python-utils 2.5.6__py3-none-any.whl → 4.0.0__py3-none-any.whl

python_utils/__about__.py

@@ -1,9 +1,37 @@
-__package_name__ = 'python-utils'
-__version__ = '2.5.6'
-__author__ = 'Rick van Hattem'
-__author_email__ = 'Wolph@wol.ph'
-__description__ = (
+"""
+This module contains metadata about the `python-utils` package.
+
+Attributes:
+    __package_name__ (str): The name of the package.
+    __author__ (str): The author of the package.
+    __author_email__ (str): The email of the author.
+    __description__ (str): A brief description of the package.
+    __url__ (str): The URL of the package's repository.
+    __version__ (str): The current version, read from the installed metadata.
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+#: Distribution name as published on PyPI.
+__package_name__: str = 'python-utils'
+#: Primary author's name.
+__author__: str = 'Rick van Hattem'
+#: Primary author's contact email.
+__author_email__: str = 'Wolph@wol.ph'
+#: One-line description of the package.
+__description__: str = (
     'Python Utils is a module with some convenient utilities not included '
-    'with the standard Python install')
-__url__ = 'https://github.com/WoLpH/python-utils'
+    'with the standard Python install'
+)
+#: Canonical project/repository URL.
+__url__: str = 'https://github.com/WoLpH/python-utils'
 
+try:
+    # `[project].version` in pyproject.toml is the single source of truth;
+    # read it back at runtime so the two never drift.
+    __version__: str = metadata.version(__package_name__)
+except metadata.PackageNotFoundError:  # pragma: no cover
+    # Not installed (e.g. running straight from a source checkout).
+    __version__ = '0.0.0'

python_utils/__init__.py

@@ -0,0 +1,241 @@
+"""
+This module initializes the `python_utils` package by importing various
+submodules and functions.
+
+Imports are performed lazily (PEP 562): nothing is imported when you ``import
+python_utils``; each submodule/function is loaded on first access. This keeps
+``import python_utils`` cheap and, in particular, avoids eagerly importing
+``asyncio`` (via the async helpers) for consumers that only need the
+synchronous utilities.
+
+Submodules::
+
+    aio
+    converters
+    decorators
+    formatters
+    generators
+    import_
+    logger
+    terminal
+    time
+    types
+
+Functions::
+
+    acount
+    remap
+    scale_1024
+    to_float
+    to_int
+    to_str
+    to_unicode
+    listify
+    set_attributes
+    raise_exception
+    reraise
+    camel_to_underscore
+    timesince
+    abatcher
+    batcher
+    import_global
+    get_terminal_size
+    aio_generator_timeout_detector
+    aio_generator_timeout_detector_decorator
+    aio_timeout_generator
+    delta_to_seconds
+    delta_to_seconds_or_none
+    format_time
+    timedelta_to_seconds
+    timeout_generator
+
+Classes::
+
+    CastedDict
+    LazyCastedDict
+    UniqueList
+    Logged
+    LoggerBase
+"""
+
+import importlib as _importlib
+import typing as _typing
+
+if _typing.TYPE_CHECKING:  # pragma: no cover
+    # Eager imports for type checkers only; the runtime equivalents are loaded
+    # lazily by ``__getattr__`` below. Names appear in ``__all__`` so they are
+    # treated as re-exports (not unused imports).
+    from . import (
+        aio,
+        converters,
+        decorators,
+        formatters,
+        generators,
+        import_,
+        logger,
+        terminal,
+        time,
+        types,
+    )
+    from .__about__ import __version__
+    from .aio import acount
+    from .containers import CastedDict, LazyCastedDict, UniqueList
+    from .converters import (
+        remap,
+        scale_1024,
+        to_float,
+        to_int,
+        to_str,
+        to_unicode,
+    )
+    from .decorators import listify, set_attributes
+    from .exceptions import raise_exception, reraise
+    from .formatters import camel_to_underscore, timesince
+    from .generators import abatcher, batcher
+    from .import_ import import_global
+    from .logger import Logged, LoggerBase
+    from .terminal import get_terminal_size
+    from .time import (
+        aio_generator_timeout_detector,
+        aio_generator_timeout_detector_decorator,
+        aio_timeout_generator,
+        delta_to_seconds,
+        delta_to_seconds_or_none,
+        format_time,
+        timedelta_to_seconds,
+        timeout_generator,
+    )
+
+#: Submodules that can be accessed as ``python_utils.<name>``.
+_SUBMODULES: frozenset[str] = frozenset(
+    {
+        'aio',
+        'containers',
+        'converters',
+        'decorators',
+        'exceptions',
+        'formatters',
+        'generators',
+        'import_',
+        'logger',
+        'terminal',
+        'time',
+        'types',
+    }
+)
+
+#: Exported name -> submodule it lives in.
+_NAME_TO_MODULE: dict[str, str] = {
+    '__version__': '__about__',
+    'acount': 'aio',
+    'CastedDict': 'containers',
+    'LazyCastedDict': 'containers',
+    'UniqueList': 'containers',
+    'remap': 'converters',
+    'scale_1024': 'converters',
+    'to_float': 'converters',
+    'to_int': 'converters',
+    'to_str': 'converters',
+    'to_unicode': 'converters',
+    'listify': 'decorators',
+    'set_attributes': 'decorators',
+    'raise_exception': 'exceptions',
+    'reraise': 'exceptions',
+    'camel_to_underscore': 'formatters',
+    'timesince': 'formatters',
+    'abatcher': 'generators',
+    'batcher': 'generators',
+    'import_global': 'import_',
+    'Logged': 'logger',
+    'LoggerBase': 'logger',
+    'get_terminal_size': 'terminal',
+    'aio_generator_timeout_detector': 'time',
+    'aio_generator_timeout_detector_decorator': 'time',
+    'aio_timeout_generator': 'time',
+    'delta_to_seconds': 'time',
+    'delta_to_seconds_or_none': 'time',
+    'format_time': 'time',
+    'timedelta_to_seconds': 'time',
+    'timeout_generator': 'time',
+}
+
+
+def __getattr__(name: str) -> _typing.Any:
+    """Lazily import a submodule or exported name on first access (PEP 562).
+
+    Args:
+        name: Attribute requested on the ``python_utils`` package.
+
+    Returns:
+        The imported submodule or object. It is cached in ``globals()`` so
+        this hook runs only once per name.
+
+    Raises:
+        AttributeError: If ``name`` is not a known submodule or export.
+    """
+    if name in _SUBMODULES:
+        module = _importlib.import_module(f'.{name}', __name__)
+    elif name in _NAME_TO_MODULE:
+        module = _importlib.import_module(
+            f'.{_NAME_TO_MODULE[name]}', __name__
+        )
+        value = getattr(module, name)
+        globals()[name] = value  # cache so __getattr__ runs only once
+        return value
+    else:
+        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+    globals()[name] = module
+    return module
+
+
+def __dir__() -> list[str]:
+    """List all eager and lazily-available names (for tab-completion)."""
+    return sorted(
+        set(globals()) | set(__all__) | _SUBMODULES | set(_NAME_TO_MODULE)
+    )
+
+
+__all__ = [
+    'CastedDict',
+    'LazyCastedDict',
+    'Logged',
+    'LoggerBase',
+    'UniqueList',
+    '__version__',
+    'abatcher',
+    'acount',
+    'aio',
+    'aio_generator_timeout_detector',
+    'aio_generator_timeout_detector_decorator',
+    'aio_timeout_generator',
+    'batcher',
+    'camel_to_underscore',
+    'converters',
+    'decorators',
+    'delta_to_seconds',
+    'delta_to_seconds_or_none',
+    'format_time',
+    'formatters',
+    'generators',
+    'get_terminal_size',
+    'import_',
+    'import_global',
+    'listify',
+    'logger',
+    'raise_exception',
+    'remap',
+    'reraise',
+    'scale_1024',
+    'set_attributes',
+    'terminal',
+    'time',
+    'timedelta_to_seconds',
+    'timeout_generator',
+    'timesince',
+    'to_float',
+    'to_int',
+    'to_str',
+    'to_unicode',
+    'types',
+]

python_utils/_aliases.py

@@ -0,0 +1,53 @@
+"""Lightweight, stdlib-only type aliases shared across python_utils.
+
+These live here (rather than in ``python_utils.types``) so internal modules can
+import them without dragging in ``typing_extensions``. ``python_utils.types``
+re-exports everything defined here, so the public names are unchanged.
+"""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+from typing import Any
+
+__all__ = [
+    'DecimalNumber',
+    'ExceptionType',
+    'ExceptionsType',
+    'Number',
+    'OptionalScope',
+    'Scope',
+    'StringTypes',
+    'delta_type',
+    'timestamp_type',
+]
+
+#: A namespace mapping, e.g. ``locals()``/``globals()`` (name -> value).
+Scope = dict[str, Any]
+#: A :data:`Scope`, or ``None`` when no namespace is supplied.
+OptionalScope = Scope | None
+#: Any plain (non-decimal) number: an ``int`` or a ``float``.
+Number = int | float
+#: A :data:`Number` or a :class:`decimal.Decimal`, for precise arithmetic.
+DecimalNumber = Number | decimal.Decimal
+#: An exception class (not an instance), e.g. ``ValueError``.
+ExceptionType = type[Exception]
+#: One exception class or a tuple of them, as accepted by ``except``.
+ExceptionsType = tuple[ExceptionType, ...] | ExceptionType
+#: Text-like data: ``str`` or ``bytes``.
+StringTypes = str | bytes
+
+#: A time interval expressed as a ``timedelta`` or a number of seconds.
+delta_type = datetime.timedelta | int | float
+#: Anything :func:`~python_utils.time.format_time` can render: a duration, a
+#: date/datetime, a numeric/str timestamp, or ``None``.
+timestamp_type = (
+    datetime.timedelta
+    | datetime.date
+    | datetime.datetime
+    | str
+    | int
+    | float
+    | None
+)

python_utils/aio.py

@@ -0,0 +1,133 @@
+"""Asyncio equivalents of common synchronous helpers.
+
+These bring ``itertools``-style ergonomics to ``async for``: ``acount`` is an
+async counter, while ``acontainer`` and ``adict`` collect an async iterable
+into a concrete container.
+"""
+
+import asyncio
+import collections.abc
+import itertools
+import typing
+
+#: Numeric type (``int`` or ``float``) produced by ``acount``.
+_N = typing.TypeVar('_N', int, float)
+#: Element type of the async iterables being consumed.
+_T = typing.TypeVar('_T')
+#: Key type when collecting an async iterable of pairs into a dict.
+_K = typing.TypeVar('_K')
+#: Value type when collecting an async iterable of pairs into a dict.
+_V = typing.TypeVar('_V')
+
+
+async def acount(
+    start: _N = 0,
+    step: _N = 1,
+    delay: float = 0,
+    stop: _N | None = None,
+) -> collections.abc.AsyncIterator[_N]:
+    """Async equivalent of ``itertools.count()``.
+
+    Counts from ``start`` in steps of ``step``, sleeping ``delay`` seconds
+    between values, and stops once ``stop`` (when given) is reached.
+
+    Args:
+        start: First value to yield.
+        step: Amount added between successive values.
+        delay: Seconds to ``asyncio.sleep`` between yields.
+        stop: Exclusive upper bound; ``None`` counts forever.
+
+    Yields:
+        The successive counter values.
+
+    >>> async def demo():
+    ...     return [i async for i in acount(stop=3)]
+    >>> asyncio.run(demo())
+    [0, 1, 2]
+    """
+    for item in itertools.count(start, step):  # pragma: no branch
+        if stop is not None and item >= stop:
+            break
+
+        yield item
+        await asyncio.sleep(delay)
+
+
+@typing.overload
+async def acontainer(
+    iterable: collections.abc.AsyncIterable[_T]
+    | collections.abc.Callable[..., collections.abc.AsyncIterable[_T]],
+    container: type[tuple[_T, ...]],
+) -> tuple[_T, ...]:
+    """Overload: collect the async iterable into a ``tuple``."""
+
+
+@typing.overload
+async def acontainer(
+    iterable: collections.abc.AsyncIterable[_T]
+    | collections.abc.Callable[..., collections.abc.AsyncIterable[_T]],
+    container: type[list[_T]] = list,
+) -> list[_T]:
+    """Overload: collect the async iterable into a ``list`` (the default)."""
+
+
+@typing.overload
+async def acontainer(
+    iterable: collections.abc.AsyncIterable[_T]
+    | collections.abc.Callable[..., collections.abc.AsyncIterable[_T]],
+    container: type[set[_T]],
+) -> set[_T]:
+    """Overload: collect the async iterable into a ``set``."""
+
+
+async def acontainer(
+    iterable: collections.abc.AsyncIterable[_T]
+    | collections.abc.Callable[..., collections.abc.AsyncIterable[_T]],
+    container: collections.abc.Callable[
+        [collections.abc.Iterable[_T]], collections.abc.Collection[_T]
+    ] = list,
+) -> collections.abc.Collection[_T]:
+    """
+    Asyncio version of list()/set()/tuple()/etc() using an async for loop.
+
+    So instead of doing `[item async for item in iterable]` you can do
+    `await acontainer(iterable)`.
+
+    """
+    iterable_: collections.abc.AsyncIterable[_T]
+    if callable(iterable):
+        iterable_ = iterable()
+    else:
+        iterable_ = iterable
+
+    items: list[_T] = [item async for item in iterable_]
+
+    return container(items)
+
+
+async def adict(
+    iterable: collections.abc.AsyncIterable[tuple[_K, _V]]
+    | collections.abc.Callable[
+        ..., collections.abc.AsyncIterable[tuple[_K, _V]]
+    ],
+    container: collections.abc.Callable[
+        [collections.abc.Iterable[tuple[_K, _V]]],
+        collections.abc.Mapping[_K, _V],
+    ] = dict,
+) -> collections.abc.Mapping[_K, _V]:
+    """
+    Asyncio version of dict() using an async for loop.
+
+    So instead of doing `{key: value async for key, value in iterable}` you
+    can do `await adict(iterable)`.
+
+    """
+    iterable_: collections.abc.AsyncIterable[tuple[_K, _V]]
+    if callable(iterable):
+        iterable_ = iterable()
+    else:
+        iterable_ = iterable
+
+    items: list[tuple[_K, _V]] = [item async for item in iterable_]
+
+    return container(items)