multidict

multidict is a dictionary-like data structure that allows multiple values per key while preserving insertion order — something Python’s built-in dict cannot do. It ships four concrete types: MultiDict and CIMultiDict for mutable use, and MultiDictProxy/CIMultiDictProxy as read-only dynamic views over an existing multidict. The CI-prefixed variants treat keys case-insensitively via a dedicated istr string subclass, matching exactly the behavior HTTP headers require.

Under the hood, multidict maintains two parallel implementations: a pure-Python reference implementation and an optional C extension that reimplements a CPython-style hash table to support duplicate keys efficiently, delivering roughly a 20-50x speedup over the Python fallback. Both implementations are validated against the same test suite to guarantee identical behavior, and the library underpins aiohttp and yarl, where it is exercised millions of times across the Python web ecosystem.

What You Get

• MultiDict and CIMultiDict mutable multi-value dict types, plus MultiDictProxy/CIMultiDictProxy read-only dynamic views
• A C-accelerated backend (enabled by default) with automatic fallback to a pure-Python implementation via MULTIDICT_NO_EXTENSIONS
• istr, a case-insensitive string subclass powering the CI* variants for header-style lookups
• Full collections.abc.Mapping/MutableMapping compatibility via structural Protocol-based ABCs so multidicts type-check and duck-type like ordinary dicts
• Pickling, copying, and .pyi type stubs validated by a dedicated mypy test suite

Common Use Cases

• Representing HTTP request/response headers, where the same header name can legitimately appear multiple times
• Parsing and building URL query strings with repeated parameter names (?tag=a&tag=b)
• Form data and multipart payloads where a field name can carry more than one value
• Any application-level key/value store that needs case-insensitive lookups without losing duplicate entries

Under The Hood

Architecture multidict maintains two parallel implementations selected at import time by _compat.USE_EXTENSIONS: a pure-Python reference (_multidict_py.py) and an optional C extension (_multidict.c plus the _multilib/ headers — hashtable.h, htkeys.h, views.h, istr.h, iter.h, parser.h, state.h). Both backends implement the same four concrete classes and register against shared MultiMapping/MutableMultiMapping Protocol-based ABCs defined in _abc.py, so callers, isinstance() checks, and type checkers see one consistent interface regardless of which backend is active. Immutable proxies wrap a live reference to the underlying multidict rather than copying it, so proxy views reflect later mutations.

Tech Stack Pure-Python 3.10+ core with an optional CPython C extension, built via setuptools and distributed as prebuilt wheels across platforms using cibuildwheel (with uv as the build/test installer for speed). No runtime dependencies beyond a typing-extensions backport for Python < 3.11. Documentation is built with Sphinx and published to Read the Docs; the changelog is managed with towncrier.

Code Quality Testing is unusually thorough for a data-structure library: test_multidict.py, test_mutable_multidict.py, test_istr.py, test_abc.py, test_copy.py, test_pickle.py, and test_update.py exercise both backends through shared parametrized fixtures to guarantee behavioral parity, test_leaks.py specifically hunts for C-extension reference leaks, and test_mypy.py validates the .pyi type stubs against real usage. ruff enforces import sorting, a ban on mid-function imports, and pyupgrade rules repo-wide; coverage is tracked via Codecov, and CI (ci-cd.yml, reusable-linters.yml, codeql.yml) runs on every push, pull request, and a daily schedule.

API Design The public API mirrors dict deliberately — indexing, .get(), .items(), iteration, and dict-style construction all work unchanged, so only the multi-value-specific methods (add, getall, extend, popall, and friends) are new to learn. Case-insensitivity is opt-in via a parallel CIMultiDict/istr type rather than a runtime flag, keeping the common case simple. Every method in the Sphinx reference carries a doctested usage example, and pip install multidict gives a working C-accelerated build with zero configuration, with MULTIDICT_NO_EXTENSIONS=1 as an explicit escape hatch.