dycw-utilities 0.125.2__tar.gz → 0.125.3__tar.gz

{dycw_utilities-0.125.2 → dycw_utilities-0.125.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.125.2
+Version: 0.125.3
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.125.2 → dycw_utilities-0.125.3}/pyproject.toml

@@ -91,7 +91,7 @@ dependencies = [
 name = "dycw-utilities"
 readme = "README.md"
 requires-python = ">= 3.12"
-version = "0.125.2"
+version = "0.125.3"
 
 [project.optional-dependencies]
 test = [
@@ -332,7 +332,7 @@ zzz-test-zoneinfo = [
 # bump-my-version
 [tool.bumpversion]
 allow_dirty = true
-current_version = "0.125.2"
+current_version = "0.125.3"
 
 [[tool.bumpversion.files]]
 filename = "src/utilities/__init__.py"

{dycw_utilities-0.125.2 → dycw_utilities-0.125.3}/src/tests/test_more_itertools.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 from collections.abc import Iterator
+from re import escape
 from typing import TYPE_CHECKING, Any, ClassVar, TypeGuard
 
 from pytest import mark, param, raises
 
 from utilities.more_itertools import (
+    BucketMappingError,
     Split,
     bucket_mapping,
     partition_list,
@@ -64,6 +66,46 @@ class TestBucketMapping:
         assert mapping["b"] == [1, 2, 3]
         assert mapping["c"] == [1, 2]
 
+    iterable_unique: ClassVar[list[str]] = ["a1", "b2", "c3"]
+
+    def test_unique(self) -> None:
+        mapping = bucket_mapping(self.iterable_unique, lambda x: x[0], unique=True)
+        expected = {"a": "a1", "b": "b2", "c": "c3"}
+        assert mapping == expected
+
+    def test_transform_and_unique(self) -> None:
+        mapping = bucket_mapping(
+            self.iterable_unique,
+            lambda x: x[0],
+            transform=lambda x: int(x[-1]),
+            unique=True,
+        )
+        expected = {"a": 1, "b": 2, "c": 3}
+        assert mapping == expected
+
+    def test_error_unique(self) -> None:
+        with raises(
+            BucketMappingError,
+            match=escape(
+                "Buckets must contain exactly one item each; got 'a' (#1: 'a1', #2: 'a2'), 'b' (#1: 'b1', #2: 'b2'), 'c' (#1: 'c1', #2: 'c2')"
+            ),
+        ):
+            _ = bucket_mapping(self.iterable, lambda x: x[0], unique=True)
+
+    def test_error_transform_and_unique(self) -> None:
+        with raises(
+            BucketMappingError,
+            match=escape(
+                "Buckets must contain exactly one item each; got 'a' (#1: 1, #2: 2), 'b' (#1: 1, #2: 2), 'c' (#1: 1, #2: 2)"
+            ),
+        ):
+            _ = bucket_mapping(
+                self.iterable,
+                lambda x: x[0],
+                transform=lambda x: int(x[-1]),
+                unique=True,
+            )
+
 
 class TestPartitionList:
     def test_main(self) -> None:

{dycw_utilities-0.125.2 → dycw_utilities-0.125.3}/src/utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.125.2"
+__version__ = "0.125.3"

{dycw_utilities-0.125.2 → dycw_utilities-0.125.3}/src/utilities/more_itertools.py

@@ -21,12 +21,14 @@ from more_itertools import bucket, partition, split_into
 from more_itertools import peekable as _peekable
 
 from utilities.functions import get_class_name
+from utilities.iterables import OneNonUniqueError, one
+from utilities.reprlib import get_repr
 from utilities.sentinel import Sentinel, sentinel
+from utilities.types import THashable
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
 
-    from utilities.types import THashable
 
 _T = TypeVar("_T")
 _U = TypeVar("_U")
@@ -35,6 +37,26 @@ _U = TypeVar("_U")
 ##
 
 
+@overload
+def bucket_mapping(
+    iterable: Iterable[_T],
+    func: Callable[[_T], THashable],
+    /,
+    *,
+    transform: Callable[[_T], _U],
+    list: bool = False,
+    unique: Literal[True],
+) -> Mapping[THashable, _U]: ...
+@overload
+def bucket_mapping(
+    iterable: Iterable[_T],
+    func: Callable[[_T], THashable],
+    /,
+    *,
+    transform: Callable[[_T], _U] | None = None,
+    list: bool = False,
+    unique: Literal[True],
+) -> Mapping[THashable, _T]: ...
 @overload
 def bucket_mapping(
     iterable: Iterable[_T],
@@ -79,11 +101,14 @@ def bucket_mapping(
     *,
     transform: Callable[[_T], _U] | None = None,
     list: bool = False,
+    unique: bool = False,
 ) -> (
     Mapping[THashable, Iterator[_T]]
     | Mapping[THashable, Iterator[_U]]
     | Mapping[THashable, Sequence[_T]]
     | Mapping[THashable, Sequence[_U]]
+    | Mapping[THashable, _T]
+    | Mapping[THashable, _U]
 ): ...
 def bucket_mapping(
     iterable: Iterable[_T],
@@ -92,26 +117,55 @@ def bucket_mapping(
     *,
     transform: Callable[[_T], _U] | None = None,
     list: bool = False,  # noqa: A002
+    unique: bool = False,
 ) -> (
     Mapping[THashable, Iterator[_T]]
     | Mapping[THashable, Iterator[_U]]
     | Mapping[THashable, Sequence[_T]]
     | Mapping[THashable, Sequence[_U]]
+    | Mapping[THashable, _T]
+    | Mapping[THashable, _U]
 ):
     """Bucket the values of iterable into a mapping."""
     b = bucket(iterable, func)
     mapping = {key: b[key] for key in b}
     match transform, list:
         case None, False:
-            return mapping
+            ...
         case None, True:
-            return {k: builtins.list(v) for k, v in mapping.items()}
+            mapping = {k: builtins.list(v) for k, v in mapping.items()}
         case _, False:
-            return {k: map(transform, v) for k, v in mapping.items()}
+            mapping = {k: map(transform, v) for k, v in mapping.items()}
         case _, True:
-            return {k: builtins.list(map(transform, v)) for k, v in mapping.items()}
+            mapping = {k: builtins.list(map(transform, v)) for k, v in mapping.items()}
         case _ as never:
             assert_never(never)
+    if not unique:
+        return mapping
+    results = {}
+    error_no_transform: dict[THashable, tuple[_T, _T]] = {}
+    for key, value in mapping.items():
+        try:
+            results[key] = one(value)
+        except OneNonUniqueError as error:
+            error_no_transform[key] = (error.first, error.second)
+    if len(error_no_transform) >= 1:
+        raise BucketMappingError(errors=error_no_transform)
+    return results
+
+
+@dataclass(kw_only=True, slots=True)
+class BucketMappingError(Exception, Generic[THashable, _U]):
+    errors: Mapping[THashable, tuple[_U, _U]]
+
+    @override
+    def __str__(self) -> str:
+        parts = [
+            f"{get_repr(key)} (#1: {get_repr(first)}, #2: {get_repr(second)})"
+            for key, (first, second) in self.errors.items()
+        ]
+        desc = ", ".join(parts)
+        return f"Buckets must contain exactly one item each; got {desc}"
 
 
 ##
@@ -264,6 +318,7 @@ def _yield_splits3(
 
 
 __all__ = [
+    "BucketMappingError",
     "Split",
     "bucket_mapping",
     "partition_list",