python-utils 4.1.3__tar.gz → 4.2.0__tar.gz

{python_utils-4.1.3 → python_utils-4.2.0}/PKG-INFO

@@ -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 → python_utils-4.2.0}/_python_utils_tests/test_aio.py

@@ -114,3 +114,25 @@ async def test_adict() -> None:
     assert await aio.adict(async_gen()) == {1: 2, 3: 4, 5: 6}
     assert await aio.adict(empty_gen) == {}
     assert await aio.adict(empty_gen()) == {}
+
+
+@pytest.mark.asyncio
+async def test_acontainer_custom_container_types() -> None:
+    """Accept custom container factories without losing their return type."""
+    from collections.abc import AsyncIterator, Iterable
+
+    from typing_extensions import assert_type
+
+    async def numbers() -> AsyncIterator[int]:
+        yield 1
+        yield 2
+
+    def summarize(items: Iterable[int]) -> dict[str, int]:
+        return {'total': sum(items)}
+
+    frozen = await aio.acontainer(numbers(), frozenset)
+    assert_type(frozen, frozenset[int])
+    assert frozen == frozenset({1, 2})
+    summary = await aio.acontainer(numbers, summarize)
+    assert_type(summary, dict[str, int])
+    assert summary == {'total': 3}

{python_utils-4.1.3 → python_utils-4.2.0}/_python_utils_tests/test_containers.py

@@ -1209,3 +1209,137 @@ def test_unique_list_failed_assignment_takes_membership_back() -> None:
     assert 1 in values
     values.append(3)
     assert values == [1, 2, 3]
+
+
+@pytest.mark.parametrize('index', [0, -1])
+@pytest.mark.parametrize('mode', ['ignore', 'raise'])
+def test_unique_list_nan_self_assignment(
+    index: int, mode: containers.OnDuplicate
+) -> None:
+    """Assigning the same NaN object does not introduce a duplicate."""
+    missing = float('nan')
+    values: containers.UniqueList[float] = containers.UniqueList(
+        missing, on_duplicate=mode
+    )
+    values[index] = missing
+    assert len(values) == 1
+    assert values[index] is missing
+    assert missing in values
+
+
+def test_unique_list_nan_duplicate_in_another_slot() -> None:
+    """The same NaN object remains a duplicate in a different list slot."""
+    missing = float('nan')
+    values: containers.UniqueList[float] = containers.UniqueList(
+        1.0, missing, on_duplicate='raise'
+    )
+    with pytest.raises(ValueError, match='Duplicate value'):
+        values[0] = missing
+    assert values[0] == 1.0
+    assert values[1] is missing
+
+
+def test_lazy_casted_dict_get_casts_values_without_caching() -> None:
+    """Get uses the same key and value casts as indexed reads."""
+    calls: list[str] = []
+
+    def cast(value: str) -> int:
+        """Record each lazy value conversion."""
+        calls.append(value)
+        return int(value)
+
+    values: containers.LazyCastedDict[int, int] = containers.LazyCastedDict(
+        int, cast
+    )
+    values['1'] = '2'
+    assert values.get('1') == 2
+    assert values.get(1) == 2
+    assert calls == ['2', '2']
+    assert raw_items(values) == {1: '2'}
+    assert values.get('3', 'fallback') == 'fallback'
+
+
+def test_lazy_casted_dict_get_defaults_without_value_cast() -> None:
+    """Return missing defaults unchanged and support disabled casts."""
+    values: containers.LazyCastedDict[int, int] = containers.LazyCastedDict(
+        int, int
+    )
+    assert values.get(1) is None
+    fallback = object()
+    assert values.get(1, fallback) is fallback
+    plain: containers.LazyCastedDict[str, str] = containers.LazyCastedDict()
+    plain['key'] = 'value'
+    assert plain.get('key') == 'value'
+    assert plain.get('missing') is None
+
+
+def test_lazy_casted_dict_get_does_not_hide_cast_errors() -> None:
+    """A KeyError raised by a value cast is not a missing-key result."""
+
+    def cast(value: str) -> int:
+        """Reject values with a distinguishable conversion error."""
+        raise KeyError(value)
+
+    values: containers.LazyCastedDict[str, int] = containers.LazyCastedDict(
+        None, cast
+    )
+    values['key'] = 'bad value'
+    with pytest.raises(KeyError, match='bad value'):
+        values.get('key', 0)
+
+
+def test_lazy_casted_dict_get_casts_key_once() -> None:
+    """A non-idempotent key cast runs once per get call."""
+    key_cast = CountingCast()
+    values: containers.LazyCastedDict[int, typing.Any] = (
+        containers.LazyCastedDict(key_cast, int)
+    )
+    dict[int, typing.Any].__setitem__(values, 2, '3')
+    assert values.get(1) == 3
+    assert key_cast.calls == 1
+
+
+@pytest.mark.parametrize('key', [None, '', 'spam', '1.5', float('inf')])
+def test_lazy_casted_dict_get_rejected_key_returns_default(
+    key: typing.Any,
+) -> None:
+    """A key the key cast rejects is missing, as it was for ``dict.get``."""
+    values: containers.LazyCastedDict[int, int] = containers.LazyCastedDict(
+        int, int
+    )
+    values[3] = '4'
+    assert values.get(key) is None
+    assert values.get(key, 'missing') == 'missing'
+
+
+def test_lazy_casted_dict_get_skips_missing() -> None:
+    """A miss returns the default without calling ``__missing__``."""
+
+    class Defaulting(containers.LazyCastedDict[int, int]):
+        """Store a zero for every key read through indexing."""
+
+        def __missing__(self, key: int) -> str:
+            """Store and return a zero."""
+            self[key] = '0'
+            return '0'
+
+    values = Defaulting(int, int)
+    assert values.get(5, 'missing') == 'missing'
+    assert raw_items(values) == {}
+
+
+class PositionalGet(containers.LazyCastedDict[int, int]):
+    """Override ``get`` with the positional-only signature of ``dict``."""
+
+    def get(
+        self, key: typing.Any, default: typing.Any = None, /
+    ) -> typing.Any:
+        """Read through the parent implementation."""
+        return super().get(key, default)
+
+
+def test_lazy_casted_dict_get_positional_override() -> None:
+    """A subclass may keep the positional-only ``dict.get`` signature."""
+    values = PositionalGet(int, int)
+    values['1'] = '2'
+    assert values.get(1) == 2

python_utils-4.2.0/_python_utils_tests/test_converters.py

@@ -0,0 +1,104 @@
+"""Tests for the conversion helpers in ``python_utils.converters``."""
+
+import math
+import re
+
+import pytest
+
+from python_utils import converters
+
+
+@pytest.mark.parametrize('regexp', [r'\d+', re.compile(r'\d+')])
+def test_to_int_regexp_without_group(regexp: re.Pattern[str] | str) -> None:
+    """Use the whole match when the pattern has no capture group."""
+    assert converters.to_int('abc123', regexp=regexp) == 123
+
+
+@pytest.mark.parametrize('regexp', [r'\d+\.\d+', re.compile(r'\d+\.\d+')])
+def test_to_float_regexp_without_group(
+    regexp: re.Pattern[str] | str,
+) -> None:
+    """Use the whole match when the pattern has no capture group."""
+    assert converters.to_float('abc1.5', regexp=regexp) == 1.5
+
+
+def test_regexp_with_groups_keeps_its_group() -> None:
+    """Keep the last group for ``to_int`` and the first for ``to_float``."""
+    assert converters.to_int('a1b2', regexp=r'(\d)\D(\d)') == 2
+    assert converters.to_float('a1b2', regexp=r'(\d)\D(\d)') == 1.0
+
+
+@pytest.mark.parametrize('value', [0.0001, 1e-9, 2**-11])
+def test_scale_1024_small_number(value: float) -> None:
+    """Never scale a number below one up to a negative power."""
+    assert converters.scale_1024(value, 9) == (value, 0)
+
+
+@pytest.mark.parametrize('power', range(1, 9))
+def test_scale_1024_integer_prefix_boundaries(power: int) -> None:
+    """Choose prefixes from the integer value before rounding it to float."""
+    boundary = 1024**power
+    for value, expected_power in (
+        (boundary - 1, power - 1),
+        (boundary, power),
+        (boundary + 1, power),
+    ):
+        assert converters.scale_1024(value, 9) == (
+            float(value) / 1024**expected_power,
+            expected_power,
+        )
+
+
+@pytest.mark.parametrize('power', range(1, 9))
+def test_scale_1024_float_prefix_boundaries(power: int) -> None:
+    """Keep the float immediately below a prefix boundary in the lower unit."""
+    boundary = float(1024**power)
+    for value, expected_power in (
+        (math.nextafter(boundary, 0.0), power - 1),
+        (boundary, power),
+        (math.nextafter(boundary, math.inf), power),
+    ):
+        assert converters.scale_1024(value, 9) == (
+            value / 1024**expected_power,
+            expected_power,
+        )
+
+
+def test_scale_1024_prefix_limit() -> None:
+    """Keep values in the largest available prefix even at higher powers."""
+    assert converters.scale_1024(1024**5, 3) == (1024.0**3, 2)
+
+
+@pytest.mark.parametrize('n_prefixes', [0, -1])
+def test_scale_1024_without_prefixes(n_prefixes: int) -> None:
+    """Never return a negative power when there are no prefixes."""
+    assert converters.scale_1024(2048, n_prefixes) == (2048.0, 0)
+
+
+@pytest.mark.parametrize('default', [0.0, -1.25])
+def test_to_float_float_default(default: float) -> None:
+    """Accept the documented float fallback in typed consumer code."""
+    assert converters.to_float('missing', default=default) is default
+    assert (
+        converters.to_float('missing', default=default, regexp=True) is default
+    )
+    assert converters.to_float('1.5', default=default) == 1.5
+
+
+class _LessEqualOnly:
+    """A numeric type with ``__le__`` and ``__float__``, no ``__lt__``."""
+
+    def __init__(self, value: int) -> None:
+        self.value: int = value
+
+    def __le__(self, other: object) -> bool:
+        return self.value <= other  # type: ignore[operator]
+
+    def __float__(self) -> float:
+        return float(self.value)
+
+
+def test_scale_1024_accepts_number_without_lt() -> None:
+    """Keep the 4.1.4 float path for a type without ``__lt__``."""
+    value: _LessEqualOnly = _LessEqualOnly(2048)
+    assert converters.scale_1024(value, 9) == (2.0, 1)  # type: ignore[arg-type]

{python_utils-4.1.3 → python_utils-4.2.0}/_python_utils_tests/test_generators.py

@@ -4,6 +4,7 @@ import asyncio
 import datetime
 import gc
 import sys
+import warnings
 from types import SimpleNamespace
 
 import pytest
@@ -99,7 +100,7 @@ async def test_abatcher_timed_with_timeout() -> None:
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize('batch_size', [None, 3])
+@pytest.mark.parametrize('batch_size', [None, 0, -1, 3])
 @pytest.mark.parametrize('interval', [10, datetime.timedelta(seconds=10)])
 @pytest.mark.parametrize('arrival', [8.0, 10.0])
 async def test_abatcher_partial_batch_keeps_deadline(
@@ -364,6 +365,149 @@ async def test_abatcher_with_future_returning_iterator() -> None:
     assert batches == [[0, 1], [2, 3], [4]]
 
 
+@pytest.mark.parametrize('batch_size', [0, -1])
+@pytest.mark.parametrize('count', [0, 3])
+def test_batcher_warns_for_nonpositive_size(
+    batch_size: int, count: int
+) -> None:
+    """Warn once while keeping the existing result and consumption order."""
+    consumed: list[int] = []
+
+    def source() -> types.Generator[int, None, None]:
+        for item in range(count):
+            consumed.append(item)
+            yield item
+
+    batcher = python_utils.batcher(source(), batch_size)
+    assert consumed == []
+    with pytest.warns(DeprecationWarning, match='ValueError.*5.0') as caught:
+        result = list(batcher)
+
+    assert result == ([list(range(count))] if count else [])
+    assert consumed == list(range(count))
+    assert len(caught) == 1
+    assert caught[0].filename == __file__
+
+
+@pytest.mark.parametrize('batch_size', [0, -1])
+def test_batcher_warning_as_error_does_not_consume(batch_size: int) -> None:
+    """Let callers opt into failure before taking the first source item."""
+    source = iter(range(3))
+    batcher = python_utils.batcher(source, batch_size)
+    with warnings.catch_warnings():
+        warnings.simplefilter('error', DeprecationWarning)
+        with pytest.raises(DeprecationWarning, match='batch_size'):
+            next(batcher)
+    assert list(source) == [0, 1, 2]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('batch_size', [0, -1])
+@pytest.mark.parametrize('count', [0, 3])
+@pytest.mark.parametrize('interval', [None, 0])
+async def test_abatcher_warns_without_interval(
+    batch_size: int, count: int, interval: int | None
+) -> None:
+    """Keep the old zero-size error and negative-size result in 4.x."""
+    consumed: list[int] = []
+
+    async def source() -> types.AsyncGenerator[int, None]:
+        for item in range(count):
+            consumed.append(item)
+            yield item
+
+    batcher = python_utils.abatcher(source(), batch_size, interval)
+    assert consumed == []
+    with pytest.warns(DeprecationWarning, match='ValueError.*5.0') as caught:
+        if batch_size == 0:
+            with pytest.raises(AssertionError, match='Must specify either'):
+                await batcher.__anext__()
+            assert consumed == []
+        else:
+            result = [batch async for batch in batcher]
+            assert result == ([list(range(count))] if count else [])
+            assert consumed == list(range(count))
+
+    assert len(caught) == 1
+    assert caught[0].filename == __file__
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('batch_size', [0, -1])
+async def test_abatcher_warning_as_error_does_not_consume(
+    batch_size: int,
+) -> None:
+    """Warn before scheduling even the first asynchronous source item."""
+    source = FutureIterator(3)
+    batcher = python_utils.abatcher(source, batch_size)
+    with warnings.catch_warnings():
+        warnings.simplefilter('error', DeprecationWarning)
+        with pytest.raises(DeprecationWarning, match='batch_size'):
+            await batcher.__anext__()
+    assert source.current == 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('batch_size', [None, 0, -1])
+@pytest.mark.parametrize('count', [0, 3])
+async def test_abatcher_interval_only_sizes(
+    batch_size: int | None, count: int
+) -> None:
+    """None and nonpositive sizes impose no limit and issue no warning."""
+    source = FutureIterator(count)
+    result = [
+        batch async for batch in python_utils.abatcher(source, batch_size, 10)
+    ]
+    assert result == ([list(range(count))] if count else [])
+    assert source.current == count
+
+
+def test_batcher_positive_size_is_lazy() -> None:
+    """Positive sizes issue no warning and consume only the first batch."""
+    source = iter(range(3))
+    batcher = python_utils.batcher(source, 1)
+    assert next(batcher) == [0]
+    assert list(source) == [1, 2]
+
+
+@pytest.mark.parametrize(
+    'batch_size,expected',
+    [('2', [[0, 1, 2, 3, 4]]), (2 + 0j, [[0, 1], [2, 3], [4]])],
+)
+def test_batcher_noncomparable_size(
+    batch_size: types.Any, expected: list[list[int]]
+) -> None:
+    """A size that does not compare with 1 keeps its 4.x result."""
+    with warnings.catch_warnings():
+        warnings.simplefilter('error', DeprecationWarning)
+        assert list(python_utils.batcher(range(5), batch_size)) == expected
+
+
+@pytest.mark.asyncio
+async def test_abatcher_noncomparable_size_with_interval() -> None:
+    """A size that does not compare with 1 leaves the interval in charge."""
+    size: types.Any = '2'
+    source = FutureIterator(5)
+    result = [batch async for batch in python_utils.abatcher(source, size, 10)]
+    assert result == [[0, 1, 2, 3, 4]]
+
+
+@pytest.mark.asyncio
+async def test_abatcher_zero_size_with_interval_yields_empty_batch() -> None:
+    """Keep the 4.x empty batch for an idle interval with a size of 0."""
+
+    async def generator() -> types.AsyncGenerator[int, None]:
+        """Stay idle forever."""
+        await asyncio.Event().wait()
+        yield 0  # pragma: no cover
+
+    batcher = python_utils.abatcher(generator(), batch_size=0, interval=0.01)
+    try:
+        assert await asyncio.wait_for(batcher.__anext__(), 5) == []
+    finally:
+        await batcher.aclose()
+
+
 def test_batcher() -> None:
     """Split an iterable into fixed-size batches."""
     batch = []

{python_utils-4.1.3 → python_utils-4.2.0}/_python_utils_tests/test_import.py

@@ -3,6 +3,7 @@
 import collections.abc
 import pathlib
 import sys
+from types import ModuleType
 
 import pytest
 
@@ -203,3 +204,98 @@ def test_import_global_missing_below_detached_module(
 
     assert type(error) is ImportError
     assert str(error) == f'No module named {name}'
+
+
+@pytest.mark.parametrize(
+    'names', [None, ['virtual', 'none', '_private', 'missing']]
+)
+def test_import_global_lazy_module_exports(
+    monkeypatch: pytest.MonkeyPatch, names: list[str] | None
+) -> None:
+    """Read declared and explicit exports through module __getattr__."""
+    module_name = 'python_utils_lazy_export_fixture'
+    module = ModuleType(module_name)
+    calls: dict[str, int] = {}
+
+    def lookup(name: str) -> types.Any:
+        """Provide public names that are deliberately absent from dir()."""
+        calls[name] = calls.get(name, 0) + 1
+        if name == 'virtual':
+            return 42
+        if name == 'none':
+            return None
+        raise AttributeError(name)
+
+    module.__dict__['__getattr__'] = lookup
+    module.__dict__['__all__'] = ['virtual', 'none', '_private', 'missing']
+    monkeypatch.setitem(sys.modules, module_name, module)
+    scope: dict[str, types.Any] = {}
+    import_.import_global(module_name, names, locals_={}, globals_=scope)
+    assert scope == {'virtual': 42, 'none': None}
+    assert calls['virtual'] == calls['none'] == 1
+
+
+@pytest.mark.parametrize('error', [ImportError, RuntimeError])
+def test_import_global_skips_failing_lazy_exports(
+    monkeypatch: pytest.MonkeyPatch, error: type[Exception]
+) -> None:
+    """Skip a lazy export that fails to resolve, as 4.x did."""
+    module_name = 'python_utils_failing_lazy_fixture'
+    module = ModuleType(module_name)
+
+    def lookup(name: str) -> types.Any:
+        """Serve one working and one failing lazy export."""
+        if name == 'working':
+            return 1
+        if name == 'broken':
+            raise error('optional dependency missing')
+        raise AttributeError(name)
+
+    module.__dict__['__getattr__'] = lookup
+    module.__dict__['__all__'] = ['eager', 'working', 'broken']
+    module.__dict__['eager'] = 0
+    monkeypatch.setitem(sys.modules, module_name, module)
+    scope: dict[str, types.Any] = {}
+    result = import_.import_global(module_name, locals_={}, globals_=scope)
+    assert result is None
+    assert scope == {'eager': 0, 'working': 1}
+
+
+def test_import_global_ignores_names_that_are_not_strings(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Skip entries of ``modules`` and ``__all__`` that are not names."""
+    module_name = 'python_utils_odd_all_fixture'
+    module = ModuleType(module_name)
+    module.__dict__['__all__'] = ['eggs', 1]
+    module.__dict__['eggs'] = 1
+    monkeypatch.setitem(sys.modules, module_name, module)
+    scope: dict[str, types.Any] = {}
+    import_.import_global(module_name, locals_={}, globals_=scope)
+    assert scope == {'eggs': 1}
+
+    names: types.Any = ['sep', 1, b'sep']
+    scope = {}
+    import_.import_global('os', names, locals_={}, globals_=scope)
+    assert list(scope) == ['sep']
+
+
+def test_import_global_requested_name_needs_an_export(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Leave a catch-all ``__getattr__`` alone for undeclared names."""
+    module_name = 'python_utils_catch_all_fixture'
+    module = ModuleType(module_name)
+    calls: list[str] = []
+
+    def lookup(name: str) -> str:
+        """Answer every name, as a lazy submodule loader would."""
+        calls.append(name)
+        return f'auto-{name}'
+
+    module.__dict__['__getattr__'] = lookup
+    monkeypatch.setitem(sys.modules, module_name, module)
+    scope: dict[str, types.Any] = {}
+    import_.import_global(module_name, ['eggs'], locals_={}, globals_=scope)
+    assert scope == {}
+    assert 'eggs' not in calls

python_utils-4.2.0/_python_utils_tests/test_types.py

@@ -0,0 +1,49 @@
+"""Regression tests for the public ``python_utils.types`` facade."""
+
+import collections
+import sys
+
+from python_utils import types
+
+
+def test_types_all_entries_are_unique() -> None:
+    """Export every public name once."""
+    counts: collections.Counter[str] = collections.Counter(types.__all__)
+    duplicates: list[str] = sorted(
+        name for name, count in counts.items() if count > 1
+    )
+
+    assert duplicates == []
+
+
+def test_types_all_entries_exist() -> None:
+    """Resolve every name in ``__all__`` so star imports keep working."""
+    missing: list[str] = [
+        name for name in types.__all__ if not hasattr(types, name)
+    ]
+
+    assert missing == []
+
+
+def test_types_star_import() -> None:
+    """Import the public facade with ``from python_utils.types import *``."""
+    namespace: dict[str, object] = {}
+    exec('from python_utils.types import *', namespace)  # noqa: S102
+
+    assert set(types.__all__) <= namespace.keys()
+
+
+def test_types_all_keeps_removed_typing_names_in_place() -> None:
+    """Keep the 4.1.4 order of ``__all__`` where the names still exist."""
+    removed_in_315: list[str] = ['ByteString', 'no_type_check_decorator']
+    if sys.version_info >= (3, 15):
+        assert not set(removed_in_315) & set(types.__all__)
+        return
+
+    # Each name sits in its alphabetical slot, not appended at the end.
+    assert types.__all__.index('ByteString') == (
+        types.__all__.index('BuiltinMethodType') + 1
+    )
+    assert types.__all__.index('no_type_check_decorator') == (
+        types.__all__.index('no_type_check') + 1
+    )

{python_utils-4.1.3 → python_utils-4.2.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["uv_build>=0.11,<0.13"]
+requires = ["uv_build>=0.11,<1"]
 build-backend = "uv_build"
 
 [tool.mypy]
@@ -125,7 +125,7 @@ source-include = [
 
 [project]
 name = "python-utils"
-version = "4.1.3"
+version = "4.2.0"
 description = "Python Utils is a module with some convenient utilities not included with the standard Python install"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -150,6 +150,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",

{python_utils-4.1.3 → python_utils-4.2.0}/pyproject.toml.orig

@@ -1,5 +1,5 @@
 [build-system]
-requires = ['uv_build>=0.11,<0.13']
+requires = ['uv_build>=0.11,<1']
 build-backend = 'uv_build'
 
 [tool.uv.build-backend]
@@ -12,7 +12,7 @@ source-include = ['_python_utils_tests/**/*.py', 'conftest.py', 'tox.ini']
 
 [project]
 name = 'python-utils'
-version = "4.1.3" # static; the single source of truth. Bump via `uv version`.
+version = "4.2.0" # static; the single source of truth. Bump via `uv version`.
 description = 'Python Utils is a module with some convenient utilities not included with the standard Python install'
 readme = 'README.md'
 requires-python = '>=3.10'
@@ -38,6 +38,7 @@ classifiers = [
     'Programming Language :: Python :: 3.12',
     'Programming Language :: Python :: 3.13',
     'Programming Language :: Python :: 3.14',
+    'Programming Language :: Python :: 3.15',
     'Programming Language :: Python :: 3 :: Only',
     'Programming Language :: Python :: Implementation :: CPython',
     'Programming Language :: Python :: Implementation :: PyPy',

{python_utils-4.1.3 → python_utils-4.2.0}/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-4.1.3 → python_utils-4.2.0}/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-4.1.3 → python_utils-4.2.0}/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-4.1.3 → python_utils-4.2.0}/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-4.1.3 → python_utils-4.2.0}/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-4.1.3 → python_utils-4.2.0}/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 → python_utils-4.2.0}/tox.ini

@@ -6,7 +6,7 @@ requires =
 # PyPy) isn't installed; CI provides each interpreter via tox-gh-actions.
 skip_missing_interpreters = true
 env_list =
-    py{310,311,312,313,314}
+    py{310,311,312,313,314,315}
     pypy{310,311}
     lint
     mypy
@@ -16,7 +16,7 @@ env_list =
     docs
     coverage
 labels =
-    test = py{310,311,312,313,314}, pypy{310,311}
+    test = py{310,311,312,313,314,315}, pypy{310,311}
     check = lint, mypy, pyright, pyrefly, codespell
 
 [gh-actions]
@@ -26,6 +26,7 @@ python =
     3.12: py312
     3.13: py313
     3.14: py314
+    3.15: py315
     pypy-3.10: pypy310
     pypy-3.11: pypy311
 

python_utils-4.1.3/_python_utils_tests/requirements.txt

@@ -1 +0,0 @@
--e .[tests]

python_utils-4.1.3/_python_utils_tests/test_converters.py

@@ -1,39 +0,0 @@
-"""Tests for the conversion helpers in ``python_utils.converters``."""
-
-import re
-
-import pytest
-
-from python_utils import converters
-
-
-@pytest.mark.parametrize('regexp', [r'\d+', re.compile(r'\d+')])
-def test_to_int_regexp_without_group(regexp: re.Pattern[str] | str) -> None:
-    """Use the whole match when the pattern has no capture group."""
-    assert converters.to_int('abc123', regexp=regexp) == 123
-
-
-@pytest.mark.parametrize('regexp', [r'\d+\.\d+', re.compile(r'\d+\.\d+')])
-def test_to_float_regexp_without_group(
-    regexp: re.Pattern[str] | str,
-) -> None:
-    """Use the whole match when the pattern has no capture group."""
-    assert converters.to_float('abc1.5', regexp=regexp) == 1.5
-
-
-def test_regexp_with_groups_keeps_its_group() -> None:
-    """Keep the last group for ``to_int`` and the first for ``to_float``."""
-    assert converters.to_int('a1b2', regexp=r'(\d)\D(\d)') == 2
-    assert converters.to_float('a1b2', regexp=r'(\d)\D(\d)') == 1.0
-
-
-@pytest.mark.parametrize('value', [0.0001, 1e-9, 2**-11])
-def test_scale_1024_small_number(value: float) -> None:
-    """Never scale a number below one up to a negative power."""
-    assert converters.scale_1024(value, 9) == (value, 0)
-
-
-@pytest.mark.parametrize('n_prefixes', [0, -1])
-def test_scale_1024_without_prefixes(n_prefixes: int) -> None:
-    """Never return a negative power when there are no prefixes."""
-    assert converters.scale_1024(2048, n_prefixes) == (2048.0, 0)

python_utils-4.1.3/_python_utils_tests/test_types.py

@@ -1,15 +0,0 @@
-"""Regression tests for the public ``python_utils.types`` facade."""
-
-import collections
-
-from python_utils import types
-
-
-def test_types_all_entries_are_unique() -> None:
-    """Export every public name once."""
-    counts: collections.Counter[str] = collections.Counter(types.__all__)
-    duplicates: list[str] = sorted(
-        name for name, count in counts.items() if count > 1
-    )
-
-    assert duplicates == []