multidict

Warnings

• gotcha d['key'] returns only the FIRST value for a duplicated key. Iterating .keys() yields ALL keys including duplicates. Use getall('key') to fetch every value.
  Fix: Replace d['key'] with d.getall('key') when multiple values per key are expected.
• gotcha d['key'] = value replaces ALL existing entries for that key with a single entry, not just the first. Use d.add('key', value) to append without clobbering existing values.
  Fix: Use d.add(key, value) to append a value while preserving existing entries for the same key.
• breaking 6.5.0 switched the internal storage from a linear array (O(N) lookups) to a hash table (O(1) lookups). MultiDict.add() and extend() are now 25-50% slower; single lookups are 25-50% faster and bulk operations are 2-3x faster. Code relying on iteration order of keys() after deletions may observe subtly different compaction behaviour.
  Fix: Upgrade to >=6.5.1 which fixes a resize-with-deleted-slots bug introduced in 6.5.0. Treat key iteration order as insertion-order stable but do not assume slot density.
• breaking MultiDictProxy and CIMultiDictProxy raise TypeError if passed a plain dict or any non-MultiDict mapping. They only accept the matching MultiDict subclass.
  Fix: Wrap the source mapping in MultiDict() first: MultiDictProxy(MultiDict(plain_dict)).
• gotcha Setting MULTIDICT_NO_EXTENSIONS=1 at runtime forces the pure-Python implementation even when the C extension wheel is installed. The pure-Python path is roughly 20-50x slower. This env var also suppresses C extension compilation at build time if set during pip install.
  Fix: Do not set MULTIDICT_NO_EXTENSIONS in production. For Alpine Linux / source builds without a C compiler, the pure-Python wheel is automatically used as a fallback starting with 6.x.
• deprecated Directly importing from private submodules multidict._multidict (C extension) or multidict._multidict_py (pure Python) is not part of the public API and can break across patch releases. The internal _Impl class was removed from the pure-Python implementation in 6.4.x.
  Fix: Always import from the top-level package: from multidict import MultiDict, CIMultiDict, ...
• gotcha CIMultiDict stores and returns keys as istr (a str subclass with preserved original case), not plain str. Identity or strict type checks against str will pass since istr derives from str, but isinstance checks for exactly str may differ from expectations when iterating keys.
  Fix: Use str(key) if you need a plain str, or compare with == rather than 'is'. istr is a subclass of str so equality checks work normally.

Install

• pip install multidict Latest (with C extension)
• MULTIDICT_NO_EXTENSIONS=1 pip install multidict Pure-Python fallback (20-50x slower)

Imports

• MultiDict

  from multidict import MultiDict

  Never import from the private _multidict (C) or _multidict_py (pure-Python) submodules directly; always import from the top-level multidict package.
• CIMultiDict

  from multidict import CIMultiDict

  Private submodule imports bypass the C/Python dispatch and are not part of the public API.
• MultiDictProxy

  from multidict import MultiDictProxy

  MultiDictProxy raises TypeError if the argument is not a MultiDict instance — it cannot wrap a plain dict.
• CIMultiDictProxy

  from multidict import CIMultiDictProxy

  CIMultiDictProxy raises TypeError if the argument is not a CIMultiDict instance.
• istr

  from multidict import istr

  Use istr for pre-folded keys with CIMultiDict to avoid redundant lower() calls in hot paths.
• getall

  d.getall('key')

  d['key'] returns only the FIRST value for a key. Use getall() to retrieve all values for a duplicated key.

Quickstart

Demonstrates mutable MultiDict with duplicate keys, getall, add, and a case-insensitive CIMultiDict.

from multidict import MultiDict, MultiDictProxy, CIMultiDict, istr

# --- Mutable multi-valued dict ---
d = MultiDict([('a', 1), ('b', 2), ('a', 3)])
assert d['a'] == 1              # returns FIRST value only
assert d.getall('a') == [1, 3] # all values for key
d.add('b', 99)                  # append without replacing
assert len(d) == 4

# --- set() replaces ALL entries for that key ---
d['a'] = 99
assert d.getall('a') == [99]

# --- Read-only proxy (dynamic view) ---
proxy = MultiDictProxy(d)
assert proxy['b'] == 2
d.add('b', 42)
assert proxy.getall('b') == [2, 99, 42]  # proxy reflects changes

# --- Case-insensitive dict ---
ci = CIMultiDict(Content_Type='application/json')
assert 'content-type' in ci
assert ci['CONTENT-TYPE'] == 'application/json'

# --- istr for pre-folded keys (performance) ---
HDR = istr('Content-Type')
assert ci[HDR] == 'application/json'

# --- merge (6.6+): copies key only if not already present ---
base = MultiDict(a=1)
base.merge(MultiDict(a=99, b=2))
assert base['a'] == 1   # not overwritten
assert base['b'] == 2