or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

case-insensitive.mdimmutable-proxies.mdindex.mdmutable-multidict.mdstring-types-utilities.md
tile.json

tessl/pypi-multidict

Dictionary-like collection where keys can occur multiple times, optimized for HTTP headers and URL query strings

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/multidict@6.6.x

To install, run

npx @tessl/cli install tessl/pypi-multidict@6.6.0

index.mddocs/

Multidict

A high-performance dictionary-like collection where keys can occur multiple times, specifically designed for HTTP headers, URL query strings, and other web development scenarios. Multidict preserves insertion order and provides both mutable and immutable variants with case-sensitive and case-insensitive key handling.

Package Information

  • Package Name: multidict
  • Package Type: pypi
  • Language: Python
  • Installation: pip install multidict
  • Python Support: 3.9+
  • Performance: Optional C extensions provide 20-50x speedup over pure Python

Core Imports

from multidict import MultiDict, CIMultiDict, MultiDictProxy, CIMultiDictProxy

Import specific types and utilities:

from multidict import MultiMapping, MutableMultiMapping, istr, upstr, getversion

Access version information:

from multidict import __version__
print(__version__)  # '6.6.4'

Basic Usage

from multidict import MultiDict, CIMultiDict

# Create a mutable multidict for HTTP headers
headers = MultiDict([
    ('Accept', 'text/html'),
    ('Accept', 'application/json'),
    ('User-Agent', 'MyApp/1.0')
])

# Access first value (dict-like behavior)
print(headers['Accept'])  # 'text/html'

# Get all values for a key
print(headers.getall('Accept'))  # ['text/html', 'application/json']

# Add more values
headers.add('Accept', 'text/plain')
print(headers.getall('Accept'))  # ['text/html', 'application/json', 'text/plain']

# Case-insensitive multidict for HTTP headers
ci_headers = CIMultiDict([('content-type', 'text/html')])
print(ci_headers['Content-Type'])  # 'text/html' (case-insensitive access)

# Create immutable proxy
proxy = headers.copy()  # Returns MultiDict
readonly_proxy = MultiDictProxy(headers)  # Immutable view

Architecture

Multidict provides a four-class hierarchy optimized for web development:

  • Mutable Classes: MultiDict (case-sensitive) and CIMultiDict (case-insensitive) for modifiable collections
  • Immutable Proxies: MultiDictProxy and CIMultiDictProxy for read-only views
  • Abstract Interfaces: MultiMapping and MutableMultiMapping define the protocol
  • String Types: istr class provides case-insensitive string handling
  • Performance Layer: Optional C extensions with automatic fallback to pure Python

The design maintains standard dict-like interfaces while extending functionality for multi-valued keys, making it ideal for HTTP headers, form data, and URL parameters where duplicate keys are meaningful.

Capabilities

Mutable Multidict Operations

Core functionality for creating and modifying multidict collections with support for multiple values per key, including specialized methods for web development scenarios.

class MultiDict(MutableMultiMapping[_V]):
    def __init__(self, arg: MDArg[_V] = None, /, **kwargs: _V): ...
    def add(self, key: str, value: _V) -> None: ...
    def getall(self, key: str) -> List[_V]: ...
    def getall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
    def getone(self, key: str) -> _V: ...
    def getone(self, key: str, default: _T) -> Union[_V, _T]: ...
    def extend(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None: ...
    def merge(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None: ...
    def popall(self, key: str) -> List[_V]: ...
    def popall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
    def popone(self, key: str) -> _V: ...
    def popone(self, key: str, default: _T) -> Union[_V, _T]: ...
    def copy(self) -> 'MultiDict[_V]': ...

Mutable Multidict

Case-Insensitive Operations

Case-insensitive multidict functionality optimized for HTTP headers and similar protocols where key casing should be ignored.

class CIMultiDict(MultiDict[_V]):
    def __init__(self, arg: MDArg[_V] = None, /, **kwargs: _V): ...
    # Inherits all MultiDict methods with case-insensitive key handling
    def copy(self) -> 'CIMultiDict[_V]': ...

Case-Insensitive Multidict

Immutable Proxy Views

Read-only proxy interfaces that provide safe access to multidict data without allowing modifications, useful for exposing internal state safely.

class MultiDictProxy(MultiMapping[_V]):
    def __init__(self, multidict: Union[MultiDict[_V], MultiDictProxy[_V]]): ...
    def getall(self, key: str) -> List[_V]: ...
    def getall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
    def getone(self, key: str) -> _V: ...
    def getone(self, key: str, default: _T) -> Union[_V, _T]: ...
    def copy(self) -> MultiDict[_V]: ...

class CIMultiDictProxy(MultiDictProxy[_V]):
    def __init__(self, ci_multidict: Union[CIMultiDict[_V], CIMultiDictProxy[_V]]): ...
    def copy(self) -> CIMultiDict[_V]: ...

Immutable Proxies

String Types and Utilities

Specialized string handling and utility functions for multidict operations, including case-insensitive strings and version tracking.

class istr(str):
    """Case-insensitive string type"""
    def __new__(cls, val=''): ...

# Legacy alias for istr
upstr = istr

def getversion(md) -> int:
    """Get internal version number for change detection"""

String Types and Utilities

Types

from typing import Union, List, Optional, TypeVar, Iterable, Mapping, Protocol
from collections.abc import MutableMapping, Iterator, KeysView, ItemsView, ValuesView

_V = TypeVar('_V')
_V_co = TypeVar('_V_co', covariant=True) 
_T = TypeVar('_T')

# Protocol types for constructor arguments
class SupportsKeys(Protocol[_V_co]):
    def keys(self) -> Iterable[str]: ...
    def __getitem__(self, key: str, /) -> _V_co: ...

class SupportsIKeys(Protocol[_V_co]):
    def keys(self) -> Iterable[istr]: ...
    def __getitem__(self, key: istr, /) -> _V_co: ...

# Constructor argument types
MDArg = Union[
    SupportsKeys[_V],
    SupportsIKeys[_V], 
    Iterable[tuple[str, _V]], 
    None
]

# Abstract base classes
class MultiMapping(Mapping[str, _V]):
    def getall(self, key: str) -> List[_V]: ...
    def getall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
    def getone(self, key: str) -> _V: ...
    def getone(self, key: str, default: _T) -> Union[_V, _T]: ...

class MutableMultiMapping(MultiMapping[_V], MutableMapping[str, _V]):
    def add(self, key: str, value: _V) -> None: ...
    def extend(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None: ...
    def merge(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None: ... 
    def popone(self, key: str) -> _V: ...
    def popone(self, key: str, default: _T) -> Union[_V, _T]: ...
    def popall(self, key: str) -> List[_V]: ...
    def popall(self, key: str, default: _T) -> Union[List[_V], _T]: ...