Collections¶

These datastructures are used to implement the behaviour of various urllib3 components in a decoupled and application-agnostic design.

class urllib3._collections.RecentlyUsedContainer(maxsize: int = 10, dispose_func: Callable[[_VT], None] | None = None)[source]¶

Provides a thread-safe dict-like container which maintains up to maxsize keys while throwing away the least-recently-used keys beyond maxsize.

Parameters:

maxsize – Maximum number of recent elements to retain.
dispose_func – Every time an item is evicted from the container, dispose_func(value) is called. Callback which will get called

clear() → None. Remove all items from D.[source]¶

keys() → a set-like object providing a view on D's keys[source]¶

class urllib3._collections.HTTPHeaderDict(headers: ValidHTTPHeaderSource | None = None, **kwargs: str)[source]¶

Parameters:

headers – An iterable of field-value pairs. Must not contain multiple field names when compared case-insensitively.
kwargs – Additional field-value pairs to pass in to dict.update.

A dict like container for storing HTTP Headers.

Field names are stored and compared case-insensitively in compliance with RFC 7230. Iteration provides the first case-sensitive key seen for each case-insensitive pair.

Using __setitem__ syntax overwrites fields that compare equal case-insensitively in order to maintain dict’s api. For fields that compare equal, instead create a new HTTPHeaderDict and use .add in a loop.

If multiple fields that are equal case-insensitively are passed to the constructor or .update, the behavior is undefined and some will be lost.

>>> headers = HTTPHeaderDict()
>>> headers.add('Set-Cookie', 'foo=bar')
>>> headers.add('set-cookie', 'baz=quxx')
>>> headers['content-length'] = '7'
>>> headers['SET-cookie']
'foo=bar, baz=quxx'
>>> headers['Content-Length']
'7'

add(key: str, val: str, *, combine: bool = False) → None[source]¶

Adds a (name, value) pair, doesn’t overwrite the value if it already exists.

If this is called with combine=True, instead of adding a new header value as a distinct item during iteration, this will instead append the value to any existing header value with a comma. If no existing header value exists for the key, then the value will simply be added, ignoring the combine parameter.

>>> headers = HTTPHeaderDict(foo='bar')
>>> headers.add('Foo', 'baz')
>>> headers['foo']
'bar, baz'
>>> list(headers.items())
[('foo', 'bar'), ('foo', 'baz')]
>>> headers.add('foo', 'quz', combine=True)
>>> list(headers.items())
[('foo', 'bar, baz, quz')]

extend(*args: ValidHTTPHeaderSource, **kwargs: str) → None[source]¶: Generic import function for any type of header-like object. Adapted version of MutableMapping.update in order to insert items with self.add instead of self.__setitem__

get_all(key: str, default: _Sentinel | _DT = _Sentinel.not_passed) → list[str] | _DT¶: Returns a list of all the values for the named field. Returns an empty list if the key doesn’t exist.

getallmatchingheaders(key: str, default: _Sentinel | _DT = _Sentinel.not_passed) → list[str] | _DT¶: Returns a list of all the values for the named field. Returns an empty list if the key doesn’t exist.

getheaders(key: str, default: _Sentinel | _DT = _Sentinel.not_passed) → list[str] | _DT¶: Returns a list of all the values for the named field. Returns an empty list if the key doesn’t exist.

getlist(key: str) → list[str][source]¶
getlist(key: str, default: _DT) → list[str] | _DT: Returns a list of all the values for the named field. Returns an empty list if the key doesn’t exist.

iget(key: str, default: _Sentinel | _DT = _Sentinel.not_passed) → list[str] | _DT¶: Returns a list of all the values for the named field. Returns an empty list if the key doesn’t exist.

items() → a set-like object providing a view on D's items[source]¶

iteritems() → Iterator[tuple[str, str]][source]¶: Iterate over all header lines, including duplicate ones.

itermerged() → Iterator[tuple[str, str]][source]¶: Iterate over all headers, merging duplicate ones together.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D[source]¶