python-utils 4.1.4__tar.gz → 4.2.1__tar.gz

{python_utils-4.1.4 → python_utils-4.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-utils
-Version: 4.1.4
+Version: 4.2.1
 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
@@ -36,6 +37,7 @@ Project-URL: Documentation, https://python-utils.readthedocs.io/
 Project-URL: Repository, https://github.com/WoLpH/python-utils
 Project-URL: Changelog, https://github.com/WoLpH/python-utils/releases
 Project-URL: Funding, https://github.com/sponsors/wolph
+Project-URL: Issues, https://github.com/wolph/python-utils/issues
 Provides-Extra: docs
 Provides-Extra: loguru
 Provides-Extra: tests

{python_utils-4.1.4 → python_utils-4.2.1}/_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.4 → python_utils-4.2.1}/_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.1/_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.4 → python_utils-4.2.1}/_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 = []