0
# Multidict
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: multidict
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install multidict`
10
- **Python Support**: 3.9+
11
- **Performance**: Optional C extensions provide 20-50x speedup over pure Python
12

13
## Core Imports
14

15
```python
16
from multidict import MultiDict, CIMultiDict, MultiDictProxy, CIMultiDictProxy
17
```
18

19
Import specific types and utilities:
20

21
```python
22
from multidict import MultiMapping, MutableMultiMapping, istr, upstr, getversion
23
```
24

25
Access version information:
26

27
```python
28
from multidict import __version__
29
print(__version__)  # '6.6.4'
30
```
31

32
## Basic Usage
33

34
```python
35
from multidict import MultiDict, CIMultiDict
36

37
# Create a mutable multidict for HTTP headers
38
headers = MultiDict([
39
    ('Accept', 'text/html'),
40
    ('Accept', 'application/json'),
41
    ('User-Agent', 'MyApp/1.0')
42
])
43

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

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

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

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

58
# Create immutable proxy
59
proxy = headers.copy()  # Returns MultiDict
60
readonly_proxy = MultiDictProxy(headers)  # Immutable view
61
```
62

63
## Architecture
64

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

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

73
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.
74

75
## Capabilities
76

77
### Mutable Multidict Operations
78

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

81
```python { .api }
82
class MultiDict(MutableMultiMapping[_V]):
83
    def __init__(self, arg: MDArg[_V] = None, /, **kwargs: _V): ...
84
    def add(self, key: str, value: _V) -> None: ...
85
    def getall(self, key: str) -> List[_V]: ...
86
    def getall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
87
    def getone(self, key: str) -> _V: ...
88
    def getone(self, key: str, default: _T) -> Union[_V, _T]: ...
89
    def extend(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None: ...
90
    def merge(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None: ...
91
    def popall(self, key: str) -> List[_V]: ...
92
    def popall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
93
    def popone(self, key: str) -> _V: ...
94
    def popone(self, key: str, default: _T) -> Union[_V, _T]: ...
95
    def copy(self) -> 'MultiDict[_V]': ...
96
```
97

98
[Mutable Multidict](./mutable-multidict.md)
99

100
### Case-Insensitive Operations
101

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

104
```python { .api }
105
class CIMultiDict(MultiDict[_V]):
106
    def __init__(self, arg: MDArg[_V] = None, /, **kwargs: _V): ...
107
    # Inherits all MultiDict methods with case-insensitive key handling
108
    def copy(self) -> 'CIMultiDict[_V]': ...
109
```
110

111
[Case-Insensitive Multidict](./case-insensitive.md)
112

113
### Immutable Proxy Views
114

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

117
```python { .api }
118
class MultiDictProxy(MultiMapping[_V]):
119
    def __init__(self, multidict: Union[MultiDict[_V], MultiDictProxy[_V]]): ...
120
    def getall(self, key: str) -> List[_V]: ...
121
    def getall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
122
    def getone(self, key: str) -> _V: ...
123
    def getone(self, key: str, default: _T) -> Union[_V, _T]: ...
124
    def copy(self) -> MultiDict[_V]: ...
125

126
class CIMultiDictProxy(MultiDictProxy[_V]):
127
    def __init__(self, ci_multidict: Union[CIMultiDict[_V], CIMultiDictProxy[_V]]): ...
128
    def copy(self) -> CIMultiDict[_V]: ...
129
```
130

131
[Immutable Proxies](./immutable-proxies.md)
132

133
### String Types and Utilities
134

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

137
```python { .api }
138
class istr(str):
139
    """Case-insensitive string type"""
140
    def __new__(cls, val=''): ...
141

142
# Legacy alias for istr
143
upstr = istr
144

145
def getversion(md) -> int:
146
    """Get internal version number for change detection"""
147
```
148

149
[String Types and Utilities](./string-types-utilities.md)
150

151
## Types
152

153
```python { .api }
154
from typing import Union, List, Optional, TypeVar, Iterable, Mapping, Protocol
155
from collections.abc import MutableMapping, Iterator, KeysView, ItemsView, ValuesView
156

157
_V = TypeVar('_V')
158
_V_co = TypeVar('_V_co', covariant=True) 
159
_T = TypeVar('_T')
160

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

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

170
# Constructor argument types
171
MDArg = Union[
172
    SupportsKeys[_V],
173
    SupportsIKeys[_V], 
174
    Iterable[tuple[str, _V]], 
175
    None
176
]
177

178
# Abstract base classes
179
class MultiMapping(Mapping[str, _V]):
180
    def getall(self, key: str) -> List[_V]: ...
181
    def getall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
182
    def getone(self, key: str) -> _V: ...
183
    def getone(self, key: str, default: _T) -> Union[_V, _T]: ...
184

185
class MutableMultiMapping(MultiMapping[_V], MutableMapping[str, _V]):
186
    def add(self, key: str, value: _V) -> None: ...
187
    def extend(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None: ...
188
    def merge(self, arg: MDArg[_V] = None, /, **kwargs: _V) -> None: ... 
189
    def popone(self, key: str) -> _V: ...
190
    def popone(self, key: str, default: _T) -> Union[_V, _T]: ...
191
    def popall(self, key: str) -> List[_V]: ...
192
    def popall(self, key: str, default: _T) -> Union[List[_V], _T]: ...
193
```