Служебные функции HTTP

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

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

Следующие функции упрощают работу со временем в контексте HTTP. Werkzeug использует объекты datetime без учета смещения во времени (offset-naive) в UTC внутри.

werkzeug.http.cookie_date(expires=None)

Форматирует время для обеспечения совместимости со стандартом куки Netscape.

Принимает число с плавающей точкой, выраженное в секундах с момента эпохи, объект datetime или кортеж времени. Все времена в UTC. Функцию parse_date() можно использовать для разбора такой даты.

Выводит строку в формате Wdy, DD-Mon-YYYY HH:MM:SS GMT.

Параметры:	expires – Если указано, используется эта дата, в противном случае текущая.

werkzeug.http.http_date(timestamp=None)

Форматирует время для соответствия формату даты RFC1123.

Принимает число с плавающей точкой, выраженное в секундах с момента эпохи, объект datetime или кортеж времени. Все времена в UTC. Функцию parse_date() можно использовать для разбора такой даты.

Выводит строку в формате Wdy, DD Mon YYYY HH:MM:SS GMT.

Параметры:	timestamp – Если указано, используется эта дата, в противном случае текущая.

werkzeug.http.parse_date(value)

Разбирает один из следующих форматов даты в объект datetime:

Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123
Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format

Если разбор не удался, возвращаемое значение равно None.

Параметры:	value – строка с поддерживаемым форматом даты.
Возвращает:	объект datetime.datetime.

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

Следующие функции могут использоваться для разбора входящих заголовков 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 – заголовок для разбора. multiple – Попытка разбора и возврата нескольких типов MIME
Возвращает:	(mimetype, options) или (mimetype, options, mimetype, options, …) если multiple=True

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

Разбирает заголовок типа set и возвращает объект 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 – заголовок типа set для разбора. on_update – необязательная функция, вызываемая каждый раз, когда значение в объекте HeaderSet изменяется.
Возвращает:	объект HeaderSet

werkzeug.http.parse_list_header(value)

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

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

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

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

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

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

Параметры:	value – строка со списком заголовков.
Возвращает:	list

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

Разбирает списки пар ключ-значение, как описано в разделе 2 RFC 2068, и преобразует их в словарь 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 – строка с заголовком типа словарь. cls – вызываемый объект для хранения результатов разбора.
Возвращает:	экземпляр cls

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

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

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

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

Параметры:	value – строка заголовка accept, подлежащая разбору. cls – класс-оболочка для возвращаемого значения (может быть Accept или подкласс thereof)
Возвращает:	экземпляр cls.

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

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

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

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

werkzeug.http.parse_authorization_header(value)

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

Параметры:	value – заголовок авторизации для разбора.
Возвращает:	объект Authorization или None.

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

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

Параметры:	value – заголовок WWW-Authenticate для разбора. on_update – необязаемая функция, вызываемая при изменении значения в объекте WWWAuthenticate.
Возвращает:	объект WWWAuthenticate.

werkzeug.http.parse_if_range_header(value)

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

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

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

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

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

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

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

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

Параметры:	value – заголовок диапазона содержимого для разбора. on_update – необязаемая функция, вызываемая при изменении значения в объекте ContentRange.

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

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

werkzeug.http.is_entity_header(header)

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

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

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

werkzeug.http.is_hop_by_hop_header(header)

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

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

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

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

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

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

Параметры:	headers – список или Headers объект. allowed – список заголовков, которые должны быть разрешены, даже если они являются заголовками сущностей.

werkzeug.http.remove_hop_by_hop_headers(headers)

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

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

Параметры:	headers – список или Headers объект.

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

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

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

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

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

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

Параметры:	value – значение для приведения в кавычки. extra_chars – список дополнительных символов, для которых не нужно приводить в кавычки. allow_token – если включено, то значения токенов возвращаются без изменений.

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

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

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

Параметры:	value – значение заголовка для снятия кавычек.

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 – итерируемый объект или словарь значений для экранирования. allow_token – если установлено в False то токены в качестве значений запрещены. Подробнее см. quote_header_value().

Куки

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

Разбор куки. Из строки или WSGI-среды.

По умолчанию ошибки кодирования игнорируются. Если нужно другое поведение, вы можете установить errors в 'replace' или 'strict'. В строгом режиме возникает HTTPUnicodeError.

Изменено в версии 0.5: Эта функция теперь возвращает TypeConversionDict, а не обычный словарь. Добален параметр cls.

Параметры:	header – заголовок для разбора куки. В качестве альтернативы это может быть WSGI-среда. charset – кодировка для значений куки. errors – поведение при ошибках кодирования. cls – необязательный класс словаря для использования. Если не указано или None, используется по умолчанию TypeConversionDict.

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. Параметры такие же, как в объекте cookie Morsel в стандартной библиотеке Python, но он также принимает данные unicode.

В Python 3 возвращаемое значение этой функции будет строкой unicode, в Python 2 — обычной строкой. В обоих случаях возвращаемое значение обычно ограничивается ASCII, так как подавляющее большинство значений должным образом экранированы, но это не гарантия. Если возвращается строка unicode, она передаётся через latin1, как требуется PEP 3333.

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

Параметры:

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

Помощники для условных ответов

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

werkzeug.http.parse_etags(value)

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

Параметры:	value – заголовок тега для разбора
Возвращает:	объект ETags.

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

Экранирование etag.

Параметры:	etag – etag для экранирования. weak – установите в True для маркировки как «слабый».

werkzeug.http.unquote_etag(etag)

Распаковка одиночного etag:

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

Параметры:	etag – идентификатор etag для распаковки.
Возвращает:	кортеж (etag, weak).

werkzeug.http.generate_etag(data)

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

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

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

Параметры:	environ – WSGI-среда запроса для проверки. etag – etag ответа для сравнения. data – или альтернативно данные ответа для автоматической генерации etag с помощью generate_etag(). last_modified – необязательная дата последней модификации. ignore_if_range – Если False, будет учтён заголовок If-Range.
Возвращает:	True если ресурс был изменён, в противном случае False.

Константы

werkzeug.http.HTTP_STATUS_CODES

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

Обработка данных форм

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

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

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

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

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

>>> from cStringIO import StringIO
>>> data = '--foo\r\nContent-Disposition: form-data; name="test"\r\n' \
... '\r\nHello World!\r\n--foo--'
>>> environ = {'wsgi.input': StringIO(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()
''
>>> form['test']
u'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 – необязательное вызываемое значение, которое возвращает новый читаемый и записываемый дескриптор файла. Это вызываемое значение работает так же, как _get_file_stream(). charset – кодировка для данных URL и данных формы в кодировке url. errors – поведение при ошибках кодирования. max_form_memory_size – максимальное количество байтов, принимаемых для данных формы в памяти. Если данные превышают указанное значение, возникает исключение RequestEntityTooLarge. max_content_length – Если указано, и переданные данные длиннее этого значения, возникает исключение RequestEntityTooLarge. cls – необязательный класс словаря для использования. Если не указано или None, используется по умолчанию MultiDict. silent – если установлено в 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)

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

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

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

Более подробную информацию см. в Обработка данных запроса.

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

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

Параметры:

environ – WSGI-окружение для разбора. stream_factory – Необязательное вызываемое значение, которое возвращает новый читаемый и записываемый дескриптор файла. Это вызываемое значение работает так же, как _get_file_stream(). charset – Кодировка символов для данных URL и данных формы в формате URL. errors – Поведение при ошибках кодирования. max_form_memory_size – Максимальное количество байтов для данных формы, хранящихся в памяти. Если данные превышают указанное значение, возникает исключение RequestEntityTooLarge. max_content_length – Если задано и переданные данные превышают это значение, возникает исключение RequestEntityTooLarge. cls – Необязательный класс словаря для использования. Если не указан или None, используется по умолчанию MultiDict. silent – Если установлено в False, ошибки разбора не будут перехвачены.

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

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

werkzeug.formparser.parse_multipart_headers(iterable)

Разбирает заголовки multipart из итерируемого объекта, который возвращает строки (включая символ завершающей новой строки). Итерируемый объект должен быть завершён новой строкой.

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

Параметры:	iterable – итерируемый объект строк, завершённых новой строкой