python-utils 3.8.1__py2.py3-none-any.whl → 3.9.0__py2.py3-none-any.whl

python_utils/time.py

@@ -1,3 +1,23 @@
+"""
+This module provides utility functions for handling time-related operations.
+
+Functions:
+- timedelta_to_seconds: Convert a timedelta to seconds with microseconds as
+  fraction.
+- delta_to_seconds: Convert a timedelta or numeric interval to seconds.
+- delta_to_seconds_or_none: Convert a timedelta to seconds or return None.
+- format_time: Format a timestamp (timedelta, datetime, or seconds) to a
+  string.
+- timeout_generator: Generate items from an iterable until a timeout is
+  reached.
+- aio_timeout_generator: Asynchronously generate items from an iterable until a
+  timeout is reached.
+- aio_generator_timeout_detector: Detect if an async generator has not yielded
+  an element for a set amount of time.
+- aio_generator_timeout_detector_decorator: Decorator for
+  aio_generator_timeout_detector.
+"""
+
 # pyright: reportUnnecessaryIsInstance=false
 import asyncio
 import datetime
@@ -18,7 +38,7 @@ epoch = datetime.datetime(year=1970, month=1, day=1)
 
 
 def timedelta_to_seconds(delta: datetime.timedelta) -> types.Number:
-    '''Convert a timedelta to seconds with the microseconds as fraction
+    """Convert a timedelta to seconds with the microseconds as fraction.
 
     Note that this method has become largely obsolete with the
     `timedelta.total_seconds()` method introduced in Python 2.7.
@@ -32,7 +52,7 @@ def timedelta_to_seconds(delta: datetime.timedelta) -> types.Number:
     '1.000001'
     >>> '%.6f' % timedelta_to_seconds(timedelta(microseconds=1))
     '0.000001'
-    '''
+    """
     # Only convert to float if needed
     if delta.microseconds:
         total = delta.microseconds * 1e-6
@@ -43,9 +63,9 @@ def timedelta_to_seconds(delta: datetime.timedelta) -> types.Number:
     return total
 
 
-def delta_to_seconds(interval: types.delta_type) -> float:
-    '''
-    Convert a timedelta to seconds
+def delta_to_seconds(interval: types.delta_type) -> types.Number:
+    """
+    Convert a timedelta to seconds.
 
     >>> delta_to_seconds(datetime.timedelta(seconds=1))
     1
@@ -57,18 +77,19 @@ def delta_to_seconds(interval: types.delta_type) -> float:
     Traceback (most recent call last):
         ...
     TypeError: Unknown type ...
-    '''
+    """
     if isinstance(interval, datetime.timedelta):
         return timedelta_to_seconds(interval)
     elif isinstance(interval, (int, float)):
         return interval
     else:
-        raise TypeError('Unknown type %s: %r' % (type(interval), interval))
+        raise TypeError(f'Unknown type {type(interval)}: {interval!r}')
 
 
 def delta_to_seconds_or_none(
     interval: types.Optional[types.delta_type],
-) -> types.Optional[float]:
+) -> types.Optional[types.Number]:
+    """Convert a timedelta to seconds or return None."""
     if interval is None:
         return None
     else:
@@ -79,7 +100,7 @@ def format_time(
     timestamp: types.timestamp_type,
     precision: datetime.timedelta = datetime.timedelta(seconds=1),
 ) -> str:
-    '''Formats timedelta/datetime/seconds
+    """Formats timedelta/datetime/seconds.
 
     >>> format_time('1')
     '0:00:01'
@@ -100,7 +121,7 @@ def format_time(
         ...
     TypeError: Unknown type ...
 
-    '''
+    """
     precision_seconds = precision.total_seconds()
 
     if isinstance(timestamp, str):
@@ -130,7 +151,7 @@ def format_time(
 
         try:  # pragma: no cover
             dt = datetime.datetime.fromtimestamp(seconds)
-        except ValueError:  # pragma: no cover
+        except (ValueError, OSError):  # pragma: no cover
             dt = datetime.datetime.max
         return str(dt)
     elif isinstance(timestamp, datetime.date):
@@ -138,7 +159,38 @@ def format_time(
     elif timestamp is None:
         return '--:--:--'
     else:
-        raise TypeError('Unknown type %s: %r' % (type(timestamp), timestamp))
+        raise TypeError(f'Unknown type {type(timestamp)}: {timestamp!r}')
+
+
+@types.overload
+def _to_iterable(
+    iterable: types.Union[
+        types.Callable[[], types.AsyncIterable[_T]],
+        types.AsyncIterable[_T],
+    ],
+) -> types.AsyncIterable[_T]: ...
+
+
+@types.overload
+def _to_iterable(
+    iterable: types.Union[
+        types.Callable[[], types.Iterable[_T]], types.Iterable[_T]
+    ],
+) -> types.Iterable[_T]: ...
+
+
+def _to_iterable(
+    iterable: types.Union[
+        types.Iterable[_T],
+        types.Callable[[], types.Iterable[_T]],
+        types.AsyncIterable[_T],
+        types.Callable[[], types.AsyncIterable[_T]],
+    ],
+) -> types.Union[types.Iterable[_T], types.AsyncIterable[_T]]:
+    if callable(iterable):
+        return iterable()
+    else:
+        return iterable
 
 
 def timeout_generator(
@@ -146,16 +198,21 @@ def timeout_generator(
     interval: types.delta_type = datetime.timedelta(seconds=1),
     iterable: types.Union[
         types.Iterable[_T], types.Callable[[], types.Iterable[_T]]
-    ] = itertools.count,  # type: ignore
+    ] = itertools.count,  # type: ignore[assignment]
     interval_multiplier: float = 1.0,
     maximum_interval: types.Optional[types.delta_type] = None,
-):
-    '''
+) -> types.Iterable[_T]:
+    """
     Generator that walks through the given iterable (a counter by default)
     until the float_timeout is reached with a configurable float_interval
-    between items
+    between items.
+
+    This can be used to limit the time spent on a slow operation. This can be
+    useful for testing slow APIs so you get a small sample of the data in a
+    reasonable amount of time.
 
     >>> for i in timeout_generator(0.1, 0.06):
+    ...     # Put your slow code here
     ...     print(i)
     0
     1
@@ -179,20 +236,14 @@ def timeout_generator(
     0
     1
     2
-    '''
-    float_timeout: float = delta_to_seconds(timeout)
+    """
     float_interval: float = delta_to_seconds(interval)
     float_maximum_interval: types.Optional[float] = delta_to_seconds_or_none(
         maximum_interval
     )
+    iterable_ = _to_iterable(iterable)
 
-    iterable_: types.Iterable[_T]
-    if callable(iterable):
-        iterable_ = iterable()
-    else:
-        iterable_ = iterable
-
-    end = float_timeout + time.perf_counter()
+    end = delta_to_seconds(timeout) + time.perf_counter()
     for item in iterable_:
         yield item
 
@@ -201,13 +252,13 @@ def timeout_generator(
 
         time.sleep(float_interval)
 
-        interval *= interval_multiplier
+        float_interval *= interval_multiplier
         if float_maximum_interval:
             float_interval = min(float_interval, float_maximum_interval)
 
 
 async def aio_timeout_generator(
-    timeout: types.delta_type,
+    timeout: types.delta_type,  # noqa: ASYNC109
     interval: types.delta_type = datetime.timedelta(seconds=1),
     iterable: types.Union[
         types.AsyncIterable[_T], types.Callable[..., types.AsyncIterable[_T]]
@@ -215,10 +266,10 @@ async def aio_timeout_generator(
     interval_multiplier: float = 1.0,
     maximum_interval: types.Optional[types.delta_type] = None,
 ) -> types.AsyncGenerator[_T, None]:
-    '''
+    """
     Async generator that walks through the given async iterable (a counter by
     default) until the float_timeout is reached with a configurable
-    float_interval between items
+    float_interval between items.
 
     The interval_exponent automatically increases the float_timeout with each
     run. Note that if the float_interval is less than 1, 1/interval_exponent
@@ -228,20 +279,14 @@ async def aio_timeout_generator(
     Doctests and asyncio are not friends, so no examples. But this function is
     effectively the same as the `timeout_generator` but it uses `async for`
     instead.
-    '''
-    float_timeout: float = delta_to_seconds(timeout)
+    """
     float_interval: float = delta_to_seconds(interval)
     float_maximum_interval: types.Optional[float] = delta_to_seconds_or_none(
         maximum_interval
     )
+    iterable_ = _to_iterable(iterable)
 
-    iterable_: types.AsyncIterable[_T]
-    if callable(iterable):
-        iterable_ = iterable()
-    else:
-        iterable_ = iterable
-
-    end = float_timeout + time.perf_counter()
+    end = delta_to_seconds(timeout) + time.perf_counter()
     async for item in iterable_:  # pragma: no branch
         yield item
 
@@ -257,7 +302,7 @@ async def aio_timeout_generator(
 
 async def aio_generator_timeout_detector(
     generator: types.AsyncGenerator[_T, None],
-    timeout: types.Optional[types.delta_type] = None,
+    timeout: types.Optional[types.delta_type] = None,  # noqa: ASYNC109
     total_timeout: types.Optional[types.delta_type] = None,
     on_timeout: types.Optional[
         types.Callable[
@@ -272,7 +317,7 @@ async def aio_generator_timeout_detector(
     ] = exceptions.reraise,
     **on_timeout_kwargs: types.Mapping[types.Text, types.Any],
 ) -> types.AsyncGenerator[_T, None]:
-    '''
+    """
     This function is used to detect if an asyncio generator has not yielded
     an element for a set amount of time.
 
@@ -282,7 +327,7 @@ async def aio_generator_timeout_detector(
     If `on_timeout` is not specified, the exception is reraised.
     If `on_timeout` is `None`, the exception is silently ignored and the
     generator will finish as normal.
-    '''
+    """
     if total_timeout is None:
         total_timeout_end = None
     else:
@@ -295,14 +340,16 @@ async def aio_generator_timeout_detector(
     while True:
         try:
             if total_timeout_end and time.perf_counter() >= total_timeout_end:
-                raise asyncio.TimeoutError('Total timeout reached')
+                raise asyncio.TimeoutError(  # noqa: TRY301
+                    'Total timeout reached'
+                )
 
             if timeout_s:
                 yield await asyncio.wait_for(generator.__anext__(), timeout_s)
             else:
                 yield await generator.__anext__()
 
-        except asyncio.TimeoutError as exception:
+        except asyncio.TimeoutError as exception:  # noqa: PERF203
             if on_timeout is not None:
                 await on_timeout(
                     generator,
@@ -332,21 +379,21 @@ def aio_generator_timeout_detector_decorator(
         ]
     ] = exceptions.reraise,
     **on_timeout_kwargs: types.Mapping[types.Text, types.Any],
-):
-    '''
-    A decorator wrapper for aio_generator_timeout_detector.
-    '''
+) -> types.Callable[
+    [types.Callable[_P, types.AsyncGenerator[_T, None]]],
+    types.Callable[_P, types.AsyncGenerator[_T, None]],
+]:
+    """A decorator wrapper for aio_generator_timeout_detector."""
 
     def _timeout_detector_decorator(
-        generator: types.Callable[_P, types.AsyncGenerator[_T, None]]
+        generator: types.Callable[_P, types.AsyncGenerator[_T, None]],
     ) -> types.Callable[_P, types.AsyncGenerator[_T, None]]:
-        '''
-        The decorator itself.
-        '''
+        """The decorator itself."""
 
         @functools.wraps(generator)
         def wrapper(
-            *args: _P.args, **kwargs: _P.kwargs
+            *args: _P.args,
+            **kwargs: _P.kwargs,
         ) -> types.AsyncGenerator[_T, None]:
             return aio_generator_timeout_detector(
                 generator(*args, **kwargs),

python_utils/types.py

@@ -1,21 +1,38 @@
+"""
+This module provides type definitions and utility functions for type hinting.
+
+It includes:
+- Shorthand for commonly used types such as Optional and Union.
+- Type aliases for various data structures and common types.
+- Importing all types from the `typing` and `typing_extensions` modules.
+- Importing specific types from the `types` module.
+
+The module also configures Pyright to ignore wildcard import warnings.
+"""
 # pyright: reportWildcardImportFromLibrary=false
+# ruff: noqa: F405
+
 import datetime
 import decimal
-from typing_extensions import *  # type: ignore  # noqa: F403
-from typing import *  # type: ignore  # pragma: no cover  # noqa: F403
-from types import *  # type: ignore  # pragma: no cover  # noqa: F403
+from re import Match, Pattern
+from types import *  # pragma: no cover  # noqa: F403
+from typing import *  # pragma: no cover  # noqa: F403
 
 # import * does not import these in all Python versions
-from typing import Pattern, BinaryIO, IO, TextIO, Match
-
 # Quickhand for optional because it gets so much use. If only Python had
 # support for an optional type shorthand such as `SomeType?` instead of
 # `Optional[SomeType]`.
-from typing import Optional as O  # noqa
-
 # Since the Union operator is only supported for Python 3.10, we'll create a
 # shorthand for it.
-from typing import Union as U  # noqa
+from typing import (
+    IO,
+    BinaryIO,
+    Optional as O,  # noqa: N817
+    TextIO,
+    Union as U,  # noqa: N817
+)
+
+from typing_extensions import *  # type: ignore[no-redef,assignment] # noqa: F403
 
 Scope = Dict[str, Any]
 OptionalScope = O[Scope]

{python_utils-3.8.1.dist-info → python_utils-3.9.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: python-utils
-Version: 3.8.1
+Version: 3.9.0
 Summary: Python Utils is a module with some convenient utilities not included with the standard Python install
 Home-page: https://github.com/WoLpH/python-utils
 Author: Rick van Hattem
 Author-email: Wolph@wol.ph
 License: BSD
 Classifier: License :: OSI Approved :: BSD License
-Requires-Python: >3.8.0
+Requires-Python: >3.9.0
 License-File: LICENSE
 Requires-Dist: typing-extensions >3.10.0.2
 Provides-Extra: docs
@@ -17,7 +17,8 @@ Requires-Dist: python-utils ; extra == 'docs'
 Provides-Extra: loguru
 Requires-Dist: loguru ; extra == 'loguru'
 Provides-Extra: tests
-Requires-Dist: flake8 ; extra == 'tests'
+Requires-Dist: ruff ; extra == 'tests'
+Requires-Dist: pyright ; extra == 'tests'
 Requires-Dist: pytest ; extra == 'tests'
 Requires-Dist: pytest-cov ; extra == 'tests'
 Requires-Dist: pytest-mypy ; extra == 'tests'
@@ -25,6 +26,9 @@ Requires-Dist: pytest-asyncio ; extra == 'tests'
 Requires-Dist: sphinx ; extra == 'tests'
 Requires-Dist: types-setuptools ; extra == 'tests'
 Requires-Dist: loguru ; extra == 'tests'
+Requires-Dist: loguru-mypy ; extra == 'tests'
+Requires-Dist: mypy-ipython ; extra == 'tests'
+Requires-Dist: blessings ; extra == 'tests'
 
 Useful Python Utils
 ==============================================================================

python_utils-3.9.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+python_utils/__about__.py,sha256=1Hb1SMxdrOMubt1ZyHT01jFkGgI-E1kDZt4R0W9_YME,804
+python_utils/__init__.py,sha256=4s6dczKPdx5mI-cUFb_8GNP3XSlVKCaXkuW1zU2bSl0,2490
+python_utils/aio.py,sha256=9xoMe_MEtDErbEBBi8_7jVw54-zY6wv1hgGXzEL4_ww,2923
+python_utils/containers.py,sha256=SNHXfDvbt5MNL4WZc9Nj7JxyAfEV5cHba6VR5pH-K2Y,19099
+python_utils/converters.py,sha256=HyvQZzIFXuVdwGl20woiW_X_ri5PagULJOqV4jcjKUY,13906
+python_utils/decorators.py,sha256=60uq2L-2vME6TZ5AquCDrbMnFgDlZN-gQvJ8ak8kxbY,5991
+python_utils/exceptions.py,sha256=KSGLr1M3IolDaM_fp5iTsC8pek2O8lOpjIpc_5gWJnw,1135
+python_utils/formatters.py,sha256=5LqSlVAQSZQRzqUe84aYuePZS8ozp5AwS7mOaim1ZSU,5702
+python_utils/generators.py,sha256=aR9iuUZcHGElSScTtLrBMBEd1-oYgG64UMyispDwNYY,3808
+python_utils/import_.py,sha256=RO_zcslYCq19OopzZtqSugdFF5S0sP-s5FScpfjNEN4,3838
+python_utils/logger.py,sha256=BD7W1R9jEBO4_Ik28mPG5AgajOFBkJDPqJfQQQNtSn8,9984
+python_utils/loguru.py,sha256=oRuG6CHR5UvrvSdLoqrvwJLBqBbDWXZ4bvvI7Xoufh0,1357
+python_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_utils/terminal.py,sha256=iv72wsIHjqX7g18qpdbn56aGHVY4WHCRiv7O6nYdCTs,5519
+python_utils/time.py,sha256=Ad44NddQQYMNJnpvzeqIHfu-SIGgUoyUsTNJK3kkwkY,13135
+python_utils/types.py,sha256=nV_6YvNAVaTwIZHKO_G2mBo7qsyoRQ1a0vuZtR0x-SI,4096
+python_utils-3.9.0.dist-info/LICENSE,sha256=_Zrs9NZu-G6_aZT2g3Jv5_JREJQfhRNBC61EH6WDH-o,1501
+python_utils-3.9.0.dist-info/METADATA,sha256=4fEmiraBMeIaaLopsSPUVIW1pmba9nrUhr9nPpMoRVw,9827
+python_utils-3.9.0.dist-info/WHEEL,sha256=AHX6tWk3qWuce7vKLrj7lnulVHEdWoltgauo8bgCXgU,109
+python_utils-3.9.0.dist-info/top_level.txt,sha256=zAx6OfEsjJs8BEW3okSiG_j9gpkI69xWShzum6oBgKI,13
+python_utils-3.9.0.dist-info/RECORD,,

{python_utils-3.8.1.dist-info → python_utils-3.9.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.2)
+Generator: setuptools (75.1.0)
 Root-Is-Purelib: true
 Tag: py2-none-any
 Tag: py3-none-any

python_utils-3.8.1.dist-info/RECORD

@@ -1,22 +0,0 @@
-python_utils/__about__.py,sha256=B-Z6aSb4uA_SEoLmYE5XeTDruTNa5wLWBsMuOIQthSk,385
-python_utils/__init__.py,sha256=HGz7pZnS6QesK0SomLOgHnA2ldA8yFZoV3m8qwlPBks,1705
-python_utils/aio.py,sha256=HCcfWm82qzQvwMGbO5MwCiLZMW1WLT28TksLV-45d78,1291
-python_utils/compat.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_utils/containers.py,sha256=QBO0GNAJ-W_Ox0ElAjK49Rs3OtB3MAyV-Nq5dpALLKU,10802
-python_utils/converters.py,sha256=4yainms6NUWITUxq-ajJUenT5I0zN1G9XZlxpGsrUVc,11404
-python_utils/decorators.py,sha256=L6BdW94YdW4Wfgwa5aRlqYRpcAxq3Olo4mutexbKkuY,5390
-python_utils/exceptions.py,sha256=iUOxIz5OGPRJcqr6afgwuIZ-i_expS5UyMxpVs8WP3I,617
-python_utils/formatters.py,sha256=Qy7w3zua3e2UBfmkfKEMYhGBGbmYm1gZVnKjt-ZT1Wc,5015
-python_utils/generators.py,sha256=oux5qLeWdC0x8nHvF7CZ-IL7gU_gPRA06KYkvXpmWfY,2670
-python_utils/import_.py,sha256=5fTkTyX6UYVjy1Tc8R9adBmHZZEoX_ynET044B9OsPg,3165
-python_utils/logger.py,sha256=hnog07avWLkAIfMGbaP5ri_YAuv00psj-z73ha5zrH8,6371
-python_utils/loguru.py,sha256=jbAr6SVavrsH4nAicJstLtLTs50S7w5HWeWHzIOLw54,358
-python_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_utils/terminal.py,sha256=FbuYoWohCTllBheaTjOVvkbkj9gFbXF0-Zq4Z0updKA,4711
-python_utils/time.py,sha256=xc6D9MLy10tRWBof6koePIMNs7eRTOVauyitWwsOkXI,11304
-python_utils/types.py,sha256=75p6yXn771yfHHzbBWGrPCYmqqrme1beRurYWh4ltsg,3652
-python_utils-3.8.1.dist-info/LICENSE,sha256=_Zrs9NZu-G6_aZT2g3Jv5_JREJQfhRNBC61EH6WDH-o,1501
-python_utils-3.8.1.dist-info/METADATA,sha256=Txz6iPgUeWnC5HJWQuc6wwJCCBk3EBFrVvNs1jkQ54k,9650
-python_utils-3.8.1.dist-info/WHEEL,sha256=iYlv5fX357PQyRT2o6tw1bN-YcKFFHKqB_LwHO5wP-g,110
-python_utils-3.8.1.dist-info/top_level.txt,sha256=zAx6OfEsjJs8BEW3okSiG_j9gpkI69xWShzum6oBgKI,13
-python_utils-3.8.1.dist-info/RECORD,,