python-utils 4.0.1__py3-none-any.whl → 4.1.1__py3-none-any.whl

python_utils/converters.py

@@ -50,7 +50,13 @@ def to_int(
     When a (regexp) object (has a search method) is given, that will be used.
     WHen a string is given, re.compile will be run over it first
 
-    The last group of the regexp will be used as value
+    The last group of the regexp will be used as value. A regexp without a
+    group uses the whole match.
+
+    With ``regexp=True`` only the first run of digits is used. A sign, a
+    decimal point and an exponent are not part of it, so the result can differ
+    from the same call without a regexp. A regexp can only search a ``str``.
+    Any other input gives the default.
 
     >>> to_int('abc')
     0
@@ -94,6 +100,14 @@ def to_int(
     1234
     >>> to_int('abc', default=1)
     1
+    >>> to_int('abc123', regexp=r'\d+')
+    123
+    >>> to_int('-5'), to_int('-5', regexp=True)
+    (-5, 5)
+    >>> to_int('1e3'), to_int('1e3', regexp=True)
+    (0, 1)
+    >>> to_int(123), to_int(123, regexp=True)
+    (123, 0)
     >>> to_int('abc', regexp=123)
     Traceback (most recent call last):
     ...
@@ -110,7 +124,10 @@ def to_int(
 
     try:
         if regexp and input_ and (match := regexp.search(input_)):
-            input_ = match.groups()[-1]
+            # A pattern without a capture group has no last group, so the
+            # whole match is the value.
+            groups: tuple[str | None, ...] = match.groups()
+            input_ = groups[-1] if groups else match.group(0)
 
         if input_ is None:
             return default
@@ -127,10 +144,12 @@ def to_float(
     regexp: _RegexpType = None,
 ) -> _aliases.Number:
     r"""
-    Convert the given `input_` to an integer or return default.
+    Convert the given `input_` to a float or return default.
 
     When trying to convert the exceptions given in the exception parameter
-    are automatically caught and the default will be returned.
+    are automatically caught and the default will be returned. The default is
+    the int ``0``, so a failed conversion returns an ``int`` unless a float
+    is passed as default.
 
     The regexp parameter allows for a regular expression to find the digits
     in a string.
@@ -138,8 +157,31 @@ def to_float(
     When a (regexp) object (has a search method) is given, that will be used.
     When a string is given, re.compile will be run over it first
 
-    The last group of the regexp will be used as value
+    The first group of the regexp will be used as value. A regexp without a
+    group uses the whole match.
 
+    With ``regexp=True`` only the first run of digits is used, with the
+    decimal part that follows it. A sign, a leading decimal point and an
+    exponent are not part of it, so the result can differ from the same call
+    without a regexp. A regexp can only search a ``str``. Any other input
+    gives the default.
+
+    >>> to_float('abc')
+    0
+    >>> to_float('abc', default=0.0)
+    0.0
+    >>> to_float('abc1.5', regexp=r'\d+\.\d+')
+    1.5
+    >>> to_float('a1b2', regexp=r'(\d)\D(\d)')
+    1.0
+    >>> to_float('-1.5'), to_float('-1.5', regexp=True)
+    (-1.5, 1.5)
+    >>> to_float('.5'), to_float('.5', regexp=True)
+    (0.5, 5.0)
+    >>> to_float('1e3'), to_float('1e3', regexp=True)
+    (1000.0, 1.0)
+    >>> to_float(1.5), to_float(1.5, regexp=True)
+    (1.5, 0)
     >>> '%.2f' % to_float('abc')
     '0.00'
     >>> '%.2f' % to_float('1')
@@ -188,7 +230,9 @@ def to_float(
 
     try:
         if regexp and (match := regexp.search(input_)):
-            input_ = match.group(1)
+            # A pattern without a capture group has no first group, so the
+            # whole match is the value.
+            input_ = match.group(1) if match.groups() else match.group(0)
         return float(input_)
     except exception:
         return default
@@ -231,7 +275,7 @@ def to_str(
 ) -> bytes:
     """Convert objects to string, encodes to the given encoding.
 
-    :rtype: str
+    :rtype: bytes
 
     >>> to_str('a')
     b'a'
@@ -242,9 +286,9 @@ def to_str(
     >>> class Foo(object):
     ...     __str__ = lambda s: 'a'
     >>> to_str(Foo())
-    'a'
+    b'a'
     >>> to_str(Foo)
-    "<class 'python_utils.converters.Foo'>"
+    b"<class 'python_utils.converters.Foo'>"
     """
     if not isinstance(input_, bytes):
         if not hasattr(input_, 'encode'):
@@ -278,7 +322,9 @@ def scale_1024(
     if x <= 0:
         power = 0
     else:
-        power = min(int(math.log(x, 2) / 10), n_prefixes - 1)
+        # Never below zero: a number under 1 has a negative logarithm, and a
+        # negative power would index the prefixes from the wrong end.
+        power = max(min(int(math.log(x, 2) / 10), n_prefixes - 1), 0)
     scaled = float(x) / (2 ** (10 * power))
     return scaled, power
 
@@ -386,11 +432,20 @@ def remap(  # pyright: ignore[reportInconsistentOverload]
 
     If floating point remaps need to be done my suggestion is to pass at least
     one parameter as a `decimal.Decimal`. This will ensure that the output
-    from this function is accurate. I left passing `floats` for backwards
-    compatibility and there is no conversion done from float to
-    `decimal.Decimal` unless one of the passed parameters has a type of
-    `decimal.Decimal`. This will ensure that any existing code that uses this
-    function will work exactly how it has in the past.
+    from this function is accurate, as long as every value with a fraction is
+    a `decimal.Decimal` itself. A `float` is converted exactly, with its
+    binary rounding error included:
+
+    >>> remap(0.1, 0, 1, 0, decimal.Decimal(10))
+    Decimal('1.000000000000000055511151231')
+    >>> remap(decimal.Decimal('0.1'), 0, 1, 0, 10)
+    Decimal('1.0')
+
+    I left passing `floats` for backwards compatibility and there is no
+    conversion done from float to `decimal.Decimal` unless one of the passed
+    parameters has a type of `decimal.Decimal`. This will ensure that any
+    existing code that uses this function will work exactly how it has in the
+    past.
 
     Some edge cases to test
     >>> remap(1, 0, 0, 1, 2)

python_utils/decorators.py

@@ -24,6 +24,11 @@ import typing
 _T = typing.TypeVar('_T')
 _P = typing.ParamSpec('_P')
 
+#: Logger of this module. The module-level `logging.debug()` writes to the
+#: root logger and installs a handler on it when it has none, which is the
+#: application's decision to make.
+_logger: logging.Logger = logging.getLogger(__name__)
+
 
 def set_attributes(
     **kwargs: typing.Any,
@@ -74,6 +79,11 @@ def listify(
     """
     Convert any generator to a list or other type of collection.
 
+    A function that returns `None` counts as empty. With `allow_empty` that
+    gives an empty collection, and with `allow_empty=False` it raises a
+    `TypeError`. The `None` is all that `allow_empty` looks at: a generator
+    that yields nothing gives an empty collection either way.
+
     >>> @listify()
     ... def generator():
     ...     yield 1
@@ -99,6 +109,13 @@ def listify(
     ...
     TypeError: ... `allow_empty` is `False`
 
+    >>> @listify(allow_empty=False)
+    ... def generator_without_items():
+    ...     yield from ()
+
+    >>> generator_without_items()
+    []
+
     >>> @listify(collection=set)
     ... def set_generator():
     ...     yield 1
@@ -124,6 +141,7 @@ def listify(
     ) -> collections.abc.Callable[..., collections.abc.Collection[_T]]:
         """Materialize ``function``'s result into ``collection``."""
 
+        @functools.wraps(function)
         def __listify(
             *args: typing.Any, **kwargs: typing.Any
         ) -> collections.abc.Collection[_T]:
@@ -178,7 +196,7 @@ def sample(
             if random.random() < sample_rate:
                 return function(*args, **kwargs)
             else:
-                logging.debug(
+                _logger.debug(
                     'Skipped execution of %r(%r, %r) due to sampling',
                     function,
                     args,
@@ -224,13 +242,21 @@ def wraps_classmethod(
             wrapper = functools.update_wrapper(
                 wrapper,
                 wrapped,
+                # The annotations are handled below. Python 3.14 lists
+                # `__annotate__` here where older versions list
+                # `__annotations__`, so both names are left out.
                 assigned=tuple(
                     a
                     for a in functools.WRAPPER_ASSIGNMENTS
-                    if a != '__annotations__'
+                    if a not in ('__annotations__', '__annotate__')
                 ),
             )
-        if annotations := getattr(wrapped, '__annotations__', {}):
+        # A copy, because the dictionary belongs to `wrapped` and that one
+        # keeps its `self`.
+        annotations: dict[str, typing.Any] = dict(
+            getattr(wrapped, '__annotations__', {})
+        )
+        if annotations:
             # Drop `self`: the wrapper is a classmethod, so it takes no `self`.
             annotations.pop('self', None)
             wrapper.__annotations__ = annotations

python_utils/formatters.py

@@ -21,7 +21,8 @@ def camel_to_underscore(name: str) -> str:
 
     If there are existing underscores they will be collapsed with the
     to-be-added underscores. Multiple consecutive capital letters will not be
-    split except for the last one.
+    split except for the last one. A plural ``s`` that ends a word stays with
+    the acronym before it.
 
     >>> camel_to_underscore('SpamEggsAndBacon')
     'spam_eggs_and_bacon'
@@ -42,11 +43,16 @@ def camel_to_underscore(name: str) -> str:
                 # Uppercase and the previous character isn't upper/underscore?
                 # Add the underscore
                 output.append('_')
-            elif i > 3 and not c.isupper():
-                # Will return the last 3 letters to check if we are changing
-                # case
-                previous = name[i - 3 : i]
-                if previous.isalpha() and previous.isupper():
+            elif i > 1 and c.islower():
+                # Two preceding capitals are enough to mark the boundary:
+                # the final capital belongs to the following word. Only a
+                # lowercase letter ends an acronym; an underscore or digit
+                # after it leaves the acronym whole.
+                previous = name[i - 2 : i]
+                # A lone ``s`` that ends the word makes the acronym plural
+                # (``IDs``, ``URLs``) and does not start a new word.
+                plural: bool = c == 's' and not name[i + 1 : i + 2].islower()
+                if previous.isalpha() and previous.isupper() and not plural:
                     output.insert(len(output) - 1, '_')
 
         output.append(c.lower())
@@ -140,16 +146,32 @@ def timesince(
     '1 hour and 2 minutes ago'
     """
     if isinstance(dt, datetime.timedelta):
-        diff = dt
+        # A negative timedelta has negative days and positive seconds, so
+        # only its size can be described.
+        diff = abs(dt)
     else:
-        now = datetime.datetime.now()
+        # An aware datetime can only be compared with an aware current time.
+        # For a naive datetime `tzinfo` is `None`, which gives local time.
+        # A date has no `tzinfo`, and no time to subtract either. It gets
+        # the same `TypeError` from the subtraction as it always did.
+        now = datetime.datetime.now(getattr(dt, 'tzinfo', None))
         diff = abs(now - dt)
 
+    # Every unit takes its share from what the larger units left over, so a
+    # day is never counted twice.
+    years: int
+    months: int
+    weeks: int
+    days: int
+    years, days = divmod(diff.days, 365)
+    months, days = divmod(days, 30)
+    weeks, days = divmod(days, 7)
+
     periods = (
-        (diff.days / 365, 'year', 'years'),
-        (diff.days % 365 / 30, 'month', 'months'),
-        (diff.days % 30 / 7, 'week', 'weeks'),
-        (diff.days % 7, 'day', 'days'),
+        (years, 'year', 'years'),
+        (months, 'month', 'months'),
+        (weeks, 'week', 'weeks'),
+        (days, 'day', 'days'),
         (diff.seconds / 3600, 'hour', 'hours'),
         (diff.seconds % 3600 / 60, 'minute', 'minutes'),
         (diff.seconds % 60, 'second', 'seconds'),

python_utils/generators.py

@@ -23,6 +23,41 @@ from python_utils import _aliases
 _T = typing.TypeVar('_T')
 
 
+async def _cancel(pending: set[asyncio.Future[_T]]) -> None:
+    """Cancel the items that are still on their way and wait for them.
+
+    Args:
+        pending: The unfinished futures to cancel. An empty set is fine.
+    """
+    if not pending:
+        # Nothing is on its way. This also covers a batcher that is closed
+        # by the garbage collector after its event loop is gone.
+        return
+
+    for future in pending:
+        future.cancel()
+
+    # Waiting lets the cancellation reach the generator. A cancelled item is
+    # of no use to anyone. An error that the generator raises while it is
+    # being cancelled is reported to the event loop, because raising it here
+    # would replace the cancellation of the consumer.
+    outcomes: list[_T | BaseException] = await asyncio.gather(
+        *pending, return_exceptions=True
+    )
+    for outcome in outcomes:
+        # A generator that returns when it is cancelled ends its item with
+        # `StopAsyncIteration`, which is no failure.
+        if isinstance(outcome, Exception) and not isinstance(
+            outcome, StopAsyncIteration
+        ):
+            asyncio.get_running_loop().call_exception_handler(
+                {
+                    'message': 'abatcher source failed while being cancelled',
+                    'exception': outcome,
+                }
+            )
+
+
 async def abatcher(
     generator: collections.abc.AsyncGenerator[_T, None]
     | collections.abc.AsyncIterator[_T],
@@ -33,6 +68,10 @@ async def abatcher(
     Asyncio generator wrapper that returns items with a given batch size or
     interval (whichever is reached first).
 
+    Stopping early while the next item is still on its way cancels the
+    request for it. A source that is an async generator ends at that point.
+    A source with nothing on its way stays usable.
+
     Args:
         generator: The async generator or iterator to batch.
         batch_size (typing.Optional[int], optional): The number of items per
@@ -58,45 +97,54 @@ async def abatcher(
 
     next_yield: float = time.perf_counter() + interval_s
 
-    done: set[asyncio.Task[_T]]
-    pending: set[asyncio.Task[_T]] = set()
-
-    while True:
-        try:
-            done, pending = await asyncio.wait(
-                pending
-                or [
-                    asyncio.create_task(
-                        typing.cast(
-                            collections.abc.Coroutine[None, None, _T],
-                            generator.__anext__(),
-                        )
-                    ),
-                ],
-                timeout=interval_s,
-                return_when=asyncio.FIRST_COMPLETED,
-            )
+    done: set[asyncio.Future[_T]]
+    pending: set[asyncio.Future[_T]] = set()
 
-            if done:
-                batch.extend(result.result() for result in done)
+    try:
+        while True:
+            try:
+                if not pending:
+                    # Store the task before waiting for it. A cancellation
+                    # during the wait still finds it in the `finally` below.
+                    # `ensure_future` takes every awaitable, where
+                    # `create_task` insists on a coroutine.
+                    pending = {asyncio.ensure_future(generator.__anext__())}
 
-        except StopAsyncIteration:
-            if batch:
-                yield batch
+                done, pending = await asyncio.wait(
+                    pending,
+                    timeout=interval_s,
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
 
-            break
+                if done:
+                    batch.extend(result.result() for result in done)
 
-        if batch_size is not None and len(batch) == batch_size:
-            yield batch
-            batch = []
+            except StopAsyncIteration:
+                if batch:
+                    yield batch
 
-        if interval and batch and time.perf_counter() > next_yield:
-            yield batch
-            batch = []
-            # Always set the next yield time to the current time. If the
-            # loop is running slow due to blocking functions we do not
-            # want to burst too much
-            next_yield = time.perf_counter() + interval_s
+                break
+
+            if batch_size is not None and len(batch) == batch_size:
+                yield batch
+                batch = []
+                # A full batch starts a new interval as well. Otherwise the
+                # next item is flushed on its own once the old one ran out.
+                next_yield = time.perf_counter() + interval_s
+
+            if interval and batch and time.perf_counter() > next_yield:
+                yield batch
+                batch = []
+                # Always set the next yield time to the current time. If the
+                # loop is running slow due to blocking functions we do not
+                # want to burst too much
+                next_yield = time.perf_counter() + interval_s
+    finally:
+        # The consumer can stop while the next item is still on its way: an
+        # early `break`, `aclose()` or a cancellation. Without this the task
+        # keeps running, takes the next item from the generator and nobody
+        # ever receives it.
+        await _cancel(pending)
 
 
 def batcher(

python_utils/import_.py

@@ -12,6 +12,8 @@ Functions:
         relative imports and custom exception handling.
 """
 
+import importlib
+import types
 import typing
 
 from python_utils import _aliases
@@ -25,6 +27,46 @@ class DummyError(Exception):
 DummyException = DummyError
 
 
+def _get_attribute(module: typing.Any, attr: str, name: str) -> typing.Any:
+    """Return ``module.attr``, importing it as a submodule when needed.
+
+    A submodule only becomes an attribute of its parent once something has
+    imported it.
+
+    Args:
+        module: The module, or other object, to take the attribute from.
+        attr: The name of the attribute or submodule.
+        name: The full dotted name that is being imported, for the error.
+
+    Returns:
+        The attribute or the imported submodule.
+
+    Raises:
+        ImportError: When ``module`` has no such attribute or submodule. An
+            error that the submodule raises while it is imported is passed
+            on as it is, a missing dependency included.
+    """
+    try:
+        return getattr(module, attr)
+    except AttributeError as error:
+        if not isinstance(module, types.ModuleType):
+            # The same error as for a missing module, as it always was.
+            raise ImportError(  # noqa: TRY004
+                f'No module named {name}'
+            ) from error
+
+    submodule: str = f'{module.__name__}.{attr}'
+    try:
+        return importlib.import_module(submodule)
+    except ModuleNotFoundError as error:
+        missing: str = error.name or ''
+        if missing != submodule and not submodule.startswith(f'{missing}.'):
+            # The submodule exists and one of its own imports is missing.
+            raise
+
+        raise ImportError(f'No module named {name}') from error
+
+
 def import_global(  # noqa: C901
     name: str,
     modules: list[str] | None = None,
@@ -41,7 +83,11 @@ def import_global(  # noqa: C901
 
     Args:
         name (str): the name of the module to import, e.g. sys
-        modules (str): the modules to import, use None for everything
+        modules (list[str]): the names to import from the module, use None
+            for everything. An empty list also imports everything. A single
+            name needs a list as well, a bare string is read as a collection
+            of one-character names. Names that start with an underscore are
+            never imported.
         exceptions (Exception): the exception to catch, e.g. ImportError
         locals_: the `locals()` method (in case you need a different scope)
         globals_: the `globals()` method (in case you need a different scope)
@@ -82,13 +128,8 @@ def import_global(  # noqa: C901
 
             # Make sure we get the right part of a dotted import (i.e.
             # spam.eggs should return eggs, not spam)
-            try:
-                for attr in name_parts[1:]:
-                    module = getattr(module, attr)
-            except AttributeError as e:
-                raise ImportError(
-                    'No module named ' + '.'.join(name_parts)
-                ) from e
+            for attr in name_parts[1:]:
+                module = _get_attribute(module, attr, '.'.join(name_parts))
 
             # If no list of modules is given, autodetect from either __all__
             # or a dir() of the module