multidict

Multidicts are useful for working with HTTP headers, URL query args etc.

The code was extracted from aiohttp library.

Introduction

HTTP Headers and URL query string require specific data structure: multidict. It behaves mostly like a regular dict but it may have several values for the same key and preserves insertion ordering.

The key is str (or istr for case-insensitive dictionaries).

multidict has four multidict classes: MultiDict, MultiDictProxy, CIMultiDict and CIMultiDictProxy.

Immutable proxies (MultiDictProxy and CIMultiDictProxy) provide a dynamic view for the proxied multidict, the view reflects underlying collection changes. They implement the Mapping interface.

Regular mutable (MultiDict and CIMultiDict) classes implement MutableMapping and allows to change their own content.

Case insensitive (CIMultiDict and CIMultiDictProxy) ones assume the keys are case insensitive, e.g.:

>>> dct = CIMultiDict(key='val')
>>> 'Key' in dct
True
>>> dct['Key']
'val'

Keys should be either str or istr instance.

The library has optional C Extensions for sake of speed.

Other C extensions can build against multidict’s own C API to create and manipulate multidicts directly, or from Cython.

Both the C extension and the pure-Python fallback are optimized for free-threaded (no-GIL) Python as well as the regular GIL build, and their performance is in the same ballpark as the built-in dict, typically within 20-30% for common operations, since dict itself benefits from per-version interpreter specializations that a third-party type cannot hook into. See Benchmarks for the full per-operation breakdown of the C extension on both builds, and the free-threading overhead figures for the pure-Python fallback.

Library Installation

$ pip install multidict

The library is Python 3 only!

PyPI contains binary wheels for Linux, Windows and MacOS. If you want to install multidict on another operation system (or Alpine Linux inside a Docker) the Tarball will be used to compile the library from sources. It requires C compiler and Python headers installed.

To skip the compilation please use the MULTIDICT_NO_EXTENSIONS environment variable, e.g.:

$ MULTIDICT_NO_EXTENSIONS=1 pip install multidict

Please note, the pure Python (uncompiled) version is dramatically slower: the pure-Python backend table in Benchmarks measures it at about 40 times more instructions than the C extension, averaged over the measured operations. Unless the target platform genuinely cannot build the C extension, leave MULTIDICT_NO_EXTENSIONS unset and let it compile.

Source code

The project is hosted on GitHub

Please file an issue on the bug tracker if you have found a bug or have some suggestion in order to improve the library.

Authors and License

The multidict package is written by Andrew Svetlov.

It’s Apache 2 licensed and freely available.

Contents

Indices and tables