multicollections 0.1.2__tar.gz → 0.2.0__tar.gz

{multicollections-0.1.2 → multicollections-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multicollections
-Version: 0.1.2
+Version: 0.2.0
 Summary: Fully generic MultiDict class
 Project-URL: Homepage, https://github.com/gerlero/multicollections
 Project-URL: Repository, https://github.com/gerlero/multicollections

{multicollections-0.1.2 → multicollections-0.2.0}/mkdocs.yml

@@ -21,7 +21,6 @@ plugins:
                     show_signature_annotations: true
                     show_symbol_type_toc: true
                     inherited_members: true
-                    filters: false
 
 nav:
     - Home: 'index.md'

{multicollections-0.1.2 → multicollections-0.2.0}/multicollections/__init__.py

@@ -20,24 +20,24 @@ else:
         Sequence,
     )
 
-from .abc import MutableMultiMapping
+from .abc import MutableMultiMapping, with_default
 
-K = TypeVar("K")
-V = TypeVar("V")
+_K = TypeVar("_K")
+_V = TypeVar("_V")
 
 
-class MultiDict(MutableMultiMapping[K, V]):
+class MultiDict(MutableMultiMapping[_K, _V]):
     """A fully generic dictionary that allows multiple values with the same key.
 
     Preserves insertion order.
     """
 
     def __init__(
-        self, iterable: Mapping[K, V] | Iterable[Sequence[K | V]] = (), **kwargs: V
+        self, iterable: Mapping[_K, _V] | Iterable[Sequence[_K | _V]] = (), **kwargs: _V
     ) -> None:
         """Create a MultiDict."""
-        self._items: list[tuple[K, V]] = []
-        self._key_indices: dict[K, list[int]] = {}
+        self._items: list[tuple[_K, _V]] = []
+        self._key_indices: dict[_K, list[int]] = {}
         if isinstance(iterable, Mapping):
             for key, value in iterable.items():
                 self._add_item(key, value)
@@ -47,7 +47,7 @@ class MultiDict(MutableMultiMapping[K, V]):
         for key, value in kwargs.items():
             self._add_item(key, value)
 
-    def _add_item(self, key: K, value: V) -> None:
+    def _add_item(self, key: _K, value: _V) -> None:
         """Add an item and update the key index."""
         index = len(self._items)
         self._items.append((key, value))
@@ -55,11 +55,18 @@ class MultiDict(MutableMultiMapping[K, V]):
             self._key_indices[key] = []
         self._key_indices[key].append(index)
 
-    def _getall(self, key: K) -> list[V]:
-        """Get all values for a key."""
-        return [self._items[i][1] for i in self._key_indices.get(key, [])]
+    @with_default
+    def getall(self, key: _K) -> list[_V]:
+        """Get all values for a key.
 
-    def __setitem__(self, key: K, value: V) -> None:
+        Raises a `KeyError` if the key is not found and no default is provided.
+        """
+        ret = [self._items[i][1] for i in self._key_indices.get(key, [])]
+        if not ret:
+            raise KeyError(key)
+        return ret
+
+    def __setitem__(self, key: _K, value: _V) -> None:
         """Set the value for a key.
 
         Replaces the first value for a key if it exists; otherwise, it adds a new item.
@@ -93,11 +100,12 @@ class MultiDict(MutableMultiMapping[K, V]):
                 self._key_indices[key] = []
             self._key_indices[key].append(i)
 
-    def add(self, key: K, value: V) -> None:
-        """Add a value for a key."""
+    def add(self, key: _K, value: _V) -> None:
+        """Add a new value for a key."""
         self._add_item(key, value)
 
-    def _popone(self, key: K) -> V:
+    @with_default
+    def popone(self, key: _K) -> _V:
         """Remove and return the first value for a key."""
         if key not in self._key_indices:
             raise KeyError(key)
@@ -115,7 +123,7 @@ class MultiDict(MutableMultiMapping[K, V]):
 
         return value
 
-    def __delitem__(self, key: K) -> None:
+    def __delitem__(self, key: _K) -> None:
         """Remove all values for a key.
 
         Raises a `KeyError` if the key is not found.
@@ -132,7 +140,7 @@ class MultiDict(MutableMultiMapping[K, V]):
         self._items = [item for item in self._items if item is not None]
         self._rebuild_indices()
 
-    def __iter__(self) -> Iterator[K]:
+    def __iter__(self) -> Iterator[_K]:
         """Return an iterator over the keys, in insertion order.
 
         Keys with multiple values will be yielded multiple times.

{multicollections-0.1.2 → multicollections-0.2.0}/multicollections/abc.py

@@ -2,14 +2,17 @@
 
 from __future__ import annotations
 
+import contextlib
+import functools
 import itertools
 import sys
 from abc import abstractmethod
 from collections import defaultdict
-from typing import Generic, TypeVar, overload
+from typing import Generic, TypeVar
 
 if sys.version_info >= (3, 9):
     from collections.abc import (
+        Callable,
         Collection,
         Iterable,
         Iterator,
@@ -20,6 +23,7 @@ if sys.version_info >= (3, 9):
     )
 else:
     from typing import (
+        Callable,
         Collection,
         Iterable,
         Iterator,
@@ -29,15 +33,15 @@ else:
         Sequence,
     )
 
-K = TypeVar("K")
-V = TypeVar("V")
-D = TypeVar("D")
+_K = TypeVar("_K")
+_V = TypeVar("_V")
+_D = TypeVar("_D")
 
 
 class MultiMappingView(MappingView, Collection):
     """Base class for MultiMapping views."""
 
-    def __init__(self, mapping: MultiMapping[K, V]) -> None:
+    def __init__(self, mapping: MultiMapping[_K, _V]) -> None:
         """Initialize the view with the given mapping."""
         super().__init__(mapping)
 
@@ -45,11 +49,11 @@ class MultiMappingView(MappingView, Collection):
 class KeysView(MultiMappingView):
     """View for the keys in a MultiMapping."""
 
-    def __contains__(self, key: K) -> bool:
+    def __contains__(self, key: _K) -> bool:
         """Check if the key is in the mapping."""
         return key in self._mapping
 
-    def __iter__(self) -> Iterator[K]:
+    def __iter__(self) -> Iterator[_K]:
         """Return an iterator over the keys."""
         return iter(self._mapping)
 
@@ -57,7 +61,7 @@ class KeysView(MultiMappingView):
 class ItemsView(MultiMappingView):
     """View for the items (key-value pairs) in a MultiMapping."""
 
-    def __contains__(self, item: tuple[K, V]) -> bool:
+    def __contains__(self, item: tuple[_K, _V]) -> bool:
         """Check if the item is in the mapping."""
         key, value = item
         try:
@@ -65,7 +69,7 @@ class ItemsView(MultiMappingView):
         except KeyError:
             return False
 
-    def __iter__(self) -> Iterator[tuple[K, V]]:
+    def __iter__(self) -> Iterator[tuple[_K, _V]]:
         """Return an iterator over the items (key-value pairs)."""
         counts = defaultdict(int)
         for k in self._mapping:
@@ -76,11 +80,11 @@ class ItemsView(MultiMappingView):
 class ValuesView(MultiMappingView):
     """View for the values in a MultiMapping."""
 
-    def __contains__(self, value: V) -> bool:
+    def __contains__(self, value: _V) -> bool:
         """Check if the value is in the mapping."""
-        return any(value in self._mapping.getall(key) for key in set(self._mapping))
+        return value in iter(self)
 
-    def __iter__(self) -> Iterator[V]:
+    def __iter__(self) -> Iterator[_V]:
         """Return an iterator over the values."""
         yield from (v for _, v in self._mapping.items())
 
@@ -92,7 +96,26 @@ class _NoDefault:
 _NO_DEFAULT = _NoDefault()
 
 
-class MultiMapping(Mapping[K, V], Generic[K, V]):
+def with_default(
+    meth: Callable[[MultiMappingView[_K, _V], _K], _V],
+) -> Callable[[MultiMappingView[_K, _V], _K, _D], _V | _D]:
+    """Add a default value argument to a method that can raise a `KeyError`."""
+
+    @functools.wraps(meth)
+    def wrapper(
+        self: MultiMappingView[_K, _V], key: _K, default: _D | _NoDefault = _NO_DEFAULT
+    ) -> _V | _D:
+        try:
+            return meth(self, key)
+        except KeyError:
+            if default is _NO_DEFAULT:
+                raise
+            return default  # ty: ignore [invalid-return-type]
+
+    return wrapper
+
+
+class MultiMapping(Mapping[_K, _V], Generic[_K, _V]):
     """Abstract base class for multi-mapping collections.
 
     A multi-mapping is a mapping that can hold multiple values for the same key.
@@ -100,15 +123,16 @@ class MultiMapping(Mapping[K, V], Generic[K, V]):
     """
 
     @abstractmethod
-    def _getall(self, key: K) -> list[V]:
+    @with_default
+    def getall(self, key: _K) -> list[_V]:
         """Get all values for a key.
 
-        Returns an empty list if no values are found.
+        Raises a `KeyError` if the key is not found and no default is provided.
         """
         raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
-    def __iter__(self) -> Iterator[K]:
+    def __iter__(self) -> Iterator[_K]:
         """Return an iterator over the keys.
 
         Keys with multiple values will be yielded multiple times.
@@ -120,74 +144,42 @@ class MultiMapping(Mapping[K, V], Generic[K, V]):
         """Return the total number of items (key-value pairs)."""
         raise NotImplementedError  # pragma: no cover
 
-    @overload
-    def getone(self, key: K) -> V: ...
-
-    @overload
-    def getone(self, key: K, default: D) -> V | D: ...
-
-    def getone(self, key: K, default: D | _NoDefault = _NO_DEFAULT) -> V | D:
+    @with_default
+    def getone(self, key: _K) -> _V:
         """Get the first value for a key.
 
         Raises a `KeyError` if the key is not found and no default is provided.
         """
-        try:
-            return self.getall(key)[0]
-        except KeyError:
-            if default is _NO_DEFAULT:
-                raise
-            return default  # ty: ignore[invalid-return-type]
+        return self.getall(key)[0]
 
-    def __getitem__(self, key: K) -> V:
+    def __getitem__(self, key: _K) -> _V:
         """Get the first value for a key.
 
         Raises a `KeyError` if the key is not found.
         """
         return self.getone(key)
 
-    @overload
-    def getall(self, key: K) -> list[V]: ...
-
-    @overload
-    def getall(self, key: K, default: D) -> list[V] | D: ...
-
-    def getall(self, key: K, default: D | _NoDefault = _NO_DEFAULT) -> list[V] | D:
-        """Get all values for a key as a list.
-
-        Raises a `KeyError` if the key is not found and no default is provided.
-        """
-        try:
-            ret = self._getall(key)
-        except KeyError as e:  # pragma: no cover
-            msg = "_getall must return an empty list instead of raising KeyError"
-            raise RuntimeError(msg) from e
-        if not ret:
-            if default is _NO_DEFAULT:
-                raise KeyError(key)
-            return default  # ty: ignore[invalid-return-type]
-        return ret
-
-    def keys(self) -> KeysView[K]:
+    def keys(self) -> KeysView[_K]:
         """Return a view of the keys in the MultiMapping."""
         return KeysView(self)
 
-    def items(self) -> ItemsView[K, V]:
+    def items(self) -> ItemsView[_K, _V]:
         """Return a view of the items (key-value pairs) in the MultiMapping."""
         return ItemsView(self)
 
-    def values(self) -> ValuesView[V]:
+    def values(self) -> ValuesView[_V]:
         """Return a view of the values in the MultiMapping."""
         return ValuesView(self)
 
 
-class MutableMultiMapping(MultiMapping[K, V], MutableMapping[K, V]):
+class MutableMultiMapping(MultiMapping[_K, _V], MutableMapping[_K, _V]):
     """Abstract base class for mutable multi-mapping collections.
 
     A mutable multi-mapping extends MultiMapping with methods to modify the collection.
     """
 
     @abstractmethod
-    def __setitem__(self, key: K, value: V) -> None:
+    def __setitem__(self, key: _K, value: _V) -> None:
         """Set the value for a key.
 
         If the key does not exist, it is added with the specified value.
@@ -198,78 +190,48 @@ class MutableMultiMapping(MultiMapping[K, V], MutableMapping[K, V]):
         raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
-    def add(self, key: K, value: V) -> None:
+    def add(self, key: _K, value: _V) -> None:
         """Add a new value for a key."""
         raise NotImplementedError  # pragma: no cover
 
     @abstractmethod
-    def _popone(self, key: K) -> V:
+    @with_default
+    def popone(self, key: _K) -> _V:
         """Remove and return the first value for a key.
 
         Raises a `KeyError` if the key is not found.
         """
         raise NotImplementedError  # pragma: no cover
 
-    @overload
-    def popone(self, key: K) -> V: ...
-
-    @overload
-    def popone(self, key: K, default: D) -> V | D: ...
-
-    def popone(self, key: K, default: D | _NoDefault = _NO_DEFAULT) -> V | D:
-        """Remove and return the first value for a key.
-
-        Raises a `KeyError` if the key is not found and no default is provided.
-        """
-        try:
-            return self._popone(key)
-        except KeyError:
-            if default is _NO_DEFAULT:
-                raise
-            return default  # type: ignore[invalid-return-type]
-
-    @overload
-    def popall(self, key: K) -> list[V]: ...
-
-    @overload
-    def popall(self, key: K, default: D) -> list[V] | D: ...
-
-    def popall(self, key: K, default: D | _NoDefault = _NO_DEFAULT) -> list[V] | D:
+    @with_default
+    def popall(self, key: _K) -> list[_V]:
         """Remove and return all values for a key as a list.
 
         Raises a `KeyError` if the key is not found and no default is provided.
         """
-        try:
-            return [self.popone(key) for _ in range(len(self.getall(key)))]
-        except KeyError:
-            if default is _NO_DEFAULT:
-                raise
-            return default  # type: ignore[invalid-return-type]
-
-    @overload
-    def pop(self, key: K) -> V: ...
-
-    @overload
-    def pop(self, key: K, default: D) -> V | D: ...
+        ret = [self.popone(key)]
+        with contextlib.suppress(KeyError):
+            while True:
+                ret.append(self.popone(key))
+        return ret
 
-    def pop(self, key: K, default: D | _NoDefault = _NO_DEFAULT) -> V | D:
+    @with_default
+    def pop(self, key: _K) -> _V:
         """Same as `popone`."""
-        if default is _NO_DEFAULT:
-            return self.popone(key)
-        return self.popone(key, default)
+        return self.popone(key)
 
-    def popitem(self) -> tuple[K, V]:
+    def popitem(self) -> tuple[_K, _V]:
         """Remove and return a (key, value) pair."""
         key = next(iter(self))
         value = self.popone(key)
         return key, value
 
-    def __delitem__(self, key: K) -> None:
+    def __delitem__(self, key: _K) -> None:
         """Remove all values for a key.
 
         Raises a `KeyError` if the key is not found.
         """
-        return self.popall(key)
+        self.popall(key)
 
     def clear(self) -> None:
         """Remove all items from the multi-mapping."""
@@ -278,8 +240,8 @@ class MutableMultiMapping(MultiMapping[K, V], MutableMapping[K, V]):
 
     def extend(
         self,
-        other: Mapping[K, V] | Iterable[Sequence[K | V]] = (),
-        **kwargs: V,
+        other: Mapping[_K, _V] | Iterable[Sequence[_K | _V]] = (),
+        **kwargs: _V,
     ) -> None:
         """Extend the multi-mapping with items from another object."""
         items = other.items() if isinstance(other, Mapping) else other
@@ -289,8 +251,8 @@ class MutableMultiMapping(MultiMapping[K, V], MutableMapping[K, V]):
 
     def merge(
         self,
-        other: Mapping[K, V] | Iterable[Sequence[K | V]] = (),
-        **kwargs: V,
+        other: Mapping[_K, _V] | Iterable[Sequence[_K | _V]] = (),
+        **kwargs: _V,
     ) -> None:
         """Merge another object into the multi-mapping.
 
@@ -305,8 +267,8 @@ class MutableMultiMapping(MultiMapping[K, V], MutableMapping[K, V]):
 
     def update(
         self,
-        other: Mapping[K, V] | Iterable[Sequence[K | V]] = (),
-        **kwargs: V,
+        other: Mapping[_K, _V] | Iterable[Sequence[_K | _V]] = (),
+        **kwargs: _V,
     ) -> None:
         """Update the multi-mapping with items from another object.
 

{multicollections-0.1.2 → multicollections-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "multicollections"
-version = "0.1.2"
+version = "0.2.0"
 authors = [
     { name = "Gabriel S. Gerlero", email = "ggerlero@cimec.unl.edu.ar" },
 ]

multicollections-0.2.0/tests/minimalimpl.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import sys
+from typing import TypeVar
+
+if sys.version_info >= (3, 9):
+    from collections.abc import (
+        Iterable,
+        Iterator,
+        Mapping,
+        Sequence,
+    )
+else:
+    from typing import (
+        Iterable,
+        Iterator,
+        Mapping,
+        Sequence,
+    )
+
+from multicollections.abc import MutableMultiMapping, with_default
+
+_K = TypeVar("_K")
+_V = TypeVar("_V")
+
+
+class ListMultiDict(MutableMultiMapping[_K, _V]):
+    def __init__(
+        self, iterable: Mapping[_K, _V] | Iterable[Sequence[_K | _V]] = (), **kwargs: _V
+    ) -> None:
+        self._items: list[tuple[_K, _V]] = []
+        if isinstance(iterable, Mapping):
+            for key, value in iterable.items():
+                self._items.append((key, value))
+        else:
+            for key, value in iterable:
+                self._items.append((key, value))
+        for key, value in kwargs.items():
+            self._items.append((key, value))
+
+    @with_default
+    def getall(self, key: _K) -> list[_V]:
+        ret = [v for k, v in self._items if k == key]
+        if not ret:
+            raise KeyError(key)
+        return ret
+
+    def __setitem__(self, key: _K, value: _V) -> None:
+        replaced: int | None = None
+        for i, (k, _) in enumerate(self._items):
+            if k == key:
+                self._items[i] = (key, value)
+                replaced = i
+                break
+
+        if replaced is not None:
+            self._items = [
+                (k, v)
+                for i, (k, v) in enumerate(self._items)
+                if i == replaced or k != key
+            ]
+        else:
+            self._items.append((key, value))
+
+    def add(self, key: _K, value: _V) -> None:
+        self._items.append((key, value))
+
+    @with_default
+    def popone(self, key: _K) -> _V:
+        for i, (k, v) in enumerate(self._items):
+            if k == key:
+                del self._items[i]
+                return v
+        raise KeyError(key)
+
+    def __iter__(self) -> Iterator[_K]:
+        return (k for k, _ in self._items)
+
+    def __len__(self) -> int:
+        return len(self._items)

{multicollections-0.1.2 → multicollections-0.2.0}/tests/test_multicollections.py

@@ -1,83 +1,16 @@
 from __future__ import annotations
 
 import sys
-from typing import TypeVar
-
-if sys.version_info >= (3, 9):
-    from collections.abc import (
-        Iterable,
-        Iterator,
-        Mapping,
-        Sequence,
-    )
-else:
-    from typing import (
-        Iterable,
-        Iterator,
-        Mapping,
-        Sequence,
-    )
+from typing import TYPE_CHECKING
 
 import multidict
 import pytest
 from multicollections import MultiDict
-from multicollections.abc import MutableMultiMapping
-
-K = TypeVar("K")
-V = TypeVar("V")
-
-
-class ListMultiDict(MutableMultiMapping[K, V]):
-    def __init__(
-        self, iterable: Mapping[K, V] | Iterable[Sequence[K | V]] = (), **kwargs: V
-    ) -> None:
-        self._items: list[tuple[K, V]] = []
-        if isinstance(iterable, Mapping):
-            for key, value in iterable.items():
-                self._items.append((key, value))
-        else:
-            for key, value in iterable:
-                self._items.append((key, value))
-        for key, value in kwargs.items():
-            self._items.append((key, value))
-
-    def _getall(self, key: K) -> list[V]:
-        return [v for k, v in self._items if k == key]
-
-    def __setitem__(self, key: K, value: V) -> None:
-        replaced: int | None = None
-        for i, (k, _) in enumerate(self._items):
-            if k == key:
-                self._items[i] = (key, value)
-                replaced = i
-                break
-
-        if replaced is not None:
-            # Key existed, remove any duplicates
-            self._items = [
-                (k, v)
-                for i, (k, v) in enumerate(self._items)
-                if i == replaced or k != key
-            ]
-        else:
-            # Key didn't exist, add it
-            self._items.append((key, value))
-
-    def add(self, key: K, value: V) -> None:
-        self._items.append((key, value))
-
-    def _popone(self, key: K) -> V:
-        for i, (k, v) in enumerate(self._items):
-            if k == key:
-                del self._items[i]
-                return v
-        raise KeyError(key)
-
-    def __iter__(self) -> Iterator[K]:
-        return (k for k, _ in self._items)
-
-    def __len__(self) -> int:
-        return len(self._items)
+
+from .minimalimpl import ListMultiDict
+
+if TYPE_CHECKING:
+    from multicollections.abc import MutableMultiMapping
 
 
 @pytest.mark.parametrize("cls", [MultiDict, ListMultiDict, multidict.MultiDict])
@@ -649,11 +582,12 @@ def test_update_method(cls: type[MutableMultiMapping]) -> None:
     md = cls([("a", 1), ("b", 2), ("a", 3)])  # ty: ignore [too-many-positional-arguments]
 
     # Test updating with pairs (should replace existing keys)
-    md.update([("a", 999), ("c", 4)])
-    assert len(md) == 3
+    md.update([("a", 999), ("c", 4), ("a", 5)])
+    assert len(md) == 4
     assert md["a"] == 999  # Replaced (duplicates removed)
     assert md["b"] == 2  # Unchanged
     assert md["c"] == 4  # New key added
+    assert md.getall("a") == [999, 5]  # Both 'a' values present
 
     # Test updating with dict
     md2 = cls([("x", 10), ("y", 20)])  # ty: ignore [too-many-positional-arguments]
@@ -671,6 +605,15 @@ def test_update_method(cls: type[MutableMultiMapping]) -> None:
     assert md3["b"] == 2  # Unchanged
     assert md3["c"] == 3  # New key added
 
+    # Test updating with args and kwargs
+    md4 = cls([("a", 1), ("b", 2)])  # ty: ignore [too-many-positional-arguments]
+    md4.update([("a", 999), ("c", 3)], a=4)
+    assert len(md4) == 4
+    assert md4["a"] == 999  # Replaced
+    assert md4["b"] == 2  # Unchanged
+    assert md4["c"] == 3  # New key added
+    assert md4.getall("a") == [999, 4]  # Both 'a' values present
+
 
 @pytest.mark.parametrize("cls", [MultiDict, ListMultiDict, multidict.MultiDict])
 def test_edge_cases_none_values(cls: type[MutableMultiMapping]) -> None: