HTTP-утилиты

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

Функции даты

Следующие функции упрощают работу со временем в контексте HTTP. Werkzeug использует объекты datetime, не учитывающие смещения, в качестве внутренних объектов, хранящих время в UTC. Если в вашем приложении вы работаете со временными зонами, убедитесь, что вы заменяете атрибут tzinfo информацией о временной зоне UTC перед обработкой значений.

werkzeug.http.cookie_date(expires=None)

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

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

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

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

werkzeug.http.http_date(timestamp=None)

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

Принимает число с плавающей точкой, выраженное в секундах с момента эпохи, объект datetime или кортеж timetuple. Все времена в 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 (или любой другой объект отображения, созданный из типа с интерфейсом словаря, предоставленного аргументом %%%CODE_BLOCK_32%%):

>>> 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')]

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

>>> 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 в объект Range. Если заголовок отсутствует или некорректен, возвращается None. ranges — список кортежей (start, stop) , где диапазоны не включают конечные значения.

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

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

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

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

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

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

Следующие утилиты хорошо работают с HTTP-заголовками, но не обрабатывают их. Они полезны, если вы работаете с условными ответами или хотите проксировать произвольные запросы, но хотите удалить заголовки hop-by-hop, не поддерживаемые WSGI. Также есть функция для создания строк 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)

Удалить все заголовки HTTP/1.1 «Hop-by-Hop» из списка или объекта 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)

Разбирает данные формы из среды environ и возвращает их в виде кортежа в формате (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 – итерируемый объект строк, завершаемых новой строкой