Утилиты HTTP

Werkzeug предоставляет несколько функций для разбора и генерации заголовков HTTP, которые полезны при реализации WSGI-мидлвар или при работе на более низком уровне. Все эти функции также доступны из объектов запроса и ответа.

Функции работы со временем

Эти функции упрощают работу со временем в контексте HTTP. Werkzeug генерирует объекты datetime с учетом часового пояса в UTC. При передаче объектов datetime в Werkzeug предполагается, что любые объекты datetime без часового пояса находятся в UTC.

При сравнении значений datetime из Werkzeug, ваши собственные объекты datetime также должны быть с учетом часового пояса, или вы должны сделать значения из Werkzeug без учета часового пояса.

dt = datetime.now(timezone.utc) получает текущее время в UTC.
dt = datetime(..., tzinfo=timezone.utc) создает время в UTC.
dt = dt.replace(tzinfo=timezone.utc) делает объект без учета часового пояса с учетом часового пояса, предполагая, что он находится в UTC.
dt = dt.replace(tzinfo=None) делает объект с учетом часового пояса без учета часового пояса.

werkzeug.http.parse_date(value)

Разбирает дату в формате RFC 2822 в объект datetime.datetime с учетом часового пояса или None в случае ошибки разбора.

Это обёртка над email.utils.parsedate_to_datetime(). Она возвращает None в случае ошибки разбора вместо исключения и всегда возвращает объект datetime с учетом часового пояса. Если в строке нет информации о часовом поясе, предполагается UTC.

Параметры: value (Необязательное[str]) – Строка с поддерживаемым форматом даты.
Тип возвращаемого значения: Необязательное[datetime.datetime]

Изменено в версии 2.0: Возвращает объект datetime с учетом часового пояса. Используйте email.utils.parsedate_to_datetime.

werkzeug.http.http_date(timestamp=None)

Форматирует объект datetime или метку времени в строку даты в формате RFC 2822.

Это обёртка над email.utils.format_datetime(). Она предполагает, что объекты datetime без часового пояса находятся в UTC вместо возбуждения исключения.

Параметры: timestamp (Необязательное[Union[datetime.datetime, datetime.date, int, float, time.struct_time]]) – Объект datetime или метка времени для форматирования. По умолчанию используется текущее время.
Тип возвращаемого значения: str

Изменено в версии 2.0: Используйте email.utils.format_datetime. Принимайте объекты date.

werkzeug.http.cookie_date(expires=None)

Форматирует объект datetime или метку времени в строку даты в формате RFC 2822 для Set-Cookie expires.

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте http_date() вместо этого.

Параметры: expires (Необязательное[Union[datetime.datetime, datetime.date, int, float, time.struct_time]]) –
Тип возвращаемого значения: str

END_OF_DOCUMENT_MARKER

Парсинг заголовков

Следующие функции могут быть использованы для парсинга входящих заголовков HTTP. Поскольку Python не предоставляет структуры данных с семантикой, необходимой для RFC 2616, Werkzeug реализует некоторые пользовательские структуры данных, которые документированы отдельно.

werkzeug.http.parse_options_header(value, multiple=False)

Разбирает заголовок типа Content-Type в кортеж со значением типа содержимого и опциями:

>>> parse_options_header('text/html; charset=utf8')
('text/html', {'charset': 'utf8'})

Не следует использовать для разбора заголовков типа Cache-Control, которые используют немного другой формат. Для таких заголовков используйте функцию parse_dict_header().

Журнал изменений

Изменено в версии 0.15: Обрабатываются продолжения параметров RFC 2231.

Добавлена в версии 0.5.

Параметры

value (Необязательно[str]) – заголовок для разбора.
multiple (bool) – Флаг, указывающий на необходимость разбора и возврата нескольких типов MIME.

Возвращает

(mimetype, options) или (mimetype, options, mimetype, options, …) если multiple=True

Тип возвращаемого значения

Union[Tuple[str, Dict[str, str]], Tuple[Any, …]]

werkzeug.http.parse_set_header(value, on_update=None)

Разбирает заголовок типа «множество» и возвращает объект HeaderSet:

>>> hs = parse_set_header('token, "quoted value"')

Значение возврата — объект, который обрабатывает элементы без учета регистра и сохраняет порядок элементов:

>>> 'TOKEN' in hs
True
>>> hs.index('quoted value')
1
>>> hs
HeaderSet(['token', 'quoted value'])

Чтобы снова создать заголовок из HeaderSet , используйте функцию dump_header().

Параметры

value (Необязательно[str]) – заголовок типа «множество» для разбора.
on_update (Необязательно[Callable[[werkzeug.datastructures.HeaderSet], None]]) – необязательная функция, вызываемая каждый раз, когда значение объекта HeaderSet изменяется.

Возвращает

объект HeaderSet

Тип возвращаемого значения

werkzeug.datastructures.HeaderSet

werkzeug.http.parse_list_header(value)

Разбирает списки, как описано в RFC 2068, раздел 2.

В частности, разбирает списки, разделенные запятыми, где элементы списка могут содержать строки в кавычках. Строка в кавычках может содержать запятую. Строка без кавычек может содержать кавычки внутри. Кавычки удаляются автоматически после разбора.

В основном работает так же, как parse_set_header(), только элементы могут встречаться несколько раз, и сохраняется чувствительность к регистру.

Значение возврата — стандартный list:

>>> parse_list_header('token, "quoted value"')
['token', 'quoted value']

Чтобы снова создать заголовок из list, используйте функцию dump_header().

Параметры: value (str) – строка с заголовком списка.
Возвращает: list
Тип возвращаемого значения: List[str]

werkzeug.http.parse_dict_header(value, cls=<class 'dict'>)

Разбирает списки пар ключ-значение, как описано в RFC 2068, раздел 2, и преобразует их в словарь Python (или любой другой объект отображения, созданный из типа с интерфейсом, подобным словарю, предоставленным аргументом cls):

>>> d = parse_dict_header('foo="is a fish", bar="as well"')
>>> type(d) is dict
True
>>> sorted(d.items())
[('bar', 'as well'), ('foo', 'is a fish')]

Если для ключа нет значения, оно будет None:

>>> parse_dict_header('key_without_value')
{'key_without_value': None}

Чтобы снова создать заголовок из dict, используйте функцию dump_header().

Журнал изменений

Изменено в версии 0.9: Добавлена поддержка аргумента cls.

Параметры

value (str) – строка с заголовком словаря.
cls (Type[dict]) – функция для хранения результатов разбора.

Возвращает

экземпляр cls

Тип возвращаемого значения

Dict[str, str]

werkzeug.http.parse_accept_header(value[, class])

Парсит заголовок HTTP Accept-*. Эта реализация не реализует полную валидную алгоритмическую схему, а только ту, которая поддерживает, как минимум, извлечение значений и качества.

Возвращает новый объект Accept (по сути, список кортежей (value, quality) , отсортированных по качеству, с дополнительными методами доступа).

Второй параметр может быть подклассом Accept , созданным с помощью обработанных значений и возвращенным.

Параметры

value (Необязательно[str]) – строка заголовка accept для разбора.
cls (Необязательно[Type[werkzeug.http._TAnyAccept]]) – класс оболочки для значения возврата (может быть Accept или его подкласс)

Возвращает

экземпляр cls.

Тип возвращаемого значения

werkzeug.http._TAnyAccept

werkzeug.http.parse_cache_control_header(value, on_update=None, cls=None)

Разбор заголовка управления кэшем. RFC различает кэширование ответов и запросов, этот метод — нет. Вам необходимо убедиться, что вы используете правильные операторы управления.

Журнал изменений

Новое в версии 0.5: Добавлена cls. Если не указано, возвращается неизменяемый RequestCacheControl.

Параметры

value (Необязательно[str]) – заголовок управления кэшем для разбора.
on_update (Необязательно[Callable[[werkzeug.http._TAnyCC], None]]) – необязательная функция, вызываемая каждый раз при изменении значения в объекте CacheControl.
cls (Необязательно[Type[werkzeug.http._TAnyCC]]) – класс для возвращаемого объекта. По умолчанию используется RequestCacheControl.

Возвращает

объект cls.

Тип возвращаемого значения

werkzeug.http._TAnyCC

werkzeug.http.parse_authorization_header(value)

Разбор HTTP-заголовка авторизации basic/digest, переданного веб-браузером. Возвращаемое значение — None в случае некорректного или отсутствующего заголовка, в противном случае — объект Authorization.

Параметры: value (Необязательно[str]) – заголовок авторизации для разбора.
Возвращает: объект Authorization или None.
Тип возвращаемого значения: Optional[werkzeug.datastructures.Authorization]

werkzeug.http.parse_www_authenticate_header(value, on_update=None)

Разбор заголовка HTTP WWW-Authenticate в объект WWWAuthenticate.

Параметры

value (Необязательно[str]) – заголовок WWW-Authenticate для разбора.
on_update (Необязательно[Callable[[werkzeug.datastructures.WWWAuthenticate], None]]) – необязательная функция, вызываемая при каждом изменении значения в объекте WWWAuthenticate.

Возвращает

объект WWWAuthenticate.

Тип возвращаемого значения

werkzeug.datastructures.WWWAuthenticate

werkzeug.http.parse_if_range_header(value)

Разбирает заголовок if-range, который может быть значением etag или датой. Возвращает объект IfRange.

Изменено в версии 2.0: Если значение представляет собой дату, оно является часовым поясом.

Журнал изменений

Новое в версии 0.7.

Параметры: value (Необязательно[str]) –
Тип возвращаемого значения: werkzeug.datastructures.IfRange

werkzeug.http.parse_range_header(value, make_inclusive=True)

Разбирает заголовок range в объект Range. Если заголовок отсутствует или имеет неправильный формат, возвращается None. ranges — список (start, stop) кортежей, где диапазоны не включают конечные значения.

Журнал изменений

Новое в версии 0.7.

Параметры

value (Необязательно[str]) –
make_inclusive (bool) –

Тип возвращаемого значения

Optional[werkzeug.datastructures.Range]

werkzeug.http.parse_content_range_header(value, on_update=None)

Разбирает заголовок диапазона в объект ContentRange или None в случае невозможности разбора.

Журнал изменений

Новое в версии 0.7.

Параметры

value (Необязательно[str]) – заголовок диапазона содержимого для разбора.
on_update (Необязательно[Callable[[werkzeug.datastructures.ContentRange], None]]) – необязательная функция, вызываемая при каждом изменении значения в объекте ContentRange.

Тип возвращаемого значения

Optional[werkzeug.datastructures.ContentRange]

Утилиты для заголовков

Следующие утилиты работают с HTTP-заголовками, но не анализируют их. Они полезны, если вы работаете с условными ответами или хотите проксировать произвольные запросы, но хотите удалить не поддерживаемые WSGI заголовки «hop-by-hop». Также есть функция для создания строк HTTP-заголовков из обработанных данных.

werkzeug.http.is_entity_header(header)

Проверка, является ли заголовок заголовком сущности.

Журнал изменений

Новая в версии 0.5.

Параметры: header (str) – заголовок для проверки.
Возвращает: True если это заголовок сущности, False в противном случае.
Тип возвращаемого значения: bool

werkzeug.http.is_hop_by_hop_header(header)

Проверка, является ли заголовок HTTP/1.1 заголовком «Hop-by-Hop».

Журнал изменений

Новая в версии 0.5.

Параметры: header (str) – заголовок для проверки.
Возвращает: True если это заголовок HTTP/1.1 «Hop-by-Hop», False в противном случае.
Тип возвращаемого значения: bool

werkzeug.http.remove_entity_headers(headers, allowed=('expires', 'content-location'))

Удаление всех заголовков сущности из списка или Headers объекта. Данная операция работает на месте. Expires и Content-Location заголовки по умолчанию не удаляются. Причина в этом — раздел 10.3.5 RFC 2616, который определяет некоторые заголовки сущности, которые должны быть отправлены.

Журнал изменений

Изменено в версии 0.5: добавлена allowed параметр.

Параметры

headers (Union[werkzeug.datastructures.Headers, List[Tuple[str, str]]]) – список или Headers объект.
allowed (Iterable[str]) – список заголовков, которые всё равно должны быть разрешены, даже если они являются заголовками сущности.

Тип возвращаемого значения

None

werkzeug.http.remove_hop_by_hop_headers(headers)

Удаление всех HTTP/1.1 заголовков «Hop-by-Hop» из списка или Headers объекта. Данная операция работает на месте.

Журнал изменений

Новая в версии 0.5.

Параметры: headers (Union[werkzeug.datastructures.Headers, List[Tuple[str, str]]]) – список или Headers объект.
Тип возвращаемого значения: None

werkzeug.http.is_byte_range_valid(start, stop, length)

Проверка, является ли заданный диапазон байтов допустимым для заданной длины.

Журнал изменений

Новая в версии 0.7.

Параметры

start (Optional[int]) –
stop (Optional[int]) –
length (Optional[int]) –

Тип возвращаемого значения

bool

werkzeug.http.quote_header_value(value, extra_chars='', allow_token=True)

При необходимости привести значение заголовка к кавычкам.

Журнал изменений

Новая в версии 0.5.

Параметры

value (Union[str, int]) – значение для приведения к кавычкам.
extra_chars (str) – список дополнительных символов, для которых не требуется приведение к кавычкам.
allow_token (bool) – если это включено, то значения токенов возвращаются без изменений.

Тип возвращаемого значения

str

werkzeug.http.unquote_header_value(value, is_filename=False)

Разбирает значение заголовка. (Обратное преобразование для quote_header_value()). Это не использует реальное разбор заголовков, а то, что фактически используется браузерами для приведения к кавычкам.

Журнал изменений

Новая в версии 0.5.

Параметры

value (str) – значение заголовка для разбора.
is_filename (bool) – значение представляет собой имя файла или путь.

Тип возвращаемого значения

str

werkzeug.http.dump_header(iterable, allow_token=True)

Вывести заголовок HTTP ещё раз. Это обратное преобразование parse_list_header(), parse_set_header() и parse_dict_header(). Это также приводит к заключению в кавычки строк, содержащих знак равенства, если вы не передаёте его в виде словаря пар ключ-значение.

>>> dump_header({'foo': 'bar baz'})
'foo="bar baz"'
>>> dump_header(('foo', 'bar baz'))
'foo, "bar baz"'

Параметры

iterable (Union[Dict[str, Union[str, int]], Iterable[str]]) – итерируемый объект или словарь значений для заключения в кавычки.
allow_token (bool) – если установлено в False то токены в качестве значений запрещены. Дополнительные сведения см. в quote_header_value().

Тип возвращаемого значения

str

Куки

werkzeug.http.parse_cookie(header, charset='utf-8', errors='replace', cls=None)

Разбор куки из строки или WSGI окружения.

Один и тот же ключ может быть предоставлен несколько раз, значения хранятся в порядке следования. По умолчанию MultiDict будет иметь первое значение первым, и все значения могут быть получены с помощью MultiDict.getlist().

Параметры

header (Optional[Union[WSGIEnvironment, str, bytes]]) – Заголовок куки в виде строки или словарь WSGI окружения с ключом HTTP_COOKIE.
charset (str) – Кодировка символов для значений куки.
errors (str) – Поведение при ошибках декодирования кодировки символов.
cls (Optional[Type[ds.MultiDict]]) – Класс типа словаря для хранения проанализированных куки. По умолчанию MultiDict.

Тип возвращаемого значения

ds.MultiDict[str, str]

Изменения

Изменено в версии 1.0.0: Возвращает MultiDict вместо TypeConversionDict.

Изменено в версии 0.5: Возвращает TypeConversionDict вместо обычного словаря. Добавлено параметр cls.

werkzeug.http.dump_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, charset='utf-8', sync_expires=True, max_size=4093, samesite=None)

Создать заголовок Set-Cookie без префикса Set-Cookie.

Значение, как правило, ограничено ASCII, так как подавляющее большинство значений правильно экранировано, но это не гарантировано. Оно передаётся через latin1 по необходимости в соответствии с PEP 3333.

Возвращаемое значение не является безопасным для ASCII, если ключ содержит символы Юникода. Это технически противоречит спецификации, но происходит на практике. Настоятельно рекомендуется не использовать значения с не-ASCII символами для ключей.

Параметры

max_age (Optional[Union[datetime.timedelta, int]]) – должно быть числом секунд или None (по умолчанию), если куки должен действовать только в течение сеанса браузера. Также принимаются объекты timedelta.
expires (Optional[Union[str, datetime.datetime, int, float]]) – должен быть объектом datetime или меткой времени Unix.
path (Optional[str]) – ограничивает куки заданным путём, по умолчанию он охватывает весь домен.
domain (Optional[str]) – Используйте этот параметр, если вы хотите установить куки для междоменного использования. Например, domain=".example.com" установит куки, доступные для домена www.example.com, foo.example.com и т.д. В противном случае куки будут доступны только для домена, который его установил.
secure (bool) – куки будет доступен только через HTTPS
httponly (bool) – запретить JavaScript доступ к куки. Это расширение стандарта куки и, вероятно, не поддерживается всеми браузерами.
charset (str) – кодировка символов для строковых значений.
sync_expires (bool) – автоматически установить expires, если max_age определён, а expires нет.
max_size (int) – вывести предупреждение, если конечное значение заголовка превышает этот размер. По умолчанию 4093, должно быть безопасно поддерживаемое большинством браузеров. Установите в 0, чтобы отключить эту проверку.
samesite (Optional[str]) – Ограничивает область действия куки таким образом, что он будет прикреплён только к запросам, если эти запросы являются однодоменными.
key (str) –
value (Union[bytes, str]) –

Тип возвращаемого значения

str

Изменения

Изменено в версии 1.0.0: Строка 'None' принимается для samesite.

Справочные материалы по условным ответам

Для условных ответов могут быть полезны следующие функции:

werkzeug.http.parse_etags(value)

Разбор заголовка etag.

Параметры: значение (Необязательно[str]) – заголовок тега для разбора
Возвращает: объект ETags.
Тип возвращаемого значения: werkzeug.datastructures.ETags

werkzeug.http.quote_etag(etag, weak=False)

Цитата etag.

Параметры

etag (str) – etag для цитирования.
weak (bool) – установить в True для обозначения «слабого» тега.

Тип возвращаемого значения

str

werkzeug.http.unquote_etag(etag)

Разбирает один etag:

>>> unquote_etag('W/"bar"')
('bar', True)
>>> unquote_etag('"bar"')
('bar', False)

Параметры: etag (Необязательно[str]) – идентификатор etag для разбора.
Возвращает: кортеж (etag, weak).
Тип возвращаемого значения: Union[Tuple[str, bool], Tuple[None, None]]

werkzeug.http.generate_etag(data)

Генерирует etag для данных.

Изменено в версии 2.0: Используется SHA-1. MD5 может быть недоступен в некоторых средах.

Параметры: данные (bytes) –
Тип возвращаемого значения: str

werkzeug.http.is_resource_modified(environ, etag=None, data=None, last_modified=None, ignore_if_range=True)

Удобный метод для условных запросов.

Параметры

environ (WSGIEnvironment) – среда WSGI запроса для проверки.
etag (Необязательно[str]) – etag ответа для сравнения.
данные (Необязательно[bytes]) – или, альтернативно, данные ответа для автоматического создания etag с помощью generate_etag().
last_modified (Необязательно[Union[datetime.datetime, str]]) – необязательная дата последнего изменения.
ignore_if_range (bool) – Если False, заголовок If-Range будет учтён.

Возвращает

True если ресурс был изменён, в противном случае False.

Тип возвращаемого значения

bool

Изменено в версии 2.0: Для генерации значения etag для данных используется SHA-1. MD5 может быть недоступен в некоторых средах.

Журнал изменений

Изменено в версии 1.0.0: Проверка выполняется для методов, отличных от GET и HEAD.

Константы

werkzeug.http.HTTP_STATUS_CODES: Словарь пар «код статуса» -> «сообщение по умолчанию». Используется обёртками и другими местами в Werkzeug, где целочисленный код статуса расширяется до строки.

Парсинг данных формы

Werkzeug предоставляет функции парсинга форм отдельно от объекта запроса, чтобы вы могли получить доступ к данным формы из обычной WSGI-среды.

В настоящее время парсер данных формы поддерживает следующие форматы:

application/x-www-form-urlencoded
multipart/form-data

Вложенные multipart пока не поддерживаются (Werkzeug 0.9), но не используются ни одним из современных веб-браузеров.

Пример использования:

>>> from io import BytesIO
>>> from werkzeug.formparser import parse_form_data
>>> data = (
...     b'--foo\r\nContent-Disposition: form-data; name="test"\r\n'
...     b"\r\nHello World!\r\n--foo--"
... )
>>> environ = {
...     "wsgi.input": BytesIO(data),
...     "CONTENT_LENGTH": str(len(data)),
...     "CONTENT_TYPE": "multipart/form-data; boundary=foo",
...     "REQUEST_METHOD": "POST",
... }
>>> stream, form, files = parse_form_data(environ)
>>> stream.read()
b''
>>> form['test']
'Hello World!'
>>> not files
True

Обычно WSGI-среда предоставляется WSGI-шлюзом с поступающими данными как частью её. Если вы хотите сгенерировать такие фиктивные WSGI-среды для тестирования юнит-тестами, вам может потребоваться использовать функцию create_environ() или EnvironBuilder.

class werkzeug.formparser.FormDataParser(stream_factory=None, charset='utf-8', errors='replace', max_form_memory_size=None, max_content_length=None, cls=None, silent=True)

Этот класс реализует парсинг данных формы для Werkzeug. Сам по себе он может парсить multipart и url-кодированные данные формы. Его можно наследовать и расширять, но для большинства MIME-типов лучше использовать необработанный поток и экспонировать его как отдельные атрибуты в объекте запроса.

Журнал изменений

В версии 0.8.

Параметры

stream_factory (Необязательно[TStreamFactory]) – Необязательное вызываемое значение, которое возвращает новый открытый для чтения и записи дескриптор файла. Это вызываемое значение работает так же, как Response._get_file_stream().
charset (str) – Набор символов для данных формы URL и url-кодированных данных формы.
errors (str) – Поведение обработки ошибок кодирования.
max_form_memory_size (Необязательно[int]) – максимальное количество байтов, принимаемых для данных формы, хранящихся в памяти. Если данные превышают указанное значение, возникает исключение RequestEntityTooLarge.
max_content_length (Необязательно[int]) – Если это значение указано, и передаваемые данные длиннее этого значения, возникает исключение RequestEntityTooLarge.
cls (Необязательно[Type[werkzeug.datastructures.MultiDict]]) – необязательный класс словаря для использования. Если это не указано или None используется по умолчанию MultiDict.
silent (bool) – Если установлено в False, ошибки парсинга не будут перехватываться.

Тип возвращаемого значения

None

werkzeug.formparser.parse_form_data(environ, stream_factory=None, charset='utf-8', errors='replace', max_form_memory_size=None, max_content_length=None, cls=None, silent=True)

Разбирает данные формы в среде environ и возвращает их как кортеж в виде (stream, form, files). Вы должны вызывать этот метод только если метод транспорта POST, PUT, или PATCH.

Если MIME-тип передаваемых данных multipart/form-data, многозначный словарь файлов будет заполнен объектами FileStorage. Если MIME-тип неизвестен, входной поток оборачивается и возвращается в качестве первого аргумента, иначе поток пуст.

Это сокращение для общего использования FormDataParser.

Для получения более подробной информации см. Обработка данных запроса.

Журнал изменений

В версии 0.5.1: Добавлен необязательный флаг silent.

В версии 0.5: Добавлены параметры max_form_memory_size, max_content_length и cls.

Параметры

environ (WSGIEnvironment) – WSGI-среда, используемая для парсинга.
stream_factory (Необязательно[TStreamFactory]) – Необязательное вызываемое значение, которое возвращает новый открытый для чтения и записи дескриптор файла. Это вызываемое значение работает так же, как Response._get_file_stream().
charset (str) – Набор символов для данных формы URL и url-кодированных данных формы.
errors (str) – Поведение обработки ошибок кодирования.
max_form_memory_size (Необязательно[int]) – максимальное количество байтов, принимаемых для данных формы, хранящихся в памяти. Если данные превышают указанное значение, возникает исключение RequestEntityTooLarge.
max_content_length (Необязательно[int]) – Если это значение указано, и передаваемые данные длиннее этого значения, возникает исключение RequestEntityTooLarge.
cls (Необязательно[Type[werkzeug.datastructures.MultiDict]]) – необязательный класс словаря для использования. Если это не указано или None используется по умолчанию MultiDict.
silent (bool) – Если установлено в False, ошибки парсинга не будут перехватываться.

Возвращает

Кортеж в форме (stream, form, files).

Тип возвращаемого значения

t_parse_result