Служебные утилиты HTTP

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

Эти функции упрощают работу со временем в контексте 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 в объект timezone-aware datetime.datetime, или None в случае неудачи.

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

Параметры

value (Optional[str]) – Строка с поддерживаемым форматом даты.

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

Optional[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 (Optional[Union[datetime.datetime, datetime.date, int, float, time.struct_time]]) – Объект datetime или временная метка для форматирования. По умолчанию используется текущее время.

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

str

Изменения

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

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

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

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

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

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

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

Параметры

• value (Optional[str]) – Значение заголовка для парсинга.
• multiple (te.Literal[None]) –

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

Кортеж[str, Словарь[str, str]]

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

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

Изменено в версии 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 (Optional[str]) – заголовок-множество для парсинга.
• on_update (Optional[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

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

Список[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 (Тип[dict]) – вызываемый для хранения результатов парсинга.

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

экземпляр cls

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

Словарь[str, str]

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

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

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

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

Параметры

• value (Optional[str]) – строка заголовка accept для парсинга.
• cls (Optional[Тип[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 (Optional[str]) – заголовок управления кэшем для разбора.
• on_update (Optional[Callable[[werkzeug.http._TAnyCC], None]]) – необязаемый вызываемый объект, который вызывается каждый раз, когда изменяется значение в объекте CacheControl.
• cls (Optional[Type[werkzeug.http._TAnyCC]]) – класс для возвращаемого объекта. По умолчанию используется RequestCacheControl.

Возвращает

объект cls.

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

werkzeug.http._TAnyCC

werkzeug.http.parse_authorization_header(value)

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

Параметры

value (Optional[str]) – заголовок авторизации для разбора.

Возвращает

объект Authorization или None.

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

Optional[werkzeug.datastructures.Authorization]

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

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

Параметры

• value (Optional[str]) – заголовок WWW-Authenticate для разбора.
• on_update (Optional[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 (Optional[str]) –

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

werkzeug.datastructures.IfRange

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

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

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

В версии 0.7.

Параметры

• value (Optional[str]) –
• make_inclusive (bool) –

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

Optional[werkzeug.datastructures.Range]

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

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

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

В версии 0.7.

Параметры

• value (Optional[str]) – заголовок диапазона содержимого для разбора.
• on_update (Optional[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 заголовки по умолчанию не удаляются. Причина в том, что RFC 2616 раздел 10.3.5, который определяет некоторые заголовки сущностей, которые должны быть отправлены.

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

Изменено в версии 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.

Параметры

value (Optional[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 (Optional[str]) – идентификатор тега etag для разбора.

Возвращает

кортеж (etag, weak).

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

Union[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 (Optional[str]) – etag для сравнения ответа.
• data (Optional[bytes]) – или альтернативно данные ответа для автоматической генерации etag с помощью generate_etag().
• last_modified (Optional[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-encoded. Его можно наследовать и расширять, но для большинства MIME-типов лучше использовать неповреждённый поток и экспонировать его как отдельные атрибуты в объекте запроса.

Изменения

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

Параметры

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

Возвращает

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

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

t_parse_result