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 | None) – Строка с поддерживаемым форматом даты.
Тип возвращаемого значения:: datetime | None

Изменения

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

werkzeug.http.http_date(timestamp=None)

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

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

Параметры:: timestamp (datetime | date | int | float | struct_time | None) – Объект datetime или метка времени для форматирования. По умолчанию текущее время.
Тип возвращаемого значения:: str

Изменения

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

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

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

werkzeug.http.parse_options_header(value)

Разбирает заголовок, который состоит из значения с key=value параметрами, разделенными точкой с запятой ;. Например, заголовок Content-Type.

parse_options_header("text/html; charset=UTF-8")
('text/html', {'charset': 'UTF-8'})

parse_options_header("")
("", {})

Это обратная операция к dump_options_header().

Разбирает допустимые части параметров, как описано в RFC 9110. Недопустимые части пропускаются.

Обрабатывает продолжения и наборы символов, как описано в RFC 2231, хотя и не так строго, как в RFC. Принимаются только наборы символов ASCII, UTF-8 и ISO-8859-1, в противном случае значение остается в кавычках.

Клиенты могут не соблюдать согласованность в обработке символа кавычки внутри кавыченного значения. Стандарт HTML заменяет его на %22 в данных multipart формы. RFC 9110 использует обратный слэш для экранирования в заголовках HTTP. Оба кодируются в символ ".

Клиенты могут не соблюдать согласованность в обработке не-ASCII символов. HTML-документы должны объявлять <meta charset=UTF-8>, в противном случае браузеры могут заменить их HTML-ссылками символов, которые можно декодировать с помощью html.unescape().

Параметры:: value (str | None) – Значение заголовка для парсинга.
Возвращаемое значение:: (value, options), где options — словарь
Тип возвращаемого значения:: tuple[str, dict[str, str]]

Изменения

Изменено в версии 2.3: Недопустимые части, такие как ключи без значения, ключи в кавычках и неправильно кавыченные значения, отбрасываются вместо обработки как None.

Изменено в версии 2.3: Принимаются только наборы символов ASCII, UTF-8 и ISO-8859-1 для значений набора символов.

Изменено в версии 2.3: Обрабатываются экранированные кавычки в кавыченных значениях, например %22 и \".

Изменено в версии 2.2: Имена опций всегда преобразуются в нижний регистр.

Изменено в версии 2.2: Параметр multiple был удален.

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

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

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 | None) – заголовок типа множества для парсинга.
on_update (Callable[[HeaderSet], None] | None) – необязательная функция, которая вызывается каждый раз при изменении значения на объекте HeaderSet.

Возвращаемое значение:

объект HeaderSet

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

HeaderSet

werkzeug.http.parse_list_header(value)

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

Это расширение urllib.request.parse_http_list(), чтобы удалить окружающие кавычки из значений.

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

Это обратная операция к dump_header().

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

werkzeug.http.parse_dict_header(value)

Разбирает заголовок списка с помощью parse_list_header(), затем разбирает каждый элемент как key=value пару.

parse_dict_header('a=b, c="d, e", f')
{"a": "b", "c": "d, e", "f": None}

Это обратная операция к dump_header().

Если ключ не имеет значения, он None.

Обрабатывает наборы символов для значений, как описано в RFC 2231. Принимаются только наборы символов ASCII, UTF-8 и ISO-8859-1, в противном случае значение остается в кавычках.

Параметры:: value (str) – Значение заголовка для парсинга.
Тип возвращаемого значения:: dict[str, str | None]

Изменено в версии 3.0: Передача байтов не поддерживается.

Изменено в версии 3.0: Аргумент cls удален.

Изменения

Изменено в версии 2.3: Добавлена поддержка элементов, закодированных в key*=charset''value.

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

werkzeug.http.parse_accept_header(value: str | None) → Accept

werkzeug.http.parse_accept_header(value:str|None, cls:type[_TAnyAccept]) → _TAnyAccept

Разбор заголовка Accept в соответствии с RFC 9110.

Возвращает экземпляр Accept, который может сортировать и проверять элементы на основе параметра качества. При разборе Accept-Charset, Accept-Encoding, или Accept-Language, передайте соответствующий подкласс Accept.

Параметры:

value – Значение заголовка для разбора.
cls – Класс Accept для обертывания результата.

Возвращает:

Экземпляр cls.

Changelog

Изменено в версии 2.3: Разбор в соответствии с RFC 9110. Элементы с недопустимыми значениями q пропускаются.

werkzeug.http.parse_cache_control_header(value: str | None, on_update: Callable[[_TAnyCC], None] | None, cls: None = None) → RequestCacheControl

werkzeug.http.parse_cache_control_header(value:str|None, on_update:Callable[[_TAnyCC],None]|None, cls:type[_TAnyCC]) → _TAnyCC

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

Changelog

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

Параметры:

value – заголовок управления кэшем для разбора.
on_update – необязаемый вызываемый объект, который вызывается каждый раз, когда изменяется значение в объекте CacheControl.
cls – класс возвращаемого объекта. По умолчанию используется RequestCacheControl.

Возвращает:

объект cls.

werkzeug.http.parse_if_range_header(value)

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

Changelog

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

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

Параметры:: value (str | None) –
Тип возвращаемого значения:: IfRange

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

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

Changelog

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

Параметры:

value (str | None) –
make_inclusive (bool) –

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

Range | None

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

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

Changelog

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

Параметры:

value (str | None) – заголовок content range для разбора.
on_update (Callable[[ContentRange], None] | None) – необязаемый вызываемый объект, который вызывается каждый раз, когда изменяется значение в объекте ContentRange.

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

ContentRange | None

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

Следующие утилиты хорошо работают с 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)

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

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

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

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

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

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

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

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

Параметры:

headers (Headers | list[tuple[str, str]]) – список или Headers объект.
allowed (Iterable[str]) – список заголовков, которые все еще должны быть разрешены, даже если они являются заголовками сущностей.

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

None

werkzeug.http.remove_hop_by_hop_headers(headers)

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

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

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

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

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

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

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

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

Параметры:

start (int | None) –
stop (int | None) –
length (int | None) –

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

bool

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

Добавление двойных кавычек вокруг значения заголовка. Если заголовок содержит только символы ASCII-токенов, он будет возвращён без изменений. Если заголовок содержит " или \ символы, они будут экранированы с помощью дополнительного \ символа.

Это обратное преобразование для unquote_header_value().

Параметры:

value (Any) – Значение для котирования. Будет преобразовано в строку.
allow_token (bool) – Отключить для котирования значения, даже если оно содержит только символы токенов.

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

str

Изменено в версии 3.0: Передача байтов не поддерживается.

Изменено в версии 3.0: Параметр extra_chars удален.

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

Изменено в версии 2.3: Значение котируется, если оно пустая строка.

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

werkzeug.http.unquote_header_value(value)

Удаление двойных кавычек и декодирование экранированных с помощью косой черты " и \ символов в значении заголовка.

Это обратное преобразование для quote_header_value().

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

Изменено в версии 3.0: Параметр is_filename удален.

werkzeug.http.dump_header(iterable)

Создайте значение заголовка из списка элементов или key=value пар, разделенных запятыми ,.

Это обратная операция к parse_list_header(), parse_dict_header() и parse_set_header().

Если значение содержит не-токенизированные символы, оно будет заключено в кавычки.

Если значение None, ключ выводится самостоятельно.

В некоторых ключах для некоторых заголовков значение UTF-8 может быть закодировано с помощью специального key*=UTF-8''value формата, где value закодировано по процентам. Эта функция не будет автоматически генерировать этот формат, но если данный ключ заканчивается звездочкой *, значение предполагается имеющим этот формат и не будет дополнительно заключено в кавычки.

dump_header(["foo", "bar baz"])
'foo, "bar baz"'

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

Параметры:: iterable (dict[str, Any] | Iterable[Any]) – Элементы для создания заголовка.
Тип возвращаемого значения:: str

Изменено в версии 3.0: Параметр allow_token удален.

Изменения

Изменено в версии 2.2.3: Если ключ заканчивается *, его значение не будет заключено в кавычки.

Cookies

werkzeug.http.parse_cookie(header, cls=None)

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

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

Параметры:

header (WSGIEnvironment | str | None) – Заголовок куки как строка или словарь WSGI окружения с ключом HTTP_COOKIE.
cls (type[ds.MultiDict] | None) – Класс типа словарь для хранения проанализированных куки. По умолчанию MultiDict.

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

ds.MultiDict[str, str]

Изменено в версии 3.0: Передача байтов, и параметры charset и errors были удалены.

Изменения

Изменено в версии 1.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, sync_expires=True, max_size=4093, samesite=None)

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

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

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

Параметры:

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

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

str

Изменено в версии 3.0: Передача байтов, и параметр charset были удалены.

Изменения

Изменено в версии 2.3.3: Параметр path по умолчанию /.

Изменено в версии 2.3.1: Значение допускает больше символов без кавычек.

Изменено в версии 2.3: Допускаются localhost и другие имена без точки для домена. Внешняя точка игнорируется.

Изменено в версии 2.3: Параметр path по умолчанию None.

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

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

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

werkzeug.http.parse_etags(value)

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

Параметры:: value (str | None) – заголовок тега для разбора
Возвращаемое значение:: объект ETags.
Тип возвращаемого значения:: 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 | None) – идентификатор etag для разархивирования.
Возвращаемое значение:: кортеж (etag, weak).
Тип возвращаемого значения:: tuple[str, bool] | tuple[None, None]

werkzeug.http.generate_etag(data)

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

Изменения

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

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

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

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

Параметры:

environ (WSGIEnvironment) – окружение WSGI запроса для проверки.
etag (str | None) – etag ответа для сравнения.
data (bytes | None) – или, альтернативно, данные ответа для автоматической генерации etag с помощью generate_etag().
last_modified (datetime | str | None) – необъектная дата последнего изменения.
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, max_form_memory_size=None, max_content_length=None, cls=None, silent=True, *, max_form_parts=None)

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

Параметры:

stream_factory (TStreamFactory | None) – Необязательный вызываемый объект, который возвращает новый читаемый и записываемый дескриптор файла. Этот вызываемый объект работает так же, как Response._get_file_stream().
max_form_memory_size (int | None) – максимальное количество байтов, принимаемых для данных формы, хранящихся в памяти. Если данные превышают указанное значение, возникает исключение RequestEntityTooLarge.
max_content_length (int | None) – Если это значение указано и передаваемые данные длиннее этого значения, возникает исключение RequestEntityTooLarge.
cls (type[MultiDict] | None) – необязательный класс словаря для использования. Если это не указано или None используется по умолчанию MultiDict.
silent (bool) – Если установлено в значение False, ошибки парсинга не будут перехватываться.
max_form_parts (int | None) – Максимальное количество частей multipart, которые должны быть обработаны. Если это значение превышено, возникает исключение RequestEntityTooLarge.

Изменено в версии 3.0: Параметры charset и errors были удалены.

Изменено в версии 3.0: Атрибут parse_functions и методы get_parse_func были удалены.

Изменения

Изменено в версии 2.2.3: Добавлен параметр max_form_parts.

Введено в версии 0.8.

werkzeug.formparser.parse_form_data(environ, stream_factory=None, max_form_memory_size=None, max_content_length=None, cls=None, silent=True, *, max_form_parts=None)

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

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

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

Параметры:

environ (WSGIEnvironment) – WSGI-среда, используемая для парсинга.
stream_factory (TStreamFactory | None) – Необязательный вызываемый объект, который возвращает новый читаемый и записываемый дескриптор файла. Этот вызываемый объект работает так же, как Response._get_file_stream().
max_form_memory_size (int | None) – максимальное количество байтов, принимаемых для данных формы, хранящихся в памяти. Если данные превышают указанное значение, возникает исключение RequestEntityTooLarge.
max_content_length (int | None) – Если это значение указано и передаваемые данные длиннее этого значения, возникает исключение RequestEntityTooLarge.
cls (type[MultiDict] | None) – необязательный класс словаря для использования. Если это не указано или None используется по умолчанию MultiDict.
silent (bool) – Если установлено в значение False, ошибки парсинга не будут перехватываться.
max_form_parts (int | None) – Максимальное количество частей multipart, которые должны быть обработаны. Если это значение превышено, возникает исключение RequestEntityTooLarge.

Возвращает:

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

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

t_parse_result

Изменено в версии 3.0: Параметры charset и errors были удалены.

Изменения

Изменено в версии 2.3: Добавлен параметр max_form_parts.

Введено в версии 0.5.1: Добавлен параметр silent.

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