python-utils 4.1.3__py3-none-any.whl → 4.2.0__py3-none-any.whl

python_utils/aio.py

@@ -18,6 +18,8 @@ _T = typing.TypeVar('_T')
 _K = typing.TypeVar('_K')
 #: Value type when collecting an async iterable of pairs into a dict.
 _V = typing.TypeVar('_V')
+#: Concrete collection returned by a custom container factory.
+_C = typing.TypeVar('_C', bound=collections.abc.Collection[typing.Any])
 
 
 async def acount(
@@ -83,6 +85,15 @@ async def acontainer(
     """Overload: collect the async iterable into a ``set``."""
 
 
+@typing.overload
+async def acontainer(
+    iterable: collections.abc.AsyncIterable[_T]
+    | collections.abc.Callable[..., collections.abc.AsyncIterable[_T]],
+    container: collections.abc.Callable[[collections.abc.Iterable[_T]], _C],
+) -> _C:
+    """Overload: preserve the result type of a custom container factory."""
+
+
 async def acontainer(
     iterable: collections.abc.AsyncIterable[_T]
     | collections.abc.Callable[..., collections.abc.AsyncIterable[_T]],
@@ -96,6 +107,8 @@ async def acontainer(
     So instead of doing `[item async for item in iterable]` you can do
     `await acontainer(iterable)`.
 
+    ``container`` may be any factory that accepts the collected items, such
+    as ``frozenset`` or a custom function. Its concrete return type is kept.
     """
     iterable_: collections.abc.AsyncIterable[_T]
     if callable(iterable):

python_utils/containers.py

@@ -73,6 +73,9 @@ if typing.TYPE_CHECKING:
 KT = typing.TypeVar('KT')
 #: A type alias for a type that can be used as a value in a dictionary.
 VT = typing.TypeVar('VT')
+GD = typing.TypeVar('GD')
+#: Marks a key that ``LazyCastedDict.get`` did not find.
+_MISSING: typing.Final[object] = object()
 #: A type alias for a dictionary with keys of type KT and values of type VT.
 DT = dict[KT, VT]
 #: A type alias for the casted type of a dictionary key.
@@ -453,6 +456,8 @@ class LazyCastedDict(CastedDictBase[KT, VT]):
     [(1, 2), (3, 4), (5, 6), (7, 8)]
     >>> d[3]
     4
+    >>> d.get('3')
+    4
 
     # Casts are optional and can be disabled by passing None as the cast
     >>> d = LazyCastedDict()
@@ -507,6 +512,40 @@ class LazyCastedDict(CastedDictBase[KT, VT]):
 
         return value
 
+    @typing.overload
+    def get(self, key: typing.Any, default: None = None, /) -> VT | None:
+        """Return a cast value or ``None`` when the key is absent."""
+
+    @typing.overload
+    def get(self, key: typing.Any, default: VT, /) -> VT:
+        """Return a cast value or a default of the same type."""
+
+    @typing.overload
+    def get(self, key: typing.Any, default: GD, /) -> VT | GD:
+        """Return a cast value or an arbitrary default unchanged."""
+
+    def get(
+        self, key: typing.Any, default: typing.Any = None, /
+    ) -> typing.Any:
+        """Read a lazily cast value, returning ``default`` for missing keys.
+
+        Value conversion errors propagate just as they do for indexed reads.
+        A key that the key cast rejects cannot have been stored, so it is
+        missing. A missing default is not converted or stored, and
+        ``__missing__`` is not called, as with ``dict.get``.
+        """
+        if self._key_cast is not None:
+            try:
+                key = self._key_cast(key)
+            except (TypeError, ValueError, ArithmeticError):
+                return super().get(key, default)
+        value = super().get(key, _MISSING)
+        if value is _MISSING:
+            return default
+        if self._value_cast is not None:
+            value = self._value_cast(value)
+        return value
+
     def items(  # type: ignore[override]
         self,
     ) -> collections.abc.Generator[tuple[KT, VT], None, None]:
@@ -554,6 +593,15 @@ class UniqueList(list[HT]):
     >>> l
     [5, 10, 2, 3, 4]
 
+    Assigning an item to itself keeps it, including a NaN that does not
+    compare equal to itself:
+
+    >>> missing = float('nan')
+    >>> samples = UniqueList(missing, on_duplicate='raise')
+    >>> samples[0] = missing
+    >>> len(samples)
+    1
+
     A value that was removed or replaced can be added again:
 
     >>> l = UniqueList(1, 2, 3)
@@ -952,7 +1000,7 @@ class UniqueList(list[HT]):
         """
         old_value: HT = self[index]
         known: bool = value in self._set
-        if known and value != old_value:
+        if known and value is not old_value and value != old_value:
             if self.on_duplicate == 'raise':
                 raise ValueError(f'Duplicate value: {value}')
             else:

python_utils/converters.py

@@ -139,7 +139,7 @@ def to_int(
 
 def to_float(
     input_: str,
-    default: int = 0,
+    default: _aliases.Number = 0,
     exception: _aliases.ExceptionsType = (ValueError, TypeError),
     regexp: _RegexpType = None,
 ) -> _aliases.Number:
@@ -308,6 +308,9 @@ def scale_1024(
 
     Use to format numbers of bytes to KiB, MiB, etc.
 
+    A prefix is used only when the input reaches its power of 1024. For
+    integer inputs, the prefix is chosen before converting the value to float.
+
     >>> scale_1024(310, 3)
     (310.0, 0)
     >>> scale_1024(2048, 3)
@@ -325,6 +328,14 @@ def scale_1024(
         # 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)
+        # A logarithm can round a value just below a prefix boundary up to
+        # that boundary. Compare with the exact integer power before the
+        # input itself is rounded to float. Only an int needs the exact
+        # comparison: anything else goes through float(), as 4.1.4 did, so
+        # a numeric type without `__lt__` keeps working.
+        exact: int | float = x if isinstance(x, int) else float(x)
+        if power and exact < 2 ** (10 * power):
+            power -= 1
     scaled = float(x) / (2 ** (10 * power))
     return scaled, power
 

python_utils/generators.py

@@ -15,6 +15,7 @@ import asyncio
 import collections.abc
 import time
 import typing
+import warnings
 
 import python_utils
 from python_utils import _aliases
@@ -23,6 +24,29 @@ from python_utils import _aliases
 _T = typing.TypeVar('_T')
 
 
+def _warn_nonpositive_batch_size(
+    batch_size: int | None, interval: _aliases.delta_type | None = None
+) -> None:
+    """Warn for a size below 1 that is used without an interval.
+
+    The size itself is left alone, so 4.x keeps its results: with an
+    interval, a size of 0 still yields an empty batch for an idle interval.
+    """
+    try:
+        nonpositive: bool = batch_size is not None and batch_size < 1
+    except TypeError:
+        # A size that does not compare with 1 never matched a batch length
+        # either, so it keeps its 4.x result.
+        return
+    if nonpositive and not interval:
+        warnings.warn(
+            'batch_size must be greater than zero; sizes below 1 are '
+            'deprecated and will raise ValueError in python-utils 5.0',
+            DeprecationWarning,
+            stacklevel=3,
+        )
+
+
 async def _cancel(pending: set[asyncio.Future[_T]]) -> None:
     """Cancel the items that are still on their way and wait for them.
 
@@ -78,14 +102,22 @@ async def abatcher(
     Args:
         generator: The async generator or iterator to batch.
         batch_size (typing.Optional[int], optional): The number of items per
-            batch. Defaults to None.
+            batch. Defaults to None. With an interval, None or a value below
+            1 means no size limit. Without an interval, sizes below 1 are
+            deprecated and will raise ValueError in version 5.0.
         interval (typing.Optional[_aliases.delta_type], optional): The time
             interval to wait before yielding a batch. Defaults to None.
 
     Yields:
         collections.abc.AsyncGenerator[list[_T], None]: A generator that yields
         batches of items.
+
+    Warns:
+        DeprecationWarning: If batch_size is below 1 without an interval.
+            The existing behavior is preserved until version 5.0.
     """
+    _warn_nonpositive_batch_size(batch_size, interval)
+
     batch: list[_T] = []
 
     assert batch_size or interval, 'Must specify either batch_size or interval'
@@ -170,12 +202,20 @@ def batcher(
     Args:
         iterable (collections.abc.Iterable[_T]): The iterable to batch.
         batch_size (int, optional): The number of items per batch. Defaults
-            to 10.
+            to 10. Sizes below 1 are deprecated and will raise ValueError in
+            version 5.0. Until then, they yield all items in a single batch,
+            or no batches for an empty iterable.
 
     Yields:
         collections.abc.Generator[list[_T], None, None]: A generator that
             yields batches of items.
+
+    Warns:
+        DeprecationWarning: If batch_size is below 1. The warning is issued
+            when iteration begins, before consuming any source items.
     """
+    _warn_nonpositive_batch_size(batch_size)
+
     batch: list[_T] = []
     for item in iterable:
         batch.append(item)

python_utils/import_.py

@@ -87,7 +87,8 @@ def import_global(  # noqa: C901
             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.
+            never imported. Declared or explicitly requested names may be
+            provided lazily by the module, even if absent from ``dir()``.
         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)
@@ -96,7 +97,7 @@ def import_global(  # noqa: C901
     """
     frame = None
     name_parts: list[str] = name.split('.')
-    modules_set: set[str] = set()
+    modules_set: set[object] = set()
     try:
         # If locals_ or globals_ are not given, autodetect them by inspecting
         # the current stack
@@ -136,12 +137,25 @@ def import_global(  # noqa: C901
             if not modules:
                 modules_set = set(getattr(module, '__all__', dir(module)))
             else:
-                modules_set = set(modules).intersection(dir(module))
-
-            # Add all items in modules to the global scope
-            for k in set(dir(module)).intersection(modules_set):
-                if k and k[0] != '_':
+                modules_set = set(modules)
+
+            # Add all items in modules to the global scope. A name that dir()
+            # does not list can still be a lazy export of the module's
+            # __getattr__. It is resolved only when __all__ declares it, and
+            # skipped when that fails, as it was before lazy exports.
+            listed = set(dir(module))
+            exported: set[object] = set(getattr(module, '__all__', ()))
+            for k in modules_set:
+                if not isinstance(k, str) or not k or k[0] == '_':
+                    continue
+                if k in listed:
                     globals_[k] = getattr(module, k)
+                elif k in exported:
+                    try:
+                        globals_[k] = getattr(module, k)
+                    except Exception:
+                        # A failing lazy export was never imported before.
+                        continue
         except exceptions as e:
             return e
     finally:

python_utils/types.py

@@ -16,6 +16,7 @@ The module also configures Pyright to ignore wildcard import warnings.
 # `from python_utils.types import datetime, decimal` worked in 3.x.
 import datetime as datetime
 import decimal as decimal
+import sys
 from re import Match, Pattern
 from types import *  # pragma: no cover  # noqa: F403
 from typing import *  # pragma: no cover  # noqa: F403
@@ -175,3 +176,10 @@ __all__ = [
     'runtime_checkable',
     'timestamp_type',
 ]
+
+# Python 3.15 removed these from `typing`. Keeping them in `__all__` there
+# would make `from python_utils.types import *` raise `AttributeError`. They
+# stay at their 4.1.4 positions on older versions.
+if sys.version_info >= (3, 15):  # pragma: no cover
+    __all__.remove('ByteString')
+    __all__.remove('no_type_check_decorator')

{python_utils-4.1.3.dist-info → python_utils-4.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-utils
-Version: 4.1.3
+Version: 4.2.0
 Summary: Python Utils is a module with some convenient utilities not included with the standard Python install
 Keywords: utils,utilities,helpers,typing,typed,async,lazy-imports
 Author: Rick van Hattem
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{python_utils-4.1.3.dist-info → python_utils-4.2.0.dist-info}/RECORD

@@ -1,21 +1,21 @@
 python_utils/__about__.py,sha256=qmqR375psvJc8IPYmLhruuaiouHzhdHu7DozRZG34DM,1343
 python_utils/__init__.py,sha256=atYwTBHh2KNGdPSawwQKYCL9UolHho3L4WFxo901WDg,5958
 python_utils/_aliases.py,sha256=xf_HrYaAa9ZKZAdYYJwIen-OB3nFGI5TTUETH5_ayGY,1641
-python_utils/aio.py,sha256=64uhJ2jEF2vyTI7TQsgxWnTnrda9O23kKVFr6ebnuq0,4235
-python_utils/containers.py,sha256=kHpDgj_sAdoouL0b_CE6IHSd-qtz0KYMs_Nuiba-yEQ,37135
-python_utils/converters.py,sha256=gBOjkVYGwx1aBs7OtjFrMdQgZwI6wbOU_Rvy0u9OVFE,17273
+python_utils/aio.py,sha256=C4R3BLDINMMucuDc9-kGdGdP70ayn2Ctvjx6Q6BxJZA,4846
+python_utils/containers.py,sha256=cC-htd9QBu4hSoR5meB_10845XKQDIsoS-2mzyhW0hg,38906
+python_utils/converters.py,sha256=Klk5wOYdKzshMqaeaP6MkUKmYSjjHl8xqAcyfkEighE,17927
 python_utils/decorators.py,sha256=UyVuV7Phf8kjAt38uA-F9MFH2o8zM4t-fmlgt3KL5cc,8225
 python_utils/exceptions.py,sha256=B5wljs3Id6eQ9eRaur-ZMPGGmhHNwh9F08Sfw6fuLX4,1230
 python_utils/formatters.py,sha256=rvbeP7H3h8Hll573PZkWsJPuHETjEHpWleb0tFck8MM,7031
-python_utils/generators.py,sha256=xYGEOzMrdxOmcm2SVMOVUQh9XNzpOpaMD13opzPCp2A,6670
-python_utils/import_.py,sha256=EnVSLs7Sk1CHrkpiKdXe8i-O6XjS5hXINpjdEohRT4A,5541
+python_utils/generators.py,sha256=dw-x72fitGgdeqLS4_xyspS81ayqExvT77THHoZBA5I,8307
+python_utils/import_.py,sha256=xabWnas9OnFs7ks52D7yqpeKg8SvkBdHZIfTmuk5yJ8,6308
 python_utils/logger.py,sha256=-QuF7Zfo7pxc4nTmAPc9Pm-oz5wsxXIX7NeCnYEPI6I,14043
 python_utils/loguru.py,sha256=qsap-aXByGXsd4KrYmtneTSUARVIdeVu9xgmrFPtqSI,2696
 python_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 python_utils/terminal.py,sha256=GL3n2_rT98LBNmxy-amY-hezGKStCo-9_d_pR-TMgv8,6823
 python_utils/time.py,sha256=fZz00bpTeLXFFhbAo03LiMLWuzSJU4iPbyGSe7PYshU,16979
-python_utils/types.py,sha256=N1O2uFE2IuwVJk_vcwz8XNkf-taL-vJ5iNNG6FUXjTg,4336
-python_utils-4.1.3.dist-info/licenses/LICENSE,sha256=_Zrs9NZu-G6_aZT2g3Jv5_JREJQfhRNBC61EH6WDH-o,1501
-python_utils-4.1.3.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
-python_utils-4.1.3.dist-info/METADATA,sha256=2xDVZBIATXuKFY6WjvPP8rJRfMufLm28n5lG9dhasm0,15988
-python_utils-4.1.3.dist-info/RECORD,,
+python_utils/types.py,sha256=VQLrKDRerOuhYxMhCaWWbUBnDXJhFx_G20gIfyolgug,4682
+python_utils-4.2.0.dist-info/licenses/LICENSE,sha256=_Zrs9NZu-G6_aZT2g3Jv5_JREJQfhRNBC61EH6WDH-o,1501
+python_utils-4.2.0.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+python_utils-4.2.0.dist-info/METADATA,sha256=b5rgvrejxzOa3qwhB3eernFS84IR-8IsYM2VBliBDqo,16039
+python_utils-4.2.0.dist-info/RECORD,,

{python_utils-4.1.3.dist-info → python_utils-4.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.13.1
+Generator: uv 0.13.7
 Root-Is-Purelib: true
 Tag: py3-none-any