Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from __future__ import annotations
3import re
4from collections.abc import Iterable, Iterator, Mapping, MutableMapping
5from typing import Any, Protocol
8__all__ = [
9 "Headers",
10 "HeadersLike",
11 "MultipleValuesError",
12]
15class MultipleValuesError(LookupError):
16 """
17 Exception raised when :class:`Headers` has multiple values for a key.
19 """
21 def __str__(self) -> str:
22 # Implement the same logic as KeyError_str in Objects/exceptions.c.
23 if len(self.args) == 1:
24 return repr(self.args[0])
25 return super().__str__()
28# Obsolete line folding for header values is not supported.
29is_valid_header_value = re.compile(r"[\x09\x20-\x7e\x80-\xff]*").fullmatch
32class Headers(MutableMapping[str, str]):
33 """
34 Efficient data structure for manipulating HTTP headers.
36 A :class:`list` of ``(name, values)`` is inefficient for lookups.
38 A :class:`dict` doesn't suffice because header names are case-insensitive
39 and multiple occurrences of headers with the same name are possible.
41 :class:`Headers` stores HTTP headers in a hybrid data structure to provide
42 efficient insertions and lookups while preserving the original data.
44 In order to account for multiple values with minimal hassle,
45 :class:`Headers` follows this logic:
47 - When getting a header with ``headers[name]``:
48 - if there's no value, :exc:`KeyError` is raised;
49 - if there's exactly one value, it's returned;
50 - if there's more than one value, :exc:`MultipleValuesError` is raised.
52 - When setting a header with ``headers[name] = value``, the value is
53 appended to the list of values for that header.
55 - When deleting a header with ``del headers[name]``, all values for that
56 header are removed (this is slow).
58 Other methods for manipulating headers are consistent with this logic.
60 As long as no header occurs multiple times, :class:`Headers` behaves like
61 :class:`dict`, except keys are lower-cased to provide case-insensitivity.
63 Two methods support manipulating multiple values explicitly:
65 - :meth:`get_all` returns a list of all values for a header;
66 - :meth:`raw_items` returns an iterator of ``(name, values)`` pairs.
68 """
70 __slots__ = ["_dict", "_list"]
72 # Like dict, Headers accepts an optional "mapping or iterable" argument.
73 def __init__(self, *args: HeadersLike, **kwargs: str) -> None:
74 self._dict: dict[str, list[str]] = {}
75 self._list: list[tuple[str, str]] = []
76 self.update(*args, **kwargs)
78 def __str__(self) -> str:
79 return "".join(f"{key}: {value}\r\n" for key, value in self._list) + "\r\n"
81 def __repr__(self) -> str:
82 return f"{self.__class__.__name__}({self._list!r})"
84 def copy(self) -> Headers:
85 copy = self.__class__()
86 copy._dict = self._dict.copy()
87 copy._list = self._list.copy()
88 return copy
90 def serialize(self) -> bytes:
91 # Since headers only contain ASCII characters, we can keep this simple.
92 return str(self).encode()
94 # Collection methods
96 def __contains__(self, key: object) -> bool:
97 return isinstance(key, str) and key.lower() in self._dict
99 def __iter__(self) -> Iterator[str]:
100 return iter(self._dict)
102 def __len__(self) -> int:
103 return len(self._dict)
105 # MutableMapping methods
107 def __getitem__(self, key: str) -> str:
108 value = self._dict[key.lower()]
109 if len(value) == 1:
110 return value[0]
111 else:
112 raise MultipleValuesError(key)
114 def __setitem__(self, key: str, value: str) -> None:
115 if not is_valid_header_value(str(value)):
116 raise InvalidHeaderValue(key, value)
117 self._dict.setdefault(key.lower(), []).append(value)
118 self._list.append((key, value))
120 def __delitem__(self, key: str) -> None:
121 key_lower = key.lower()
122 self._dict.__delitem__(key_lower)
123 # This is inefficient. Fortunately deleting HTTP headers is uncommon.
124 self._list = [(k, v) for k, v in self._list if k.lower() != key_lower]
126 def __eq__(self, other: Any) -> bool:
127 if not isinstance(other, Headers):
128 return NotImplemented
129 return self._dict == other._dict
131 def clear(self) -> None:
132 """
133 Remove all headers.
135 """
136 self._dict = {}
137 self._list = []
139 def update(self, *args: HeadersLike, **kwargs: str) -> None:
140 """
141 Update from a :class:`Headers` instance and/or keyword arguments.
143 """
144 args = tuple(
145 arg.raw_items() if isinstance(arg, Headers) else arg for arg in args
146 )
147 super().update(*args, **kwargs)
149 # Methods for handling multiple values
151 def get_all(self, key: str) -> list[str]:
152 """
153 Return the (possibly empty) list of all values for a header.
155 Args:
156 key: Header name.
158 """
159 return self._dict.get(key.lower(), [])
161 def raw_items(self) -> Iterator[tuple[str, str]]:
162 """
163 Return an iterator of all values as ``(name, value)`` pairs.
165 """
166 return iter(self._list)
168 # Internal menthods
170 def set_insecure(self, key: str, value: str) -> None:
171 """
172 Set a header without validating its value.
174 """
175 self._dict.setdefault(key.lower(), []).append(value)
176 self._list.append((key, value))
179# copy of _typeshed.SupportsKeysAndGetItem.
180class SupportsKeysAndGetItem(Protocol): # pragma: no cover
181 """
182 Dict-like types with ``keys() -> str`` and ``__getitem__(key: str) -> str`` methods.
184 """
186 def keys(self) -> Iterable[str]: ...
188 def __getitem__(self, key: str) -> str: ...
191HeadersLike = (
192 Headers | Mapping[str, str] | Iterable[tuple[str, str]] | SupportsKeysAndGetItem
193)
194"""
195Types accepted where :class:`Headers` is expected.
197In addition to :class:`Headers` itself, this includes dict-like types where both
198keys and values are :class:`str`.
200"""
203# At the bottom to break an import cycle.
204from .exceptions import InvalidHeaderValue # noqa: E402