Служебные программы 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)

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

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 – строка с заголовком словаря. cls – вызываемая функция для хранения результатов разбора.
Возвращает:	экземпляр cls

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

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

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

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

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

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

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

Изменения

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

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

werkzeug.http.parse_authorization_header(value)

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

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

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

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

Параметры:	значение – заголовок 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)

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

Изменения

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

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

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

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

werkzeug.http.is_entity_header(header)

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

Изменения

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

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

werkzeug.http.is_hop_by_hop_header(header)

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

Изменения

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

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

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

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

Изменения

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

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

werkzeug.http.remove_hop_by_hop_headers(headers)

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

Изменения

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

Параметры:	заголовки – список или 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.

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

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

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

Изменения

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

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

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-среды.

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

Параметры:	header – Заголовок куки в виде строки или WSGI-словарь со HTTP_COOKIE ключом. charset – Кодировка символов для значений куки. errors – Поведение при ошибках декодирования кодировки символов. cls – Класс типа dict для хранения разбора куки. По умолчанию MultiDict.

Изменено в версии 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 Параметры идентичны объекту 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 – автоматически устанавливает срок действия, если max_age определен, но expires нет. max_size – Вывести предупреждение, если конечное значение заголовка превышает этот размер. По умолчанию 4093, должно быть безопасно поддерживаемое большинством браузеров. Установите в 0, чтобы отключить эту проверку. samesite – Ограничивает область действия куки таким образом, что он будет прикреплен только к запросам, если эти запросы являются однодоменными.

Изменено в версии 1.0.0: Строка 'None' принимается для 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.

Изменено в версии 1.0.0: Проверка выполняется для методов, отличных от GET и HEAD.

Константы

werkzeug.http.HTTP_STATUS_CODES

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

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

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

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

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

Вложенная многочастная форма не поддерживается (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-encoded. Он может быть расширен, но для большинства MIME-типов лучше использовать необработанный поток и экспонировать его как отдельные атрибуты в объекте запроса.

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

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

Параметры:

stream_factory – необязательная функция, которая возвращает новый потоковый объект для чтения и записи. Эта функция работает аналогично _get_file_stream(). charset – кодировка символов для данных формы URL и url-encoded. 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.1: Добавлен необязательный флаг silent.

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

Параметры:

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