Erotemic / ubelt

Compare 9cb931b ... +23 ... 6f959cb

No flags found

Use flags to group coverage reports by test type, project and/or folders.
Then setup custom commit statuses and notifications for each flag.

e.g., #unittest #integration

#production #enterprise

#frontend #backend

Learn more about Codecov Flags here.

Showing 25 of 72 files from the diff.
Newly tracked file
ubelt/__main__.py changed.

@@ -95,46 +95,52 @@
Loading
95 95
    changes to an unseen value. The location
96 96
97 97
    Args:
98 -
        fname (str): A file name. This is the prefix that will be used by the
99 -
            cache. It will always be used as-is.
98 +
        fname (str):
99 +
            A file name. This is the prefix that will be used by the cache. It
100 +
            will always be used as-is.
100 101
101 -
        depends (str | List[str]): Indicate dependencies of this cache.
102 -
            If the dependencies change, then the cache is recomputed.
103 -
            New in version 0.8.9, replaces `cfgstr`.
102 +
        depends (str | List[str] | None):
103 +
            Indicate dependencies of this cache.  If the dependencies change,
104 +
            then the cache is recomputed.  New in version 0.8.9, replaces
105 +
            `cfgstr`.
104 106
105 -
        dpath (PathLike): Specifies where to save the cache. If unspecified,
106 -
            Cacher defaults to an application resource dir as given by appname.
107 +
        dpath (str | PathLike | None):
108 +
            Specifies where to save the cache. If unspecified, Cacher defaults
109 +
            to an application resource dir as given by appname.
107 110
108 111
        appname (str, default='ubelt'): Application name
109 112
            Specifies a folder in the application resource directory where to
110 113
            cache the data if ``dpath`` is not specified.
111 114
112 115
        ext (str, default='.pkl'): File extension for the cache format
113 116
114 -
        meta (object): Metadata that is also saved with the ``cfgstr``.
115 -
            This can be useful to indicate how the ``cfgstr`` was constructed.
117 +
        meta (object | None):
118 +
            Metadata that is also saved with the ``cfgstr``.  This can be
119 +
            useful to indicate how the ``cfgstr`` was constructed.
116 120
117 121
        verbose (int, default=1): Level of verbosity. Can be 1, 2 or 3.
118 122
119 123
        enabled (bool, default=True): If set to False, then the load and save
120 124
            methods will do nothing.
121 125
122 -
        log (func): Overloads the print function. Useful for sending output to
123 -
            loggers (e.g. logging.info, tqdm.tqdm.write, ...)
126 +
        log (Callable[[str], Any]):
127 +
            Overloads the print function. Useful for sending output to loggers
128 +
            (e.g. logging.info, tqdm.tqdm.write, ...)
124 129
125 -
        hasher (str): Type of hashing algorithm to use if ``cfgstr`` needs to
126 -
            be condensed to less than 49 characters.
130 +
        hasher (str, default='sha1'):
131 +
            Type of hashing algorithm to use if ``cfgstr`` needs to be
132 +
            condensed to less than 49 characters.
127 133
128 134
        protocol (int, default=-1): Protocol version used by pickle.
129 135
            Defaults to the -1 which is the latest protocol.
130 136
            If python 2 compatibility is not required, set to 2.
131 137
132 -
        cfgstr (str): Deprecated in favor of depends. Indicates the state.
133 -
            Either this string or a hash of this string will be used to
134 -
            identify the cache. A cfgstr should always be reasonably readable,
135 -
            thus it is good practice to hash extremely detailed cfgstrs to a
136 -
            reasonable readable level. Use meta to store make original details
137 -
            persist.
138 +
        cfgstr (str | None):
139 +
            Deprecated in favor of depends. Indicates the state.  Either this
140 +
            string or a hash of this string will be used to identify the cache.
141 +
            A cfgstr should always be reasonably readable, thus it is good
142 +
            practice to hash extremely detailed cfgstrs to a reasonable
143 +
            readable level. Use meta to store make original details persist.
138 144
139 145
    Example:
140 146
        >>> import ubelt as ub
@@ -253,10 +259,10 @@
Loading
253 259
        Then cfgstr will be hashed.
254 260
255 261
        Args:
256 -
            cfgstr (str, optional): overrides the instance-level cfgstr
262 +
            cfgstr (str | None): overrides the instance-level cfgstr
257 263
258 264
        Returns:
259 -
            PathLike
265 +
            str | PathLike
260 266
261 267
        Example:
262 268
            >>> # xdoctest: +REQUIRES(module:pytest)
@@ -281,7 +287,7 @@
Loading
281 287
        Check to see if the cache exists
282 288
283 289
        Args:
284 -
            cfgstr (str, optional): overrides the instance-level cfgstr
290 +
            cfgstr (str | None): overrides the instance-level cfgstr
285 291
286 292
        Returns:
287 293
            bool
@@ -329,7 +335,7 @@
Loading
329 335
        Removes the saved cache and metadata from disk
330 336
331 337
        Args:
332 -
            cfgstr (str, optional): overrides the instance-level cfgstr
338 +
            cfgstr (str | None): overrides the instance-level cfgstr
333 339
        """
334 340
        data_fpath = self.get_fpath(cfgstr)
335 341
        if self.verbose > 0:
@@ -352,7 +358,7 @@
Loading
352 358
        Like load, but returns None if the load fails due to a cache miss.
353 359
354 360
        Args:
355 -
            cfgstr (str, optional): overrides the instance-level cfgstr
361 +
            cfgstr (str | None): overrides the instance-level cfgstr
356 362
357 363
            on_error (str, default='raise'):
358 364
                How to handle non-io errors errors. Either 'raise', which
@@ -394,7 +400,7 @@
Loading
394 400
        Load the data cached and raise an error if something goes wrong.
395 401
396 402
        Args:
397 -
            cfgstr (str, optional): overrides the instance-level cfgstr
403 +
            cfgstr (str | None): overrides the instance-level cfgstr
398 404
399 405
        Returns:
400 406
            object: the cached data
@@ -470,7 +476,7 @@
Loading
470 476
471 477
        Args:
472 478
            data (object): arbitrary pickleable object to be cached
473 -
            cfgstr (str, optional): overrides the instance-level cfgstr
479 +
            cfgstr (str | None): overrides the instance-level cfgstr
474 480
475 481
        Example:
476 482
            >>> from ubelt.util_cache import *  # NOQA
@@ -524,7 +530,7 @@
Loading
524 530
        Wraps around a function. A cfgstr must be stored in the base cacher.
525 531
526 532
        Args:
527 -
            func (callable): function that will compute data on cache miss
533 +
            func (Callable): function that will compute data on cache miss
528 534
            *args: passed to func
529 535
            **kwargs: passed to func
530 536
@@ -592,21 +598,10 @@
Loading
592 598
        fname (str):
593 599
            Name of the stamp file
594 600
595 -
        cfgstr (str):
596 -
            Configuration associated with the stamped computation.  A common
597 -
            pattern is to call :func:`ubelt.hash_data` on a dependency list.
598 -
599 -
            Deprecated in favor of depends. Indicates the state.
600 -
            Either this string or a hash of this string will be used to
601 -
            identify the cache. A cfgstr should always be reasonably readable,
602 -
            thus it is good practice to hash extremely detailed cfgstrs to a
603 -
            reasonable readable level. Use meta to store make original details
604 -
            persist.
605 -
606 -
        dpath (PathLike):
601 +
        dpath (str | PathLike | None):
607 602
            Where to store the cached stamp file
608 603
609 -
        product (PathLike or Sequence[PathLike], optional):
604 +
        product (str | PathLike | Sequence[str | PathLike] | None):
610 605
            Path or paths that we expect the computation to produce. If
611 606
            specified the hash of the paths are stored.
612 607
@@ -621,13 +616,27 @@
Loading
621 616
        enabled (bool, default=True):
622 617
            if False, expired always returns True
623 618
624 -
        depends (str | List[str]): Indicate dependencies of this cache.
625 -
            If the dependencies change, then the cache is recomputed.
626 -
            New to CacheStamp in version 0.9.2, replaces `cfgstr`.
619 +
        depends (str | List[str] | None):
620 +
            Indicate dependencies of this cache.  If the dependencies change,
621 +
            then the cache is recomputed.  New to CacheStamp in version 0.9.2,
622 +
            replaces `cfgstr`.
623 +
624 +
        meta (object | None):
625 +
            Metadata that is also saved with the ``cfgstr``.  This can be
626 +
            useful to indicate how the ``cfgstr`` was constructed.  New to
627 +
            CacheStamp in version 0.9.2.
627 628
628 -
        meta (object): Metadata that is also saved with the ``cfgstr``.
629 -
            This can be useful to indicate how the ``cfgstr`` was constructed.
630 -
            New to CacheStamp in version 0.9.2.
629 +
        cfgstr (str | None):
630 +
            DEPRECATED in favor or depends.
631 +
            Configuration associated with the stamped computation.  A common
632 +
            pattern is to call :func:`ubelt.hash_data` on a dependency list.
633 +
634 +
            Deprecated in favor of depends. Indicates the state.
635 +
            Either this string or a hash of this string will be used to
636 +
            identify the cache. A cfgstr should always be reasonably readable,
637 +
            thus it is good practice to hash extremely detailed cfgstrs to a
638 +
            reasonable readable level. Use meta to store make original details
639 +
            persist.
631 640
632 641
    TODO:
633 642
        - [ ] expiration time delta or date time (also remember when renewed)
@@ -703,10 +712,10 @@
Loading
703 712
        expected result of that computation still exists.
704 713
705 714
        Args:
706 -
            cfgstr (str, optional): overrides the instance-level cfgstr
715 +
            cfgstr (str | None): overrides the instance-level cfgstr
707 716
708 -
            product (PathLike or Sequence[PathLike], optional): override the
709 -
                default product if specified
717 +
            product (str | PathLike | Sequence[str | PathLike] | None):
718 +
                override the default product if specified
710 719
711 720
        Returns:
712 721
            bool: True if the stamp is invalid or does not exist.
@@ -807,12 +816,3 @@
Loading
807 816
    fmtstr = ('{:.' + str(precision) + 'f}{}')
808 817
    res = fmtstr.format(num_unit, unit)
809 818
    return res
810 -
811 -
812 -
if __name__ == '__main__':
813 -
    """
814 -
    CommandLine:
815 -
        python ~/code/ubelt/ubelt/util_cache.py Cacher
816 -
    """
817 -
    import xdoctest
818 -
    xdoctest.doctest_module(__file__)

@@ -69,7 +69,8 @@
Loading
69 69
        total (int): hints about the length of the input
70 70
71 71
    Yields:
72 -
        List[T]: subsequent non-overlapping chunks of the input items
72 +
        List[T]:
73 +
            subsequent non-overlapping chunks of the input items
73 74
74 75
    References:
75 76
        http://stackoverflow.com/questions/434287/iterate-over-a-list-in-chunks
@@ -228,22 +229,22 @@
Loading
228 229
    specifying a default element if ``items`` is an iterable of dictionaries.
229 230
230 231
    Args:
231 -
        items (Sequence[V] | Mapping[K, V]):
232 +
        items (Sequence[VT] | Mapping[KT, VT]):
232 233
            An indexable object to select items from
233 234
234 -
        indices (Iterable[int | K]):
235 +
        indices (Iterable[int | KT]):
235 236
            sequence of indexes into ``items``
236 237
237 238
        default (Any, default=NoParam):
238 239
            if specified ``items`` must support the ``get`` method.
239 240
240 241
    Yeilds:
241 -
        V: a selected item within the list
242 +
        VT: a selected item within the list
242 243
243 244
    SeeAlso:
244 245
        :func:`ubelt.dict_subset`
245 246
246 -
    Notes:
247 +
    Note:
247 248
        ``ub.take(items, indices)`` is equivalent to
248 249
        ``(items[i] for i in indices)`` when ``default`` is unspecified.
249 250
@@ -330,13 +331,14 @@
Loading
330 331
    Generates unique items in the order they appear.
331 332
332 333
    Args:
333 -
        items (Iterable[A]): list of items
334 +
        items (Iterable[T]): list of items
334 335
335 -
        key (Callable[[A], B], default=None): custom normalization function.
336 +
        key (Callable[[T], Any], default=None): custom normalization function.
336 337
            If specified returns items where ``key(item)`` is unique.
337 338
338 339
    Yields:
339 -
        A: a unique item from the input sequence
340 +
        T:
341 +
            a unique item from the input sequence
340 342
341 343
    Example:
342 344
        >>> import ubelt as ub
@@ -372,9 +374,9 @@
Loading
372 374
    Returns indices corresponding to the first instance of each unique item.
373 375
374 376
    Args:
375 -
        items (Sequence[V]): indexable collection of items
377 +
        items (Sequence[VT]): indexable collection of items
376 378
377 -
        key (Callable[[V], Any], default=None): custom normalization function.
379 +
        key (Callable[[VT], Any], default=None): custom normalization function.
378 380
            If specified returns items where ``key(item)`` is unique.
379 381
380 382
    Returns:
@@ -400,10 +402,11 @@
Loading
400 402
    unique item.
401 403
402 404
    Args:
403 -
        items (Sequence): indexable collection of items
405 +
        items (Sequence[VT]): indexable collection of items
404 406
405 -
        key (Callable[[V], Any], default=None): custom normalization function.
406 -
            If specified returns items where ``key(item)`` is unique.
407 +
        key (Callable[[VT], Any] | None, default=None): custom normalization
408 +
            function.  If specified returns items where ``key(item)`` is
409 +
            unique.
407 410
408 411
    Returns:
409 412
        List[bool] : flags the items that are unique
@@ -538,10 +541,10 @@
Loading
538 541
    Determine if all items in a sequence are the same
539 542
540 543
    Args:
541 -
        iterable (Iterable[A]):
544 +
        iterable (Iterable[T]):
542 545
            items to determine if they are all the same
543 546
544 -
        eq (Callable[[A, A], bool], default=operator.eq):
547 +
        eq (Callable[[T, T], bool], default=operator.eq):
545 548
            function used to test for equality
546 549
547 550
    Returns:
@@ -580,15 +583,16 @@
Loading
580 583
    and works on both lists and dictionaries.
581 584
582 585
    Args:
583 -
        indexable (Iterable[B] | Mapping[A, B]): indexable to sort by
586 +
        indexable (Iterable[VT] | Mapping[KT, VT]): indexable to sort by
584 587
585 -
        key (Callable[[A], B], default=None):
588 +
        key (Callable[[VT], VT] | None, default=None):
586 589
            customizes the ordering of the indexable
587 590
588 591
        reverse (bool, default=False): if True returns in descending order
589 592
590 593
    Returns:
591 -
        List[int]: indices - list of indices such that sorts the indexable
594 +
        List[int] | List[KT]:
595 +
            indices - list of indices that sorts the indexable
592 596
593 597
    Example:
594 598
        >>> import ubelt as ub
@@ -636,13 +640,13 @@
Loading
636 640
    and works on both lists and dictionaries.
637 641
638 642
    Args:
639 -
        indexable (Iterable[B] | Mapping[A, B]): indexable to sort by
643 +
        indexable (Iterable[VT] | Mapping[KT, VT]): indexable to sort by
640 644
641 -
        key (Callable[[A], B], default=None):
645 +
        key (Callable[[VT], Any], default=None):
642 646
            customizes the ordering of the indexable
643 647
644 648
    Returns:
645 -
        int: the index of the item with the maximum value.
649 +
        int | KT: the index of the item with the maximum value.
646 650
647 651
    Example:
648 652
        >>> import ubelt as ub
@@ -672,13 +676,13 @@
Loading
672 676
    and works on both lists and dictionaries.
673 677
674 678
    Args:
675 -
        indexable (Iterable[B] | Mapping[A, B]): indexable to sort by
679 +
        indexable (Iterable[VT] | Mapping[KT, VT]): indexable to sort by
676 680
677 -
        key (Callable[[A], B], default=None):
681 +
        key (Callable[[VT], VT], default=None):
678 682
            customizes the ordering of the indexable
679 683
680 684
    Returns:
681 -
        int: the index of the item with the minimum value.
685 +
        int | KT: the index of the item with the minimum value.
682 686
683 687
    Example:
684 688
        >>> import ubelt as ub
@@ -706,7 +710,7 @@
Loading
706 710
    the next element is exhausted (i.e. a pop operation).
707 711
708 712
    Args:
709 -
        iterable (List[T]): an iterable
713 +
        iterable (Iterable[T]): an iterable
710 714
711 715
    Returns:
712 716
        T: item - the first item of ordered sequence, a popped item from an

@@ -121,19 +121,22 @@
Loading
121 121
    Imports a module via its path
122 122
123 123
    Args:
124 -
        modpath (PathLike): path to the module on disk or within a zipfile.
125 -
        index (int): location at which we modify PYTHONPATH if necessary.
126 -
            If your module name does not conflict, the safest value is -1,
127 -
            However, if there is a conflict, then use an index of 0.
128 -
            The default may change to 0 in the future.
124 +
        modpath (str | PathLike):
125 +
            Path to the module on disk or within a zipfile.
126 +
127 +
        index (int):
128 +
            Location at which we modify PYTHONPATH if necessary.  If your
129 +
            module name does not conflict, the safest value is -1, However, if
130 +
            there is a conflict, then use an index of 0.  The default may
131 +
            change to 0 in the future.
129 132
130 133
    Returns:
131 -
        module: the imported module
134 +
        ModuleType: the imported module
132 135
133 136
    References:
134 137
        https://stackoverflow.com/questions/67631/import-module-given-path
135 138
136 -
    Notes:
139 +
    Note:
137 140
        If the module is part of a package, the package will be imported first.
138 141
        These modules may cause problems when reloading via IPython magic
139 142
@@ -240,7 +243,7 @@
Loading
240 243
        modname (str):  module name
241 244
242 245
    Returns:
243 -
        module: module
246 +
        ModuleType: module
244 247
245 248
    Example:
246 249
        >>> # test with modules that wont be imported in normal circumstances
@@ -320,13 +323,15 @@
Loading
320 323
321 324
    Args:
322 325
        modname (str): name of module to find
323 -
        sys_path (List[PathLike], default=None):
326 +
327 +
        sys_path (List[str | PathLike] | None, default=None):
324 328
            if specified overrides ``sys.path``
325 -
        exclude (List[PathLike], default=None):
329 +
330 +
        exclude (List[str | PathLike] | None, default=None):
326 331
            list of directory paths. if specified prevents these directories
327 332
            from being searched.
328 333
329 -
    Notes:
334 +
    Note:
330 335
        This is much slower than the pkgutil mechanisms.
331 336
332 337
    Example:
@@ -537,16 +542,16 @@
Loading
537 542
    Normalizes __init__ and __main__ paths.
538 543
539 544
    Args:
540 -
        modpath (PathLike): path to a module
545 +
        modpath (str | PathLike): path to a module
541 546
        hide_init (bool, default=True): if True, always return package modules
542 547
           as __init__.py files otherwise always return the dpath.
543 548
        hide_main (bool, default=False): if True, always strip away main files
544 549
            otherwise ignore __main__.py.
545 550
546 551
    Returns:
547 -
        PathLike: a normalized path to the module
552 +
        str | PathLike: a normalized path to the module
548 553
549 -
    Notes:
554 +
    Note:
550 555
        Adds __init__ if reasonable, but only removes __main__ by default
551 556
552 557
    Example:
@@ -671,7 +676,7 @@
Loading
671 676
            directory and does not contain an ``__init__.py`` file.
672 677
673 678
    Returns:
674 -
        tuple: (directory, rel_modpath)
679 +
        Tuple[str, str]: (directory, rel_modpath)
675 680
676 681
    Raises:
677 682
        ValueError: if modpath does not exist or is not a package

@@ -46,13 +46,15 @@
Loading
46 46
    simply remind the developer that there might be a better way.
47 47
48 48
    Args:
49 -
        self (T): instance to inject a function into
49 +
        self (T):
50 +
            Instance to inject a function into.
50 51
51 -
        func (Callable[[T, ...], Any]):
52 -
            the function to inject (must contain an arg for self)
52 +
        func (Callable[..., Any]):
53 +
            The function to inject (must contain an arg for self).
53 54
54 -
        name (str, default=None): name of the method. optional. If not
55 -
            specified the name of the function is used.
55 +
        name (str, default=None):
56 +
            Name of the method. optional. If not specified the name of the
57 +
            function is used.
56 58
57 59
    Example:
58 60
        >>> import ubelt as ub
@@ -82,7 +84,7 @@
Loading
82 84
    Take the subset of dict items that can be passed to function as kwargs
83 85
84 86
    Args:
85 -
        config (dict):
87 +
        config (Dict[str, Any]):
86 88
            a flat configuration dictionary
87 89
88 90
        func (Callable):
@@ -93,7 +95,7 @@
Loading
93 95
            unbound method to avoid the ``self`` argument.
94 96
95 97
    Returns:
96 -
        dict :
98 +
        Dict[str, Any] :
97 99
            a subset of ``config`` that only contains items compatible with the
98 100
            signature of ``func``.
99 101

@@ -46,9 +46,9 @@
Loading
46 46
    cases. For more details see notes in :mod:`ubelt._win32_links`.
47 47
48 48
    Args:
49 -
        path (PathLike): path to real file or directory
49 +
        path (str | PathLike): path to real file or directory
50 50
51 -
        link_path (PathLike): path to desired location for symlink
51 +
        link_path (str | PathLike): path to desired location for symlink
52 52
53 53
        overwrite (bool, default=False): overwrite existing symlinks.
54 54
            This will not overwrite real files on systems with proper symlinks.
@@ -59,7 +59,7 @@
Loading
59 59
        verbose (int, default=0): verbosity level
60 60
61 61
    Returns:
62 -
        PathLike: link path
62 +
        str | PathLike: link path
63 63
64 64
    Example:
65 65
        >>> import ubelt as ub

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Click to load this diff.
Loading diff...

Learn more Showing 2 files with coverage changes found.

New file ubelt/__main__.py
New
Loading file...
New file ubelt/_win32_links.py
New
Loading file...

25 Commits

Hiding 7 contexual commits
Hiding 2 contexual commits
-1
-1
Hiding 4 contexual commits
-1
+3
-4
Hiding 4 contexual commits
+12
+8
+4
Files Coverage
ubelt -7.04% 92.96%
Project Totals (31 files) 92.96%
Loading