typedmultidict 0.2.0__py3-none-any.whl

typedmultidict/__init__.py

@@ -0,0 +1,14 @@
+"""Pure-Python typed ordered multi-value dictionary with a case-insensitive variant."""
+
+from __future__ import annotations
+
+from ._cimultidict import CIMultiDict
+from ._multidict import MultiDict
+
+__version__ = "0.2.0"
+
+# Pickles name a class by its module: point them at the public one, which never moves.
+CIMultiDict.__module__ = __name__
+MultiDict.__module__ = __name__
+
+__all__ = ["CIMultiDict", "MultiDict"]

typedmultidict/_cimultidict.py

@@ -0,0 +1,31 @@
+"""Case-insensitive multi-value mapping for HTTP-style string keys."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from typing import ClassVar, TypeVar
+
+from ._multidict import MultiDict
+
+V = TypeVar("V")
+
+# Never equal to a stored token, so a key of the wrong type is simply absent on lookup.
+_NO_MATCH = object()
+
+
+class CIMultiDict(MultiDict[str, V]):
+    """Keys compare case-insensitively (``str.lower``); each pair keeps its own spelling.
+
+    Keys must be ``str`` (or a subclass): adding any other key raises ``TypeError``, while
+    looking one up simply finds nothing.
+    """
+
+    _folds_case: ClassVar[bool] = True
+
+    def _token(self, key: str) -> Hashable:
+        if not isinstance(key, str):
+            raise TypeError(f"{type(self).__name__} keys must be str, not {type(key).__name__}")
+        return str.lower(key)
+
+    def _probe(self, key: object) -> Hashable:
+        return str.lower(key) if isinstance(key, str) else _NO_MATCH

typedmultidict/_multidict.py

@@ -0,0 +1,170 @@
+"""Ordered mapping where a single key can hold several values."""
+
+from __future__ import annotations
+
+import copy as _copy
+from collections.abc import Hashable
+from typing import TYPE_CHECKING, Any, TypeVar, overload
+
+from ._pairs import MultiDictInput, read_pairs
+from ._storage import _Entry, _Storage
+from ._views import AllItemsView, AllValuesView
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from _typeshed import SupportsKeysAndGetItem
+
+K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
+T = TypeVar("T")
+Self = TypeVar("Self", bound="MultiDict[Any, Any]")
+
+_MISSING: Any = object()
+
+
+class MultiDict(_Storage[K, V]):
+    """A typed, insertion-ordered multi-value mapping.
+
+    Mapping operations act on the first value of each key, so the type behaves like a
+    normal mapping (``len()`` counts keys). The multi-value surface (``add``, ``getall``,
+    ``allitems`` and friends) sees every stored pair in insertion order.
+    """
+
+    def __init__(self, initial: MultiDictInput[K, V] | None = None) -> None:
+        self._setup()
+        if initial is not None:
+            self.extend(initial)
+
+    def _collect(self, source: object, extra: dict[str, Any]) -> list[tuple[Hashable, K, V]]:
+        pairs = read_pairs(source, _Storage)
+        pairs.extend(extra.items())
+        return [(self._token(key), key, value) for key, value in pairs]
+
+    def add(self, key: K, value: V) -> None:
+        """Append another value for ``key`` without replacing existing ones."""
+        self._append([(self._token(key), key, value)])
+
+    def extend(self, other: MultiDictInput[K, V]) -> None:
+        """Append every pair of a mapping, multi-dict or iterable of pairs."""
+        self._append(self._collect(other, {}))
+
+    def merge(self, other: MultiDictInput[K, V]) -> None:
+        """Append the pairs whose key is not present yet; keys already here are skipped."""
+        present = set(self._index)
+        self._append([item for item in self._collect(other, {}) if item[0] not in present])
+
+    @overload
+    def update(self, other: SupportsKeysAndGetItem[K, V], /) -> None: ...
+    @overload
+    def update(
+        self: MultiDict[str, V], other: SupportsKeysAndGetItem[str, V], /, **kwargs: V
+    ) -> None: ...
+    @overload
+    def update(self, other: Iterable[tuple[K, V]], /) -> None: ...
+    @overload
+    def update(self: MultiDict[str, V], other: Iterable[tuple[str, V]], /, **kwargs: V) -> None: ...
+    @overload
+    def update(self: MultiDict[str, V], /, **kwargs: V) -> None: ...
+
+    def update(self, other: Any = (), /, **kwargs: Any) -> None:
+        """Replace the values of every incoming key, reusing the old positions in order.
+
+        Extra new values go to the end, extra old values are removed, and keys that do
+        not appear in ``other`` are left alone.
+        """
+        # Plan first: every hash and key comparison happens before anything changes.
+        used: dict[Hashable, int] = {}
+        reused: list[tuple[_Entry, K, V]] = []
+        fresh: list[tuple[Hashable, K, V]] = []
+        for token, key, value in self._collect(other, kwargs):
+            slot = used.get(token, 0)
+            used[token] = slot + 1
+            entries = self._index.get(token, [])
+            if slot < len(entries):
+                reused.append((entries[slot], key, value))
+            else:
+                fresh.append((token, key, value))
+        stale = [entry for token, n in used.items() for entry in self._index.get(token, [])[n:]]
+        self._append(fresh)  # undoes itself if it fails; nothing after it can fail
+        for entry, key, value in reused:
+            entry.key = key
+            entry.value = value
+        self._drop(stale)
+
+    @overload
+    def getone(self, key: K) -> V: ...
+    @overload
+    def getone(self, key: K, default: T) -> V | T: ...
+
+    def getone(self, key: K, default: Any = _MISSING) -> Any:
+        """Return the first value for ``key``, else ``default`` or raise ``KeyError``."""
+        entries = self._index.get(self._probe(key))
+        if entries is not None:
+            return entries[0].value
+        if default is _MISSING:
+            raise KeyError(key)
+        return default
+
+    def getall(self, key: K) -> list[V]:
+        """Return a new list of every value for ``key`` in order, empty if absent."""
+        return [entry.value for entry in self._index.get(self._probe(key), ())]
+
+    @overload
+    def popone(self, key: K) -> V: ...
+    @overload
+    def popone(self, key: K, default: T) -> V | T: ...
+
+    def popone(self, key: K, default: Any = _MISSING) -> Any:
+        """Remove and return the first value for ``key``; later values stay."""
+        entries = self._index.get(self._probe(key))
+        if entries is None:
+            if default is _MISSING:
+                raise KeyError(key)
+            return default
+        first = entries[0]
+        self._drop([first])
+        return first.value
+
+    @overload
+    def popall(self, key: K) -> list[V]: ...
+    @overload
+    def popall(self, key: K, default: T) -> list[V] | T: ...
+
+    def popall(self, key: K, default: Any = _MISSING) -> Any:
+        """Remove and return every value for ``key``; raise ``KeyError`` if absent."""
+        entries = self._index.get(self._probe(key))
+        if entries is None:
+            if default is _MISSING:
+                raise KeyError(key)
+            return default
+        self._drop(list(entries))
+        return [entry.value for entry in entries]
+
+    def popitem(self) -> tuple[K, V]:
+        """Remove and return the last pair added; other values of its key stay."""
+        if not self._entries:
+            raise KeyError("popitem(): multi-dict is empty")
+        last = self._entries.pop()
+        entries = self._index[last.token]
+        entries.pop()
+        if not entries:
+            del self._index[last.token]
+        self._version += 1
+        return last.key, last.value
+
+    def allitems(self) -> AllItemsView[K, V]:
+        """A live view of every ``(key, value)`` pair in insertion order."""
+        return AllItemsView(self)
+
+    def allvalues(self) -> AllValuesView[V]:
+        """A live view of every value in insertion order."""
+        return AllValuesView(self)
+
+    def to_dict(self) -> dict[K, list[V]]:
+        """A new ``dict`` from each key (first spelling) to a new list of its values."""
+        return {key: self.getall(key) for key in self}
+
+    def copy(self: Self) -> Self:
+        """A shallow copy of the same type; values are shared, not copied."""
+        return _copy.copy(self)

typedmultidict/_pairs.py

@@ -0,0 +1,37 @@
+"""Reading bulk input (mappings, multi-dicts, iterables of pairs) before anything changes."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, TypeVar, Union
+
+if TYPE_CHECKING:
+    from _typeshed import SupportsKeysAndGetItem
+
+    from ._storage import _Storage
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+MultiDictInput = Union["SupportsKeysAndGetItem[K, V]", Iterable[tuple[K, V]]]
+
+
+def read_pairs(source: Any, storage_type: type[_Storage[Any, Any]]) -> list[tuple[Any, Any]]:
+    """Return every pair of ``source`` as a new list, validating each element first."""
+    if isinstance(source, storage_type):
+        return [(entry.key, entry.value) for entry in source._entries]
+    if hasattr(source, "keys"):
+        # The same test dict.update uses: anything with keys() is read as a mapping.
+        return [(key, source[key]) for key in source.keys()]  # noqa: SIM118
+    pairs: list[tuple[Any, Any]] = []
+    for position, item in enumerate(source):
+        try:
+            pair = tuple(item)
+        except TypeError:
+            raise TypeError(
+                f"element #{position} is not a (key, value) pair: {type(item).__name__}"
+            ) from None
+        if len(pair) != 2:
+            raise ValueError(f"element #{position} has length {len(pair)}; 2 is required")
+        pairs.append(pair)
+    return pairs

typedmultidict/_state.py

@@ -0,0 +1,48 @@
+"""Pickling and copying state: plain pairs plus whatever a subclass adds."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ._storage import _Storage
+
+# Rebuilt from the pairs, never copied as they are.
+_OWN = frozenset({"_entries", "_index", "_version"})
+
+
+def state_of(obj: _Storage[Any, Any]) -> tuple[Any, ...]:
+    """The pairs, the instance attributes and any subclass slots, in that order."""
+    pairs = [(entry.key, entry.value) for entry in obj._entries]
+    attrs = {name: value for name, value in vars(obj).items() if name not in _OWN}
+    slots = {name: getattr(obj, name) for name in _slot_names(type(obj)) if hasattr(obj, name)}
+    return pairs, attrs or None, slots or None
+
+
+def restore(obj: _Storage[Any, Any], state: Any) -> None:
+    """Fill an object made with ``__new__`` from ``state_of`` output or a 0.1.0 pickle."""
+    if isinstance(state, dict):
+        # 0.1.0 pickled the instance dictionary, with every pair under "_items".
+        attrs = {name: value for name, value in state.items() if name != "_items"}
+        pairs, slots = state.get("_items", []), None
+    else:
+        pairs, attrs, slots = state
+    vars(obj).update(attrs or {})
+    for name, value in (slots or {}).items():
+        object.__setattr__(obj, name, value)
+    # Attributes first: a subclass may need them to normalise its keys.
+    obj._setup()
+    obj._append([(obj._token(key), key, value) for key, value in pairs])
+
+
+def _slot_names(cls: type) -> list[str]:
+    names: list[str] = []
+    for klass in cls.__mro__:
+        declared = klass.__dict__.get("__slots__", ())
+        for name in [declared] if isinstance(declared, str) else declared:
+            if name in ("__dict__", "__weakref__"):
+                continue
+            if name.startswith("__") and not name.endswith("__"):
+                name = f"_{klass.__name__.lstrip('_')}{name}"
+            names.append(name)
+    return names

typedmultidict/_storage.py

@@ -0,0 +1,167 @@
+"""Indexed, insertion-ordered storage of key/value pairs behind the mapping protocol."""
+
+from __future__ import annotations
+
+import copyreg
+import reprlib
+from collections.abc import Hashable, Iterator, Mapping, MutableMapping
+from typing import Any, ClassVar, TypeVar
+
+from ._state import restore, state_of
+
+K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
+
+_CHANGED = "multi-dict changed during iteration"
+# Rebuilds with cls.__new__(cls); pickle encodes it as the compact NEWOBJ opcode.
+_NEWOBJ: Any = getattr(copyreg, "__newobj__")  # noqa: B009
+
+
+class _Entry:
+    __slots__ = ("key", "token", "value")
+
+    def __init__(self, token: Hashable, key: Any, value: Any) -> None:
+        self.token = token
+        self.key = key
+        self.value = value
+
+
+class _Storage(MutableMapping[K, V]):
+    # Pairs live in one ordered list; the index maps each key token to its entries in order,
+    # so lookups never scan the list. Only removals pay a linear pass. No __slots__: 0.1.0
+    # instances took extra attributes and weak references, and still do.
+
+    _folds_case: ClassVar[bool] = False
+
+    def _setup(self) -> None:
+        self._entries: list[_Entry] = []
+        self._index: dict[Hashable, list[_Entry]] = {}
+        self._version = 0
+
+    def _token(self, key: K) -> Hashable:
+        """The identity a key is stored under; raises for keys this mapping refuses."""
+        return key
+
+    def _probe(self, key: object) -> Hashable:
+        """The identity to look a key up by; a refused key matches nothing."""
+        return key
+
+    def _append(self, pairs: list[tuple[Hashable, K, V]]) -> None:
+        added: list[_Entry] = []
+        try:
+            for token, key, value in pairs:
+                entry = _Entry(token, key, value)
+                # A key whose __hash__ or __eq__ raises fails here; undo what came before.
+                self._index.setdefault(token, []).append(entry)
+                added.append(entry)
+        except BaseException:
+            for entry in reversed(added):
+                self._index[entry.token].pop()
+                if not self._index[entry.token]:
+                    del self._index[entry.token]
+            raise
+        self._entries.extend(added)
+        self._version += 1
+
+    def _drop(self, doomed: list[_Entry]) -> None:
+        if not doomed:
+            return
+        gone = {id(entry) for entry in doomed}
+        self._entries = [entry for entry in self._entries if id(entry) not in gone]
+        for token in {entry.token for entry in doomed}:
+            kept = [entry for entry in self._index[token] if id(entry) not in gone]
+            if kept:
+                self._index[token] = kept
+            else:
+                del self._index[token]
+        self._version += 1
+
+    def _iterate(self, version: int) -> Iterator[_Entry]:
+        # Checked before each step, so a change made between iter() and next() is caught.
+        for entry in self._entries:
+            if self._version != version:
+                raise RuntimeError(_CHANGED)
+            yield entry
+        if self._version != version:
+            raise RuntimeError(_CHANGED)
+
+    def __getitem__(self, key: K) -> V:
+        entries = self._index.get(self._probe(key))
+        if entries is None:
+            raise KeyError(key)
+        value: V = entries[0].value
+        return value
+
+    def __setitem__(self, key: K, value: V) -> None:
+        token = self._token(key)
+        entries = self._index.get(token)
+        if entries is None:
+            self._append([(token, key, value)])
+            return
+        first = entries[0]
+        first.key = key
+        first.value = value
+        self._drop(entries[1:])
+        self._version += 1
+
+    def __delitem__(self, key: K) -> None:
+        entries = self._index.get(self._probe(key))
+        if entries is None:
+            raise KeyError(key)
+        self._drop(list(entries))
+
+    def __contains__(self, key: object) -> bool:
+        return self._probe(key) in self._index
+
+    def __iter__(self) -> Iterator[K]:
+        # Not a generator itself, so the version is taken when iter() is called.
+        return self._first_keys(self._iterate(self._version))
+
+    def _first_keys(self, entries: Iterator[_Entry]) -> Iterator[K]:
+        seen: set[Hashable] = set()
+        for entry in entries:
+            if entry.token not in seen:
+                seen.add(entry.token)
+                yield entry.key
+
+    def __len__(self) -> int:
+        return len(self._index)
+
+    def clear(self) -> None:
+        self._entries = []
+        self._index = {}
+        self._version += 1
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, _Storage):
+            fold = self._folds_case or other._folds_case
+            return _compared(self._entries, fold) == _compared(other._entries, fold)
+        if isinstance(other, Mapping):
+            if not len(self._entries) == len(self._index) == len(other):
+                return False
+            return {e.key: e.value for e in self._entries} == dict(other.items())
+        return NotImplemented
+
+    __hash__ = None  # type: ignore[assignment]
+
+    @reprlib.recursive_repr()
+    def __repr__(self) -> str:
+        pairs = [(entry.key, entry.value) for entry in self._entries]
+        return f"{type(self).__name__}({pairs!r})"
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # The pairs travel as state, not as arguments, so an object that contains itself is
+        # memoised before its pairs are copied. Built with __new__: no __init__ is called.
+        return (_NEWOBJ, (type(self),), state_of(self))
+
+    def __setstate__(self, state: Any) -> None:
+        restore(self, state)
+
+
+def _compared(entries: list[_Entry], fold: bool) -> list[tuple[Any, Any]]:
+    if not fold:
+        return [(entry.token, entry.value) for entry in entries]
+    return [
+        (str.lower(entry.key) if isinstance(entry.key, str) else entry.key, entry.value)
+        for entry in entries
+    ]

typedmultidict/_views.py

@@ -0,0 +1,60 @@
+"""Live views over every stored pair or value, not just the first of each key."""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Hashable, Iterator
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from ._storage import _Storage
+
+K = TypeVar("K", bound=Hashable)
+V = TypeVar("V")
+
+
+class AllItemsView(Collection[tuple[K, V]], Generic[K, V]):
+    """Every ``(key, value)`` pair in insertion order; ``len()`` counts pairs."""
+
+    __slots__ = ("_mapping",)
+
+    def __init__(self, mapping: _Storage[K, V]) -> None:
+        self._mapping = mapping
+
+    def __len__(self) -> int:
+        return len(self._mapping._entries)
+
+    def __iter__(self) -> Iterator[tuple[K, V]]:
+        mapping = self._mapping
+        return ((entry.key, entry.value) for entry in mapping._iterate(mapping._version))
+
+    def __contains__(self, item: object) -> bool:
+        if not isinstance(item, tuple) or len(item) != 2:
+            return False
+        key, value = item
+        entries = self._mapping._index.get(self._mapping._probe(key), ())
+        return any(entry.value is value or entry.value == value for entry in entries)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({list(self)!r})"
+
+
+class AllValuesView(Collection[V], Generic[V]):
+    """Every value in insertion order; ``len()`` counts pairs."""
+
+    __slots__ = ("_mapping",)
+
+    def __init__(self, mapping: _Storage[Any, V]) -> None:
+        self._mapping = mapping
+
+    def __len__(self) -> int:
+        return len(self._mapping._entries)
+
+    def __iter__(self) -> Iterator[V]:
+        mapping = self._mapping
+        return (entry.value for entry in mapping._iterate(mapping._version))
+
+    def __contains__(self, value: object) -> bool:
+        return any(entry.value is value or entry.value == value for entry in self._mapping._entries)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({list(self)!r})"

typedmultidict-0.2.0.dist-info/METADATA

@@ -0,0 +1,213 @@
+Metadata-Version: 2.5
+Name: typedmultidict
+Version: 0.2.0
+Summary: Pure-Python typed ordered multi-value dictionary with a case-insensitive variant
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/typedmultidict
+Project-URL: Issues, https://github.com/JaviLianes8/typedmultidict/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/typedmultidict/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dictionary,headers,mapping,multi-value,multidict,typed
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: multidict; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: werkzeug; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# typedmultidict
+
+Pure-Python typed ordered multi-value dictionary with a case-insensitive variant.
+
+## Install
+
+```
+pip install typedmultidict
+```
+
+## Usage
+
+A `MultiDict[K, V]` is a normal mapping over the first value of each key, plus methods
+that see every value. Pairs keep their insertion order across keys.
+
+```python
+from typedmultidict import MultiDict
+
+params: MultiDict[str, str] = MultiDict([("tag", "python"), ("page", "2")])
+params.add("tag", "typing")
+
+print(params["tag"])  # python
+print(params.getall("tag"))  # ['python', 'typing']
+print(len(params), len(params.allitems()))  # 2 3
+print(list(params.allitems()))  # [('tag', 'python'), ('page', '2'), ('tag', 'typing')]
+print(dict(params))  # {'tag': 'python', 'page': '2'}
+print(params.to_dict())  # {'tag': ['python', 'typing'], 'page': ['2']}
+```
+
+Assigning replaces every value of a key in the position of its first one; removing can
+take the first value, every value, or the last pair added:
+
+```python
+from typedmultidict import MultiDict
+
+md = MultiDict([("a", 1), ("b", 2), ("a", 3), ("a", 4)])
+md["a"] = 9
+print(md)  # MultiDict([('a', 9), ('b', 2)])
+
+md.extend([("a", 5), ("c", 6)])
+print(md.popone("a"), md.getall("a"))  # 9 [5]
+print(md.popall("a"), "a" in md)  # [5] False
+print(md.popitem(), md)  # ('c', 6) MultiDict([('b', 2)])
+print(md.getone("missing", "default"))  # default
+```
+
+`extend` appends, `merge` only adds keys that are not present yet, and `update` replaces
+the values of each incoming key in place (extra new values go to the end, extra old
+values are dropped):
+
+```python
+from typedmultidict import MultiDict
+
+md = MultiDict([("a", 1), ("b", 2), ("a", 3)])
+md.merge([("a", 0), ("c", 4)])
+print(md)  # MultiDict([('a', 1), ('b', 2), ('a', 3), ('c', 4)])
+md.update([("a", 7), ("a", 8), ("a", 9)], b=0)
+print(md)  # MultiDict([('a', 7), ('b', 0), ('a', 8), ('c', 4), ('a', 9)])
+```
+
+`CIMultiDict[V]` has `str` keys compared case-insensitively. Every pair keeps the spelling
+it was added with, and keys are listed in the spelling of their first pair:
+
+```python
+from typedmultidict import CIMultiDict
+
+headers: CIMultiDict[str] = CIMultiDict()
+headers.add("Set-Cookie", "a=1")
+headers.add("set-cookie", "b=2")
+headers.add("Content-Type", "text/html")
+
+print(headers["SET-COOKIE"])  # a=1
+print(headers.getall("set-cookie"))  # ['a=1', 'b=2']
+print(list(headers))  # ['Set-Cookie', 'Content-Type']
+print(5 in headers)  # False
+```
+
+Views from `allitems()` and `allvalues()` follow the mapping. Changing the mapping while
+iterating over it, or over any of its views, raises `RuntimeError`. As in `multidict`,
+every write counts, even replacing a value in place (which `dict` allows):
+
+```python
+from typedmultidict import MultiDict
+
+md = MultiDict([("a", 1)])
+pairs = md.allitems()
+md.add("a", 2)
+print(len(pairs), ("a", 2) in pairs)  # 2 True
+try:
+    for key in md:
+        md.add("b", 3)
+except RuntimeError as error:
+    print(error)  # multi-dict changed during iteration
+```
+
+Equality, copies and pickles:
+
+```python
+import pickle
+
+from typedmultidict import CIMultiDict, MultiDict
+
+print(MultiDict([("a", 1), ("b", 2)]) == MultiDict([("b", 2), ("a", 1)]))  # False
+print(MultiDict([("a", 1), ("b", 2)]) == {"b": 2, "a": 1})  # True
+print(MultiDict([("a", 1), ("a", 2)]) == {"a": 1})  # False
+print(CIMultiDict([("A", 1)]) == MultiDict([("a", 1)]))  # True
+
+headers = CIMultiDict([("X-Id", "1")])
+print(pickle.loads(pickle.dumps(headers)))  # CIMultiDict([('X-Id', '1')])
+print(headers.copy() == headers, headers.copy() is headers)  # True False
+```
+
+## API
+
+| Name | What it does |
+| --- | --- |
+| `MultiDict[K, V](initial=None)` | Ordered multi-value mapping. `initial` is a mapping, a multi-dict (every pair is copied) or an iterable of pairs. `K` must be hashable. |
+| `CIMultiDict[V](initial=None)` | `MultiDict[str, V]` whose keys compare with `str.lower`. A non-`str` key raises `TypeError` when added and is absent when looked up. |
+| `md[key]`, `get`, `in`, `keys`, `items`, `values`, `len()`, iteration | The `Mapping` view: first value of each key, keys once each. |
+| `md[key] = value` | Replaces every value of `key` with one, in the place of the first. |
+| `del md[key]`, `pop(key[, default])` | Remove every value of `key` (`pop` returns the first). |
+| `setdefault(key[, default])` | First value of `key`, or adds `default`. |
+| `add(key, value)` | Appends one more pair. |
+| `extend(other)` | Appends every pair of `other`. |
+| `merge(other)` | Appends the pairs whose key is not present yet. |
+| `update(other=(), /, **kwargs)` | Replaces the values of each incoming key in place. |
+| `getone(key[, default])` | First value, else `default`, else `KeyError`. |
+| `getall(key)` | New list of every value of `key`, empty if absent. |
+| `popone(key[, default])` | Removes and returns the first value only. |
+| `popall(key[, default])` | Removes and returns every value as a list. |
+| `popitem()` | Removes and returns the last pair added (`KeyError` when empty). |
+| `allitems()`, `allvalues()` | Live views of every pair or value; `len()` counts pairs. |
+| `to_dict()` | New `dict` from each key to a new list of its values. |
+| `copy()`, `clear()` | Shallow copy of the same class; remove everything. |
+
+Bulk input (`initial`, `extend`, `merge`, `update`) is read and checked in full first: an
+element that is not a pair raises `TypeError`, one of the wrong length raises
+`ValueError`, both with its position, and the mapping is left unchanged. Lookups cost the
+same whatever the size; removals are linear in the number of pairs.
+
+### Compared with `multidict` and Werkzeug
+
+The method names and their behaviour follow the `multidict` package, with two
+differences that keep the type a consistent `Mapping`: `len()` counts keys (use
+`len(md.allitems())` for pairs), and `keys`, `items` and `values` show the first value of
+each key, as Werkzeug's `MultiDict` does. `getall` returns an empty list for a missing
+key instead of raising, and `pop` removes every value of the key.
+
+Like `dict`, a multi-dict is not safe to change from several threads at once without a
+lock. Equality between a plain and a case-insensitive multi-dict folds case, so it is not
+transitive across the two kinds. Any other mapping, a `multidict.MultiDict` included, is
+compared as a plain mapping.
+
+## Why
+
+HTTP headers and query strings routinely carry repeated keys, so a mapping that keeps every
+value is a common need. The existing options each fall short for a plain, typed project:
+
+- `multidict` (the aiohttp one) is a C extension; its pure-Python fallback runs many times
+  slower and still needs a build step for the fast path.
+- `orderedmultidict` depends on `six` and ships no type hints.
+- The `MultiDict` types in `werkzeug` and `starlette` come bundled with a whole framework.
+
+`typedmultidict` is a single, standalone, fully typed implementation with `py.typed`, zero
+runtime dependencies and no compilation. Reach for it when you want multi-value semantics
+and `mypy --strict` support without pulling in a framework or a native wheel.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

typedmultidict-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+typedmultidict/__init__.py,sha256=90bOn67mLk-o-D4t_arZgGJ_Q-QyDDZPSXm0ohVZXzg,414
+typedmultidict/_cimultidict.py,sha256=E4-RwWKHJGJNtImANf7bdw5_IkTdz9oRJuOrsMC1YwE,982
+typedmultidict/_multidict.py,sha256=cBeU1g_FOGmvJqVIVZ3VjO-KWrAeK9KN_YrpnI8M1Rk,6535
+typedmultidict/_pairs.py,sha256=oHn0QYCCkIyu5kDefg-Pf0HbKaDaFrSnk8b3X050UOk,1387
+typedmultidict/_state.py,sha256=SpPqUmeUNqnYYJdpM3GkO06qJ5D9bCt8kTZSq54LqIg,1962
+typedmultidict/_storage.py,sha256=UvTToMueIpkUAc9KiYjJSptxLGYOC2u-9DUYLYls5rM,5959
+typedmultidict/_views.py,sha256=UHlDkYRy6NqE-rf0blKvVRpCWz2YYfh1eF6s9whe-iM,1961
+typedmultidict/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+typedmultidict-0.2.0.dist-info/METADATA,sha256=9l0M9y55cJVSUf_bqBtxDgq50z7_Gbqj3vP7yCthfgI,8855
+typedmultidict-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+typedmultidict-0.2.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+typedmultidict-0.2.0.dist-info/RECORD,,

typedmultidict-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

typedmultidict-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.