Объекты запроса/ответа

Объекты запроса и ответа оборачивают среду WSGI или возвращаемое значение приложения WSGI, превращая его в другое приложение WSGI (обрамляя всё приложение целиком).

Как они работают

Ваше приложение WSGI всегда получает два аргумента. WSGI «среда» и WSGI start_response функция, используемая для запуска фазы ответа. Класс Request оборачивает environ для более удобного доступа к переменным запроса (данные формы, заголовки запроса и т. д.).

С другой стороны, Response — стандартное приложение WSGI, которое вы можете создать. Простой «привет мир» на Werkzeug выглядит так:

from werkzeug.wrappers import Response
application = Response('Hello World!')

Чтобы сделать его более полезным, вы можете заменить его функцией и выполнить некоторую обработку:

from werkzeug.wrappers import Request, Response

def application(environ, start_response):
    request = Request(environ)
    response = Response(f"Hello {request.args.get('name', 'World!')}!")
    return response(environ, start_response)

Поскольку это очень распространённая задача, объект Request предоставляет для этого вспомогательную функцию. Приведённый выше код можно переписать так:

from werkzeug.wrappers import Request, Response

@Request.application
def application(request):
    return Response(f"Hello {request.args.get('name', 'World!')}!")

application по-прежнему является допустимым приложением WSGI, которое принимает среду и start_response вызываемую функцию.

Изменяемость и повторное использование обёртки

Реализация объектов запроса и ответа Werkzeug пытается оградить вас от распространённых ошибок, запрещая определённые действия по мере возможности. Это служит двум целям: высокой производительности и предотвращения ошибок.

Для объекта запроса применяются следующие правила:

Объект запроса неизменяемый. Изменения по умолчанию не поддерживаются, но вы можете заменить неизменяемые атрибуты на изменяемые, если вам нужно его изменить.
Объект запроса может быть общим в рамках одного потока, но сам по себе не потокобезопасен. Если вам нужно получить к нему доступ из нескольких потоков, используйте блокировки вокруг вызовов.
Невозможно выполнить сериализацию объекта запроса с помощью pickle.

Для объекта ответа применяются следующие правила:

Объект ответа изменяемый.
Объект ответа можно сериализовать с помощью pickle или скопировать после вызова freeze().
Начиная с Werkzeug 0.6, безопасно использовать один и тот же объект ответа для нескольких ответов WSGI.
Можно создавать копии, используя copy.deepcopy.

Классы-обертки

class werkzeug.wrappers.Request(environ, populate_request=True, shallow=False)

Представляет входящий WSGI HTTP-запрос с заголовками и телом, взятыми из WSGI-окружения. Имеет свойства и методы для использования функциональности, определённой различными спецификациями HTTP. Данные в объекте запроса являются только для чтения.

Предполагается, что текстовые данные используют кодировку UTF-8, что должно быть верно для подавляющего большинства современных клиентов. Использование кодировки, установленной клиентом, небезопасно в Python из-за дополнительных кодировок, предоставляемых, например, zip. Чтобы изменить предполагаемую кодировку, создайте подкласс и замените charset.

Параметры:

environ (WSGIEnvironment) – WSGI-окружение генерируется WSGI-сервером и содержит информацию о конфигурации сервера и запросе клиента.
populate_request (bool) – Добавить этот объект запроса в WSGI-окружение в качестве environ['werkzeug.request']. Может быть полезно при отладке.
shallow (bool) – При чтении из stream (и любых методов, которые считывают из него) вызывает исключение RuntimeError. Полезно для предотвращения потребления данных формы в middleware, что сделает их недоступными для конечного приложения.

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

Изменено в версии 2.1: Удалить атрибут disable_data_descriptor.

Изменено в версии 2.0: Объединить BaseRequest и mixins в один класс Request. Использование старых классов устарело и будет удалено в Werkzeug 2.1.

Изменено в версии 0.5: Режим только для чтения принудительно используется с неизменяемыми классами для всех данных.

_get_file_stream(total_content_length, content_type, filename=None, content_length=None)

Вызывается для получения потока для загрузки файла.

Это должно предоставить файлоподобный класс с методами read(), readline() и seek(), который одновременно является записываемым и читаемым.

По умолчанию, если общая длина содержимого больше 500 КБ, возвращается временный файл. Поскольку многие браузеры не предоставляют длину содержимого для файлов, важна только общая длина содержимого.

Параметры:

total_content_length (Optional[int]) – Общая длина содержимого всех данных в запросе. Это значение гарантированно присутствует.
content_type (Optional[str]) – Тип MIME загружаемого файла.
filename (Optional[str]) – Имя загружаемого файла. Может быть None.
content_length (Optional[int]) – Длина этого файла. Это значение обычно не предоставляется, потому что веб-браузеры не предоставляют это значение.

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

IO[bytes]

property accept_charsets: CharsetAccept: Список кодировок символов, поддерживаемых этим клиентом, как объект CharsetAccept.

property accept_encodings: Accept: Список кодировок, принимаемых этим клиентом. Кодировки в терминологии HTTP — это кодировки сжатия, такие как gzip. Для кодировок символов см. accept_charset.

property accept_languages: LanguageAccept: Список языков, принимаемых этим клиентом, как объект LanguageAccept.

property accept_mimetypes: MIMEAccept: Список MIME-типов, поддерживаемых этим клиентом, как объект MIMEAccept.

access_control_request_headers: Отправляется с предварительным запросом для указания заголовков, которые будут отправлены с запросом кросс-доменного ресурса. Установите access_control_allow_headers в ответе, чтобы указать разрешённые заголовки.

access_control_request_method: Отправляется с предварительным запросом для указания метода, который будет использоваться для запроса кросс-доменного ресурса. Установите access_control_allow_methods в ответе, чтобы указать разрешённые методы.

property access_route: List[str]: Если существует заголовок forwarded, это список всех IP-адресов от IP-адреса клиента до последнего прокси-сервера.

classmethod application(f)

Декорирует функцию как обработчик, который принимает запрос в качестве последнего аргумента. Это работает как декоратор responder(), но функция получает объект запроса в качестве последнего аргумента, а объект запроса закрывается автоматически:

@Request.application
def my_wsgi_app(request):
    return Response('Hello World!')

С Werkzeug 0.14 HTTP-исключения автоматически перехватываются и преобразуются в ответы вместо аварийного завершения.

Параметры:: f (Callable[[Request], WSGIApplication]) – WSGI-вызываемый объект для декорирования
Возвращает:: новый WSGI-вызываемый объект
Тип возвращаемого значения:: WSGIApplication

property args: MultiDict[str, str]

Обработанные параметры URL (часть URL после знака вопроса).

По умолчанию из этой функции возвращается ImmutableMultiDict. Это можно изменить, установив parameter_storage_class на другой тип. Это может потребоваться, если порядок данных формы важен.

property authorization: Optional[Authorization]: Объект Authorization в обработанном виде.

property base_url: str: Как url, но без строки запроса.

property cache_control: RequestCacheControl: Объект RequestCacheControl для входящих заголовков управления кэшем.

charset = 'utf-8': Кодировка символов, используемая для декодирования большей части данных в запросе.

close()

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

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

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

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

END_OF_DOCUMENT_MARKER

content_encoding: Поле заголовка сущности Content-Encoding используется в качестве модификатора медиа-типа. При его наличии значение указывает, какие дополнительные кодировки содержимого были применены к телу сущности, и, следовательно, какие механизмы декодирования необходимо применить для получения медиа-типа, указанного в поле заголовка Content-Type.

Changelog

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

property content_length: Optional[int]: Поле заголовка сущности Content-Length указывает размер тела сущности в байтах или, в случае метода HEAD, размер тела сущности, который был бы отправлен, если бы запрос был GET.

content_md5: Поле заголовка сущности Content-MD5, как определено в RFC 1864, представляет собой MD5-хеш тела сущности для обеспечения проверки целостности сообщения от начала до конца (MIC) тела сущности. (Примечание: MIC подходит для обнаружения случайных изменений тела сущности во время передачи, но не является гарантией против злонамеренных атак.)

Changelog

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

content_type: Поле заголовка сущности Content-Type указывает медиа-тип тела сущности, отправляемого получателю, или, в случае метода HEAD, медиа-тип, который был бы отправлен, если бы запрос был GET.

property cookies: ImmutableMultiDict[str, str]: Словарь dict с содержимым всех куки, переданных вместе с запросом.

property data: bytes: Содержит данные входящего запроса в виде строки, если они были отправлены с типом mime, который не обрабатывается Werkzeug.

date: Поле общего заголовка Date представляет собой дату и время, в которые было создано сообщение, имеющее те же семантику, что и orig-date в RFC 822.

Changelog

Изменено в версии 2.0: Объект datetime имеет информацию о часовом поясе.

dict_storage_class: Псевдоним ImmutableMultiDict

encoding_errors = 'replace': Процедура обработки ошибок, по умолчанию «replace»

environ: WSGIEnvironment: WSGI-среда, содержащая HTTP-заголовки и информацию от WSGI-сервера.

property files: ImmutableMultiDict[str, FileStorage]

MultiDict объект, содержащий все загруженные файлы. Каждый ключ в files — имя из <input type="file" name="">. Каждое значение в files — объект Werkzeug FileStorage.

По сути, ведет себя как обычный объект файла из Python, с той разницей, что у него также есть функция save(), которая может сохранить файл в файловой системе.

Обратите внимание, что files будет содержать данные только если метод запроса был POST, PUT или PATCH и <form> который был отправлен в запрос имел enctype="multipart/form-data". В противном случае он будет пустым.

См. документацию MultiDict / FileStorage для получения более подробной информации о используемой структуре данных.

property form: ImmutableMultiDict[str, str]

Параметры формы. По умолчанию функция возвращает ImmutableMultiDict. Это можно изменить, задав parameter_storage_class на другой тип. Это может потребоваться, если порядок данных формы важен.

Пожалуйста, имейте в виду, что загрузки файлов не попадут сюда, а вместо этого в атрибут files.

Changelog

Изменено в версии 0.9: До Werkzeug 0.9 это содержало только данные формы для запросов POST и PUT.

form_data_parser_class: Псевдоним FormDataParser

classmethod from_values(*args, **kwargs)

Создаёт новый объект запроса на основе предоставленных значений. Если environ задан, отсутствующие значения заполняются оттуда. Этот метод полезен для небольших скриптов, когда вам нужно смоделировать запрос из URL. Не используйте этот метод для юнит-тестирования, существует полнофункциональный объект клиента (Client), который позволяет создавать multipart-запросы, поддерживать куки и т.д.

Принимает те же опции, что и EnvironBuilder.

Changelog

Изменено в версии 0.5: Этот метод теперь принимает те же аргументы, что и EnvironBuilder. Из-за этого параметр environ теперь называется environ_overrides.

Возвращает:

объект запроса

Параметры:

args (Any) –
kwargs (Any) –

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

Request

property full_path: str: Запрашиваемый путь, включая строку запроса.

END_OF_DOCUMENT_MARKER

get_data(cache=True, as_text=False, parse_form_data=False)

Это считывает буферизованные входящие данные от клиента в один байтовый объект. По умолчанию это кэшируется, но это поведение можно изменить, установив cache на False.

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

Обратите внимание, что если данные формы уже были обработаны, этот метод не вернёт ничего, так как обработка данных формы не кэширует данные, как это делает данный метод. Чтобы неявно вызвать функцию обработки данных формы, установите parse_form_data на True. Когда это сделано, значение возвращаемого результата этого метода будет пустой строкой, если парсер формы обрабатывает данные. В целом, это не обязательно, так как если все данные кэшируются (что является значением по умолчанию), парсер формы будет использовать кэшированные данные для обработки данных формы. Пожалуйста, всегда проверяйте длину содержимого перед вызовом этого метода, чтобы избежать исчерпания оперативной памяти сервера.

Если as_text установлено на True возвращаемое значение будет декодированной строкой.

Changelog

Новое в версии 0.9.

Параметры:

cache (bool) –
as_text (bool) –
parse_form_data (bool) –

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

Union[bytes, str]

get_json(force=False, silent=False, cache=True)

Обработать data как JSON.

Если тип MIME не указывает JSON (application/json, см. is_json), или при разборе произошла ошибка, on_json_loading_failed() вызывается, и её возвращаемое значение используется в качестве возвращаемого значения. По умолчанию это вызывает ошибку 400 Bad Request.

Параметры:

force (bool) – Игнорировать тип MIME и всегда пытаться разобрать JSON.
silent (bool) – Скрыть ошибки типа MIME и разбора, и вернуть None вместо этого.
cache (bool) – Сохранить разобранный JSON для возврата при последующих вызовах.

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

Optional[Any]

Changelog

Изменено в версии 2.1: Вызывать ошибку 400, если тип содержимого неверен.

headers: Заголовки, полученные с запросом.

property host: str: Имя хоста, к которому был сделан запрос, включая порт, если он нестандартный. Валидируется с помощью trusted_hosts.

property host_url: str: Схема и хост URL запроса.

property if_match: ETags

Объект, содержащий все теги в заголовке If-Match.

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

property if_modified_since: Optional[datetime]: Обработанный заголовок If-Modified-Since как объект datetime.

Changelog

Изменено в версии 2.0: Объект datetime с часовым поясом.

property if_none_match: ETags

Объект, содержащий все теги в заголовке If-None-Match.

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

property if_range: IfRange: Обработанный заголовок If-Range.

Changelog

Изменено в версии 2.0: IfRange.date с часовым поясом.

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

property if_unmodified_since: Optional[datetime]: Обработанный заголовок If-Unmodified-Since как объект datetime.

Changelog

Изменено в версии 2.0: Объект datetime с часовым поясом.

input_stream

Поток ввода WSGI.

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

property is_json: bool: Проверка, указывает ли тип MIME данные JSON, либо application/json, либо application/*+json.

is_multiprocess: булево значение, True если приложение обслуживается сервером WSGI, который запускает несколько процессов.

is_multithread: булево значение, True если приложение обслуживается многопоточным сервером WSGI.

is_run_once: булево значение, True если приложение будет выполнено только один раз за время существования процесса. Это относится, например, к CGI, но не гарантируется, что выполнение произойдёт только один раз.

property is_secure: bool: True если запрос был выполнен с помощью защищённого протокола (HTTPS или WSS).

property json: Optional[Any]

Обработанные данные JSON, если mimetype указывает JSON (application/json, см. is_json).

Вызывает get_json() с аргументами по умолчанию.

Если тип содержимого запроса не application/json, это вызовет ошибку 400 Bad Request.

Changelog

Изменено в версии 2.1: Вызывать ошибку 400, если тип содержимого неверен.

json_module = <module 'json' from '/home/docs/.asdf/installs/python/3.10.4/lib/python3.10/json/__init__.py'>: Модуль или другой объект, имеющий функции dumps и loads , соответствующие API встроенного модуля json.

list_storage_class: Псевдоним для ImmutableList

make_form_data_parser()

Создаёт парсер данных формы. Инициализирует form_data_parser_class с некоторыми параметрами.

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

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

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

max_content_length: Optional[int] = None

Максимальная длина содержимого. Передаётся в функцию парсинга данных формы (parse_form_data()). Если установлено и при доступе к атрибутам form или files парсинг завершается ошибкой, так как переданное значение превышает заданное, то возникает исключение RequestEntityTooLarge.

Подробнее см. Обработка данных запроса.

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

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

max_form_memory_size: Optional[int] = None

Максимальный размер поля формы. Передаётся в функцию парсинга данных формы (parse_form_data()). Если установлено и при доступе к атрибутам form или files размер данных в памяти для данных POST превышает заданное значение, возникает исключение RequestEntityTooLarge.

Подробнее см. Обработка данных запроса.

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

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

max_forwards: Поле заголовка запроса Max-Forwards предоставляет механизм для методов TRACE и OPTIONS ограничения количества прокси или шлюзов, которые могут пересылать запрос следующему серверу.

method: Метод, используемый для запроса, например GET.

property mimetype: str: Аналогично content_type, но без параметров (например, без кодировки, типа и т. д.) и всегда в нижнем регистре. Например, если тип содержимого text/HTML; charset=utf-8, то mimetype будет 'text/html'.

property mimetype_params: Dict[str, str]: Параметры mimetype в виде словаря. Например, если тип содержимого text/html; charset=utf-8, то параметры будут {'charset': 'utf-8'}.

on_json_loading_failed(e)

Вызывается, если get_json() терпит неудачу и не подавляется.

Если этот метод возвращает значение, оно используется в качестве возвращаемого значения для get_json(). По умолчанию вызывается исключение BadRequest.

Параметры:: e (Optional[ValueError]) – Если парсинг завершился ошибкой, это исключение. Оно будет None если тип содержимого не application/json.
Тип возвращаемого значения:: Any

origin: Хост, откуда исходит запрос. Установите access_control_allow_origin в ответе, чтобы указать разрешённые источники.

parameter_storage_class: Псевдоним для ImmutableMultiDict

path: Часть пути URL после root_path. Это путь, используемый для маршрутизации в приложении.

property pragma: HeaderSet: Поле заголовка Pragma используется для включения реализационных директив, которые могут применяться к любому получателю в цепочке запроса/ответа. Все директивы pragma указывают на необязательное поведение с точки зрения протокола; однако некоторые системы МОГУТ потребовать, чтобы это поведение соответствовало директивам.

query_string: Часть URL после “?”. Это исходное значение, используйте args для проанализированных значений.

property range: Optional[Range]

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

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

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

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

referrer: Поле заголовка Referer позволяет клиенту указать для блага сервера адрес (URI) ресурса, из которого был получен Request-URI (так называемый «referrer», хотя в поле заголовка допущена ошибка в написании).

remote_addr: Адрес клиента, отправившего запрос.

remote_user: Если сервер поддерживает аутентификацию пользователя и скрипт защищён, этот атрибут содержит имя пользователя, с которым пользователь прошёл аутентификацию.

root_path: Префикс, под которым установлено приложение, без заключительного слэша. path идёт после этого.

property root_url: str: Схема, хост и корневой путь URL запроса. Это корень, откуда происходит доступ к приложению.

scheme: Схема URL протокола, используемого запросом, например https или wss.

property script_root: str: Псевдоним для self.root_path. environ["SCRIPT_ROOT"] без заключительного слэша.

server: Адрес сервера. (host, port), (path, None) для сокетов Unix или None если неизвестно.

shallow: bool: Устанавливается при создании объекта запроса. Если True, чтение из тела запроса приведёт к RuntimeException. Полезно для предотвращения изменения потока из middleware.

property stream: IO[bytes]

Если входящие данные формы не были закодированы с известным типом MIME, данные хранятся в этом потоке без изменений для потребления. В большинстве случаев лучше использовать data, который предоставит эти данные в виде строки. Поток возвращает данные только один раз.

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

Изменения

Изменено в версии 0.9: Этот поток теперь всегда доступен, но может быть использован парсером формы позднее. Ранее поток устанавливался только если не происходило парсинга.

trusted_hosts: t.Optional[t.List[str]] = None

Допустимые имена хостов при обработке запросов. По умолчанию все хосты доверяются, что означает, что принимаемый от клиента хост будет принят.

Поскольку Host и X-Forwarded-Host заголовки могут быть установлены на любое значение вредоносным клиентом, рекомендуется либо установить это свойство, либо реализовать подобную валидацию в прокси-сервере (если приложение работает за ним).

Изменения

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

property url: str: Полный URL запроса со схемой, хостом, корневым путём, путём и строкой запроса.

property url_charset: str: Кодировка символов, предполагаемая для URL. По умолчанию значение charset.

Изменения

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

property url_root: str: Псевдоним для root_url. URL со схемой, хостом и корневым путём. Например, https://example.com/app/.

property user_agent: UserAgent: Пользовательский агент. Используйте user_agent.string для получения значения заголовка. Установите user_agent_class на подкласс UserAgent, чтобы обеспечить парсинг других свойств или других расширенных данных.

Изменения

Изменено в версии 2.0: Встроенный парсер устарел и будет удалён в Werkzeug 2.1. Необходимо установить подкласс UserAgent для парсинга данных из строки.

user_agent_class: Псевдоним для UserAgent

property values: CombinedMultiDict[str, str]

werkzeug.datastructures.CombinedMultiDict, объединяющий args и form.

Для GET-запросов присутствуют только args, а не form.

Изменения

Изменено в версии 2.0: Для GET-запросов присутствуют только args, а не form.

property want_form_data_parsed: bool: True если метод запроса несёт контент. По умолчанию это true, если отправлен Content-Type.

Изменения

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

class werkzeug.wrappers.Response(response=None, status=None, headers=None, mimetype=None, content_type=None, direct_passthrough=False)

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

Тело ответа гибкое, чтобы поддерживать различные случаи использования. Простой способ — передать байты или строку, которая будет закодирована как UTF-8. Передача итерируемого объекта байтов или строк делает этот ответ потоковым. Генератор особенно полезен для построения файла CSV в памяти или использования SSE (Server Sent Events). Также итерируемым является объект, похожий на файл, хотя в этом случае следует использовать вспомогательную функцию send_file().

Сам объект ответа является вызываемым WSGI-приложением. При вызове (__call__()) с environ и start_response, он передаст свой статус и заголовки start_response, а затем вернёт своё тело в виде итерируемого объекта.

from werkzeug.wrappers.response import Response

def index():
    return Response("Hello, World!")

def application(environ, start_response):
    path = environ.get("PATH_INFO") or "/"

    if path == "/":
        response = index()
    else:
        response = Response("Not Found", status=404)

    return response(environ, start_response)

Параметры:

response (Union[Iterable[str], Iterable[bytes]]) – Данные для тела ответа. Строка или байты, или кортеж или список строк или байтов для ответа фиксированной длины, или любой другой итерируемый объект строк или байтов для потокового ответа. По умолчанию пустое тело.
status (Optional[Union[int, str, HTTPStatus]]) – Код состояния ответа. Либо целое число, в этом случае добавляется сообщение по умолчанию, либо строка в формате {code} {message}, например, 404 Not Found. По умолчанию 200.
headers (Headers) – Объект Headers или список кортежей (key, value), которые будут преобразованы в объект Headers.
mimetype (Optional[str]) – Тип MIME (тип содержимого без набора символов или других параметров) ответа. Если значение начинается с text/ (или соответствует некоторым другим особым случаям), набор символов будет добавлен для создания content_type.
content_type (Optional[str]) – Полный тип содержимого ответа. Переопределяет построение значения из mimetype.
direct_passthrough (bool) – Передать тело ответа напрямую как WSGI-итерируемый объект. Это можно использовать, когда тело является двоичным файлом или другим итератором байтов, чтобы пропустить некоторые ненужные проверки. Вместо ручного задания используйте send_file().

Изменения

Изменено в версии 2.0: Объединить BaseResponse и миксины в один класс Response. Использование старых классов устарело и будет удалено в Werkzeug 2.1.

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

__call__(environ, start_response)

Обработать этот ответ как WSGI-приложение.

Параметры:

environ (WSGIEnvironment) – окружение WSGI.
start_response (StartResponse) – вызываемый объект ответа, предоставленный WSGI-сервером.

Возвращает:

итератор приложения

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

Iterable[bytes]

_ensure_sequence(mutable=False)

Этот метод может быть вызван методами, которым нужен последовательность. Если mutable имеет значение True, он также гарантирует, что последовательность ответа является стандартным списком Python.

Изменения

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

Параметры:: mutable (bool) –
Тип возвращаемого значения:: None

accept_ranges

Заголовок Accept-Ranges. Несмотря на то, что имя указывает на поддержку нескольких значений, должен быть только один строковый токен.

Общие значения 'bytes' и 'none'.

Изменения

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

property access_control_allow_credentials: bool: Разрешение браузеру совместно использовать учетные данные с кодом JavaScript. В рамках запроса предварительного просмотра он указывает, можно ли использовать учетные данные в запросе к ресурсу с другим происхождением.

access_control_allow_headers: Какие заголовки можно отправлять в запросе к ресурсу с другим происхождением.

access_control_allow_methods: Какие методы можно использовать для запроса к ресурсу с другим происхождением.

access_control_allow_origin: Происхождение или «*» для любого происхождения, которое может выполнять запросы к ресурсам с другим происхождением.

access_control_expose_headers: Какие заголовки может совместно использовать браузер с кодом JavaScript.

access_control_max_age: Максимальное время в секундах, на которое можно кэшировать настройки управления доступом.

add_etag(overwrite=False, weak=False)

Добавить ETag для текущего ответа, если его ещё нет.

Изменения

Изменено в версии 2.0: Для генерации значения используется SHA-1. MD5 может быть недоступен в некоторых средах.

Параметры:

overwrite (bool) –
weak (bool) –

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

None

age

Поле заголовка ответа Age сообщает об оценке времени, прошедшего с момента создания (или повторной проверки) ответа на сервере-источнике.

Значения Age — неотрицательные десятичные целые числа, представляющие время в секундах.

property allow: HeaderSet: Поле Allow в сообщении-заголовке указывает набор методов, поддерживаемых ресурсом, идентифицируемым URI запроса. Цель этого поля — проинформировать получателя о допустимых методах, связанных с ресурсом. Заголовок Allow ОБЯЗАТЕЛЬНО должен быть присутствующим в ответе 405 (Метод запрещён).

autocorrect_location_header = False: Если заголовок перенаправления Location является относительным URL, сделайте его абсолютным URL, включая схему и домен.

Changelog

Изменено в версии 2.1: По умолчанию это отключено, поэтому ответы будут отправлять относительные перенаправления.

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

automatically_set_content_length = True: Должен ли этот объект ответа автоматически устанавливать заголовок content-length, если это возможно? По умолчанию это true.

Changelog

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

property cache_control: ResponseCacheControl: Поле заголовка Cache-Control используется для указания директив, которые должны выполняться всеми механизмами кэширования вдоль цепочки запроса/ответа.

calculate_content_length()

Возвращает длину содержимого, если она доступна, или None в противном случае.

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

call_on_close(func)

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

Changelog

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

Параметры:: func (Callable[[], Any]) –
Тип возвращаемого значения:: Callable[[], Any]

charset = 'utf-8': кодировка символов ответа.

close()

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

Changelog

Добавлена в версии 0.9: Теперь можно использовать в операторе with.

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

content_encoding: Поле заголовка Content-Encoding используется как модификатор типа медиа. При наличии его значение указывает, какие дополнительные кодировки содержимого были применены к телу сущности, и, следовательно, какие механизмы декодирования должны быть применены для получения типа медиа, на который ссылается заголовок Content-Type.

property content_language: HeaderSet: Поле заголовка Content-Language описывает естественный язык(и) целевой аудитории для включенной сущности. Обратите внимание, что это может не соответствовать всем языкам, используемым в теле сущности.

content_length: Поле заголовка Content-Length указывает размер тела сущности в десятичном числе октетов, отправленных получателю, или, в случае метода HEAD, размер тела сущности, который был бы отправлен, если бы запрос был GET.

content_location: Поле заголовка Content-Location МОЖЕТ использоваться для предоставления местоположения ресурса для включенной в сообщение сущности, когда эта сущность доступна из местоположения, отличного от URI запрошенного ресурса.

content_md5: Поле заголовка Content-MD5, как определено в RFC 1864, представляет собой хэш-сумму MD5 тела сущности для обеспечения проверки целостности сообщения от конца до конца (MIC) тела сущности. (Примечание: MIC подходит для обнаружения случайных изменений тела сущности во время передачи, но не является доказательством защиты от злонамеренных атак.)

property content_range: ContentRange: Заголовок Content-Range в виде объекта ContentRange. Доступен даже если заголовок не задан.

Changelog

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

property content_security_policy: ContentSecurityPolicy

Заголовок Content-Security-Policy в виде объекта ContentSecurityPolicy. Доступен даже если заголовок не задан.

Заголовок Content-Security-Policy добавляет дополнительный уровень безопасности, который помогает обнаруживать и смягчать определенные типы атак.

property content_security_policy_report_only: ContentSecurityPolicy

Заголовок Content-Security-policy-report-only в виде объекта ContentSecurityPolicy. Доступен даже если заголовок не задан.

Заголовок Content-Security-Policy-Report-Only добавляет политику csp, которая не применяется, но сообщается, тем самым помогая обнаруживать определенные типы атак.

content_type: Поле заголовка Content-Type указывает тип медиа тела сущности, отправленного получателю, или, в случае метода HEAD, тип медиа, который был бы отправлен, если бы запрос был GET.

cross_origin_embedder_policy: Предотвращает загрузку документа любых ресурсов из другого источника, которые не предоставляют документу разрешение. Значения должны быть членом перечисления werkzeug.http.COEP.

cross_origin_opener_policy: Позволяет контролировать совместное использование группы контекста просмотра с документами из другого источника. Значения должны быть членом перечисления werkzeug.http.COOP.

property data: Union[bytes, str]: Дескриптор, который вызывает get_data() и set_data().

date: Поле заголовка Date представляет дату и время, в которые было создано сообщение, имея те же семантические значения, что и orig-date в RFC 822.

Changelog

Изменено в версии 2.0: Объект datetime имеет часовой пояс.

default_mimetype: Optional[str] = 'text/plain': тип MIME по умолчанию, если он не указан.

default_status = 200: статус по умолчанию, если он не указан.

END_OF_DOCUMENT_MARKER

delete_cookie(key, path='/', domain=None, secure=False, httponly=False, samesite=None)

Удалить cookie. Без ошибок, если ключ не существует.

Параметры:

key (str) – ключ (имя) cookie для удаления.
path (str) – если cookie была ограничена по пути, путь необходимо указать здесь.
domain (Optional[str]) – если cookie была ограничена по домену, домен необходимо указать здесь.
secure (bool) – Если True, cookie будет доступна только через HTTPS.
httponly (bool) – Запретить доступ к cookie через JavaScript.
samesite (Optional[str]) – Ограничить область действия cookie только запросами с «одного сайта».

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

None

direct_passthrough: Передать тело ответа напрямую как WSGI-итератор. Это может быть полезно, когда тело — это двоичный файл или другой итератор байтов, чтобы пропустить некоторые ненужные проверки. Используйте send_file() вместо ручного задания.

expires: Поле заголовка сущности Expires указывает дату/время, после которой ответ считается устаревшим. В кэше обычно не возвращаются устаревшие записи.

Изменения

Изменено в версии 2.0: Объект datetime имеет часовой пояс.

classmethod force_type(response, environ=None)

Принудительно установить, что WSGI-ответ — это объект ответа текущего типа. Werkzeug будет использовать Response во многих ситуациях, таких как исключения. Если вы вызываете get_response() для исключения, вы получите обычный объект Response, даже если вы используете пользовательский подкласс.

Этот метод может принудительно установить заданный тип ответа, а также преобразовывать произвольные WSGI-вызовы в объекты ответа, если предоставлен environ:

# convert a Werkzeug response object into an instance of the
# MyResponseClass subclass.
response = MyResponseClass.force_type(response)

# convert any WSGI application into a response object
response = MyResponseClass.force_type(response, environ)

Это особенно полезно, если вы хотите обработать ответы в основном диспетчере и использовать функциональные возможности, предоставляемые вашим подклассом.

Обратите внимание, что этот метод может изменять объекты ответов на месте, если это возможно!

Параметры:

response (Response) – объект ответа или WSGI-приложение.
environ (Optional[WSGIEnvironment]) – объект WSGI-среды.

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

объект ответа.

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

Response

freeze()

Подготовить объект ответа к сериализации с помощью pickle. Выполняет следующие действия:

Буферизует ответ в список, игнорируя implicity_sequence_conversion и direct_passthrough.
Устанавливает заголовок Content-Length.
Генерирует заголовок ETag , если он ещё не установлен.

Изменения

Изменено в версии 2.1: Параметр no_etag удалён.

Изменено в версии 2.0: Добавлен заголовок ETag, параметр no_etag устарел и будет удалён в Werkzeug 2.1.

Изменено в версии 0.6: Установлен заголовок Content-Length.

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

classmethod from_app(app, environ, buffered=False)

Создать новый объект ответа из выходных данных приложения. Лучше всего использовать приложение, которое всегда возвращает генератор. Иногда приложения могут использовать вызываемый объект write(), возвращаемый функцией start_response. Это пытается автоматически разрешить такие крайние случаи. Но если вы не получите ожидаемый вывод, вы должны установить buffered в True, что принуждает к буферизации.

Параметры:

app (WSGIApplication) – WSGI-приложение для выполнения.
environ (WSGIEnvironment) – WSGI-среда для выполнения.
buffered (bool) – установить в True для принудительной буферизации.

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

объект ответа.

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

Response

get_app_iter(environ)

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

Если метод запроса — HEAD или код состояния находится в диапазоне, где спецификация HTTP требует пустой ответ, возвращается пустая итерируемая последовательность.

Изменения

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

Параметры:: environ (WSGIEnvironment) – WSGI-среда запроса.
Возвращаемое значение:: итерируемая последовательность ответа.
Тип возвращаемого значения:: Iterable[bytes]

get_data(as_text=False)

Строковое представление тела ответа. При каждом вызове этого свойства итерируемая последовательность ответа кодируется и выравнивается. Это может привести к нежелательному поведению при обработке больших данных.

Это поведение можно отключить, установив implicit_sequence_conversion в False.

Если as_text установлено в True, возвращаемое значение будет строкой с декодированием.

Изменения

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

Параметры:: as_text (bool) –
Тип возвращаемого значения:: Union[bytes, str]

get_etag()

Возвращает кортеж в форме (etag, is_weak). Если ETag отсутствует, возвращаемое значение равно (None, None).

Тип возвращаемого значения:: Union[Tuple[str, bool], Tuple[None, None]]

get_json(force=False, silent=False)

Разбирает data как JSON. Полезно во время тестирования.

Если MIME-тип не указывает на JSON (application/json, см. is_json), это возвращает None.

В отличие от Request.get_json(), результат не кэшируется.

Параметры:

force (bool) – Игнорировать MIME-тип и всегда пытаться разобрать JSON.
silent (bool) – Отключить ошибки разбора и вернуть None вместо них.

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

Optional[Any]

get_wsgi_headers(environ)

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

Например, заголовок location (если он присутствует) объединяется с корневым URL-адресом среды. Кроме того, длина содержимого автоматически устанавливается в ноль для определенных кодов состояния.

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

Изменено в версии 0.6: Ранее эта функция называлась fix_headers и изменяла объект ответа на месте. Также начиная с версии 0.6, IRI в заголовках location и content-location обрабатываются правильно.

Кроме того, начиная с версии 0.6, Werkzeug будет пытаться установить длину содержимого, если сможет самостоятельно ее определить. Это происходит, если все строки в итераторе ответа уже закодированы, а итератор буферизован.

Параметры:: environ (WSGIEnvironment) – среда WSGI запроса.
Возвращает:: возвращает новый объект Headers.
Тип возвращаемого значения:: Headers

get_wsgi_response(environ)

Возвращает окончательный ответ WSGI в виде кортежа. Первый элемент кортежа — итератор приложения, второй — состояние, а третий — список заголовков. Возвращаемый ответ создается специально для данной среды. Например, если метод запроса в среде WSGI равен 'HEAD', ответ будет пустым, и будут присутствовать только заголовки и код состояния.

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

Новое в версии 0.6.

Параметры:: environ (WSGIEnvironment) – среда WSGI запроса.
Возвращает:: кортеж (app_iter, status, headers).
Тип возвращаемого значения:: Tuple[Iterable[bytes], str, List[Tuple[str, str]]]

implicit_sequence_conversion = True: если установлено в False, доступ к свойствам объекта ответа не будет пытаться использовать итератор ответа и преобразовывать его в список.

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

Новое в версии 0.6.2: Этот атрибут ранее назывался implicit_seqence_conversion. (Обратите внимание на опечатку). Если вы использовали эту функцию, вам необходимо адаптировать свой код к изменению имени.

property is_json: bool: Проверить, указывает ли MIME-тип на данные JSON, либо application/json, либо application/*+json.

property is_sequence: bool: Если итератор буферизован, это свойство будет True. Объект ответа будет считать итератор буферизованным, если атрибут ответа является списком или кортежем.

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

Новое в версии 0.6.

property is_streamed: bool

Если ответ передается потоком (ответ не является итератором с информацией о длине), это свойство равно True. В этом случае потоковый означает, что нет информации о количестве итераций. Это обычно True, если генератор передается объекту ответа.

Это полезно для проверки перед применением какой-либо пост-фильтрации, которая не должна выполняться для потоковых ответов.

iter_encoded()

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

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

property json: Optional[Any]

Разобранные данные JSON, если mimetype указывает на JSON (application/json, см. is_json).

Вызывает get_json() с аргументами по умолчанию.

json_module = <module 'json' from '/home/docs/.asdf/installs/python/3.10.4/lib/python3.10/json/__init__.py'>: Модуль или другой объект, который имеет функции dumps и loads, соответствующие API встроенного модуля json.

last_modified: Поле заголовка сущности Last-Modified указывает дату и время, когда, по мнению исходного сервера, вариант был последний раз изменен.

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

Изменено в версии 2.0: Объект datetime учитывает часовой пояс.

location: Поле заголовка ответа Location используется для перенаправления получателя в другое местоположение, отличное от Request-URI, для завершения запроса или определения нового ресурса.

make_conditional(request_or_environ, accept_ranges=False, complete_length=None)

Устанавливает условие для ответа на запрос. Этот метод лучше всего работает, если для ответа уже определён etag. Метод add_etag может быть использован для этого. Если вызов производится без etag, устанавливается только заголовок даты.

Ничего не делает, если метод запроса в запросе или окружении — не GET или HEAD.

Для оптимальной производительности при обработке запросов диапазона рекомендуется, чтобы ваш объект данных ответа реализовывал методы seekable, seek и tell, как описано в io.IOBase. Объекты, возвращаемые wrap_file(), автоматически реализуют эти методы.

Не удаляет тело ответа, так как за это отвечает функция __call__().

Возвращает self, позволяя вам return resp.make_conditional(req), но изменяет объект на месте.

Parameters:

request_or_environ (Union[WSGIEnvironment, Request]) – объект запроса или окружение WSGI, используемое для установления условия для ответа.
accept_ranges (Union[bool, str]) – Этот параметр определяет значение заголовка Accept-Ranges. Если False (значение по умолчанию), заголовок не устанавливается. Если True, он будет установлен на "bytes". Если None, он будет установлен на "none". Если это строка, используется это значение.
complete_length (Optional[int]) – Используется только в допустимых запросах диапазона. Он установит значение полной длины Content-Range и вычислит значение Content-Length. Этот параметр обязателен для успешного завершения запросов диапазона.

Raises:

RequestedRangeNotSatisfiable, если заголовок Range не удалось разобрать или удовлетворить.

Return type:

Response

Changelog

Изменено в версии 2.0: Обработка диапазона пропускается, если длина равна 0, вместо повышения ошибки 416 Range Not Satisfiable.

make_sequence()

Преобразует итератор ответа в список. По умолчанию это происходит автоматически, если необходимо. Если implicit_sequence_conversion отключено, этот метод не вызывается автоматически, и некоторые свойства могут вызывать исключения. Это также кодирует все элементы.

Changelog

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

Return type:: None

max_cookie_size = 4093: Выводит предупреждение, если заголовок cookie превышает этот размер. Значение по умолчанию, 4093, должно безопасно поддерживаться большинством браузеров. Cookie, больший этого размера, всё ещё будет отправлен, но некоторые браузеры могут игнорировать его или обработать его неправильно. Установите 0, чтобы отключить эту проверку.

Changelog

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

property mimetype: Optional[str]: MIME-тип (тип содержимого без кодировки и т.д.).

property mimetype_params: Dict[str, str]: Параметры MIME-типа в виде словаря. Например, если тип содержимого text/html; charset=utf-8, параметры будут {'charset': 'utf-8'}.

Changelog

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

response: Union[Iterable[str], Iterable[bytes]]

Тело ответа для отправки как WSGI-итератор. Список строк или байтов представляет ответ фиксированной длины, любая другая итерация — ответ потокового типа. Строки кодируются в байты как UTF-8.

Не устанавливайте обычную строку или байты, это сделает отправку ответа очень неэффективной, так как он будет перебирать один байт за раз.

property retry_after: Optional[datetime]

Поле заголовка ответа Retry-After может быть использовано с ответом 503 (Сервис недоступен) для указания того, как долго сервис, по ожиданиям, будет недоступен для клиента, сделавшего запрос.

Время в секундах до истечения срока действия или дата.

Changelog

Изменено в версии 2.0: Объект datetime является часовым.

set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)

Устанавливает cookie.

Выводится предупреждение, если размер заголовка cookie превышает max_cookie_size, но заголовок всё равно будет установлен.

Параметры:

ключ (str) – ключ (имя) cookie, который нужно установить.
значение (str) – значение cookie.
max_age (Optional[Union[timedelta, int]]) – количество секунд, или None (по умолчанию), если cookie должно действовать только пока открыт браузер клиента.
expires (Optional[Union[str, datetime, int, float]]) – объект datetime или метка времени Unix.
path (Optional[str]) – ограничивает cookie заданным путем, по умолчанию cookie распространяется на весь домен.
domain (Optional[str]) – для установки cookie для другого домена. Например, domain=".example.com" установит cookie, доступный для домена www.example.com, foo.example.com и т. д. В противном случае cookie будет доступен только для домена, который его установил.
secure (bool) – Если True, cookie будет доступен только через HTTPS.
httponly (bool) – Запрещает JavaScript-доступ к cookie.
samesite (Optional[str]) – Ограничивает область действия cookie, чтобы она применялась только к запросам с одного сайта.

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

None

set_data(value)

Устанавливает новую строку как ответ. Значение должно быть строкой или байтами. Если установлена строка, она кодируется в кодировку charset ответа (utf-8 по умолчанию).

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

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

Параметры:: значение (Union[bytes, str]) –
Тип возвращаемого значения:: None

set_etag(etag, weak=False)

Устанавливает etag и перезаписывает предыдущее значение, если оно было.

Параметры:

etag (str) –
weak (bool) –

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

None

property status: str: Код HTTP-статуса в виде строки.

property status_code: int: Код HTTP-статуса в виде числа.

property stream: ResponseStream: Итерируемый ответ как потоковый объект для записи.

property vary: HeaderSet: Значение поля Vary указывает набор полей заголовков запроса, которые полностью определяют, пока ответ является свежим, может ли кэшировать использовать ответ для ответа на последующий запрос без повторной проверки.

property www_authenticate: WWWAuthenticate: Заголовок WWW-Authenticate в обработанном виде.