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

Изменения

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

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

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

werkzeug.http.parse_options_header(value)

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

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

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

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

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

Изменения

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

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

объект HeaderSet

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

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]

END_OF_DOCUMENT_MARKER

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

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

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

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

Parameters:

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

Returns:

экземпляр cls.

Return type:

_TAnyAccept

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

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

Changelog

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

Parameters:

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

Returns:

объект cls.

Return type:

_TAnyCC

werkzeug.http.parse_authorization_header(value)

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

Parameters:: value (Optional[str]) – обрабатываемый заголовок аутентификации.
Returns:: объект Authorization или None.
Return type:: Optional[Authorization]

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

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

Parameters:

value (Optional[str]) – обрабатываемый заголовок WWW-Authenticate.
on_update (Optional[Callable[[WWWAuthenticate], None]]) – необязательное вызываемое значение, которое вызывается каждый раз, когда изменяется значение в объекте WWWAuthenticate.

Returns:

объект WWWAuthenticate.

Return type:

WWWAuthenticate

werkzeug.http.parse_if_range_header(value)

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

Changelog

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

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

Parameters:: value (Optional[str]) –
Return type:: IfRange

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

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

Changelog

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

Parameters:

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

Return type:

Optional[Range]

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

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

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

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

Параметры:

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

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

Optional[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)

Проверка, является ли заголовок заголовком «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 (Union[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 (Union[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

END_OF_DOCUMENT_MARKER

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[timedelta, int]]) – количество секунд, или None (по умолчанию), если куки должно действовать только до окончания сеанса браузера. Также принимаются объекты timedelta.
expires (Optional[Union[str, 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.
Тип возвращаемого значения:: 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, 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[MultiDict]]) – необязательный класс словаря. Если это не указано или None, используется по умолчанию MultiDict.
silent (bool) – Если установлено в False, ошибки парсинга не будут перехватываться.

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[MultiDict]]) – необязательный класс словаря. Если это не указано или None, используется по умолчанию MultiDict.
silent (bool) – Если установлено в False, ошибки парсинга не будут перехватываться.

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

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

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

t_parse_result