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

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

Ваше приложение 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 пытается оградить вас от распространённых ошибок, запрещая определённые действия по мере возможности. Это служит двум целям: высокой производительности и предотвращения ошибок.

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

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

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

1. Объект ответа изменяемый.
2. Объект ответа можно сериализовать с помощью pickle или скопировать после вызова freeze().
3. Начиная с Werkzeug 0.6, безопасно использовать один и тот же объект ответа для нескольких ответов WSGI.
4. Можно создавать копии, используя 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. Полезно для предотвращения обработки данных формы в программном обеспечении промежуточного уровня, что сделает их недоступными для конечного приложения.

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

Изменено в версии 3.0: Параметры charset, url_charset, и encoding_errors были удалены.

Изменено в версии 2.1: Старые BaseRequest и классы-миксины были удалены.

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

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

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

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

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

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

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

Параметры:

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

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

IO[bytes]

max_content_length: int | None = None

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

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

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

max_form_memory_size: int | None = 500000

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

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

Изменено в версии 3.1: Значение по умолчанию изменилось на 500 КБ вместо неограниченного.

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

max_form_parts = 1000

Максимальное количество частей multipart для парсинга, передаётся в form_data_parser_class. Парсинг данных формы с более чем этим количеством частей приведёт к исключению RequestEntityTooLarge.

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

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

form_data_parser_class

Псевдоним FormDataParser

environ: WSGIEnvironment

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

shallow: bool

Устанавливается при создании объекта запроса. Если True, чтение из тела запроса вызовет RuntimeException. Полезно для предотвращения изменения потока из программного обеспечения промежуточного уровня.

classmethod from_values(*args, **kwargs)

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

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

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

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

Возвращает:

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

Параметры:

• args (Any)
• kwargs (Any)

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

Request

classmethod application(f)

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

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

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

Параметры:

f (t.Callable[[Запрос], WSGIApplication]) – вызываемый объект WSGI для обработки

Возвращает:

новый вызываемый объект WSGI

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

WSGIApplication

property want_form_data_parsed: bool

True если метод запроса несёт данные. По умолчанию это True, если отправляется Content-Type.

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

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

make_form_data_parser()

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

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

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

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

FormDataParser

close()

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

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

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

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

None

property stream: IO[bytes]

Поток ввода WSGI с проверками безопасности. Этот поток может быть потреблён только один раз.

Используйте get_data(), чтобы получить все данные в виде байтов или текста. Атрибут data будет содержать все байты только если они не представляют данные формы. В этом случае атрибут form будет содержать обработанные данные формы.

В отличие от input_stream, этот поток защищает от бесконечных потоков или чтения за пределами content_length или max_content_length.

Если max_content_length установлено, это может быть применено к потокам, если wsgi.input_terminated установлено. В противном случае возвращается пустой поток.

Если предел достигнут до исчерпания основного потока (например, слишком большой файл или бесконечный поток), оставшиеся данные потока безопасно не могут быть прочитаны. В зависимости от того, как сервер обрабатывает это, клиенты могут показать ошибку «разрыв соединения» вместо ответа 413.

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

Изменено в версии 2.3: Проверка max_content_length предварительно и во время чтения.

Изменено в версии 0.9: Поток всегда устанавливается (но может быть потреблён), даже если сначала был обращён к парсеру данных формы.

input_stream

Необработанный поток ввода WSGI без проверок безопасности.

Использование опасно. Он не защищает от бесконечных потоков или чтения за пределами content_length или max_content_length.

Используйте stream вместо этого.

property data: bytes

Необработанные данные, считанные из stream. Будет пустым, если запрос представляет данные формы.

Чтобы получить необработанные данные, даже если они представляют данные формы, используйте get_data().

get_data(cache: bool = True, as_text: Literal[False] = False, parse_form_data: bool = False) → bytes

get_data(cache:bool=True, as_text:Literal[True]=False, parse_form_data:bool=False) → str

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

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

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

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

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

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

property form: ImmutableMultiDict[str, str]

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

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

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

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

property values: CombinedMultiDict[str, str]

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

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

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

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

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 script_root: str

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

property url_root: str

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

remote_user

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

is_multithread

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

is_multiprocess

Булево значение, которое True , если приложение обслуживается сервером WSGI, запускающим несколько процессов.

is_run_once

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

json_module = <module 'json' from '/home/docs/.asdf/installs/python/3.12.3/lib/python3.12/json/__init__.py'>

Модуль или другой объект, который имеет dumps и loads функции, соответствующие API встроенного модуля json.

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]

Если существует заголовок переадресации, это список всех IP-адресов от IP-адреса клиента до последнего прокси-сервера.

property args: MultiDict[str, str]

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

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

Changelog

Изменено в версии 2.3: Недействительные байты остаются в процентах кодированных.

property authorization: Authorization | None

Заголовок Authorization , проанализированный в объект Authorization. None , если заголовок отсутствует.

Changelog

Изменено в версии 2.3: Authorization больше не является dict. Был добавлен атрибут token для схем аутентификации, которые используют токен вместо параметров.

property base_url: str

Аналогично url, но без строки запроса.

property cache_control: RequestCacheControl

Объект RequestCacheControl для входящих заголовков кэширования.

content_encoding

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

Changelog

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

property content_length: int | None

Поле заголовка сущности 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 с содержимым всех файлов cookie, переданных с запросом.

date

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

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

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

dict_storage_class

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

property full_path: str

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

property host: str

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

property host_url: str

Схема и хост URL запроса.

property if_match: ETags

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

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

ETags

property if_modified_since: datetime | None

Разбор заголовка If-Modified-Since как объекта datetime.

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

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

property if_none_match: ETags

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

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

ETags

property if_range: IfRange

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

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

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

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

property if_unmodified_since: datetime | None

Разбор заголовка If-Unmodified-Since как объекта datetime.

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

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

property is_json: bool

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

property is_secure: bool

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

property json: Any | None

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

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

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

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

Изменено в версии 2.3: Вызывает ошибку 415 вместо 400.

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

list_storage_class

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

max_forwards

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

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'}.

origin

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

parameter_storage_class

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

property pragma: HeaderSet

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

property range: Range | None

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

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

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

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

Range

referrer

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

property root_url: str

Схема, хост и корневой путь URL запроса. Это корень, из которого осуществляется доступ к приложению.

trusted_hosts: list[str] | None = None

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

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

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

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

property url: str

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

property user_agent: UserAgent

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

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

Изменено в версии 2.1: Встроенный парсер был удален. Установите user_agent_class в подкласс UserAgent для разбора данных из строки.

user_agent_class

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

method

Метод, с помощью которого был выполнен запрос, например, GET.

scheme

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

server

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

root_path

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

path

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

query_string

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

headers

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

remote_addr

Адрес клиента, отправляющего запрос.

get_json(force: bool = False, silent: Literal[False] = False, cache: bool = True) → Any

get_json(force:bool=False, silent:bool=False, cache:bool=True) → Any|None

Разбор data как JSON.

Если тип MIME не указывает на JSON (application/json, см. is_json), или разбор завершился ошибкой, вызывается on_json_loading_failed(), и его возвращаемое значение используется как возвращаемое значение. По умолчанию это приводит к ошибке 415 Unsupported Media Type.

Параметры:

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

Изменения

Изменено в версии 2.3: Выводить ошибку 415 вместо 400.

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

on_json_loading_failed(e)

Вызывается, если get_json() завершился ошибкой и не был заглушен.

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

Параметры:

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

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

Any

Изменения

Изменено в версии 2.3: Выводить ошибку 415 вместо 400.

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

Изменения

Изменено в версии 2.1: Старые BaseResponse и миксин-классы были удалены.

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

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

__call__(environ, start_response)

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

Параметры:

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

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

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

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

t.Iterable[bytes]

_ensure_sequence(mutable=False)

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

Изменения

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

Параметры:

mutable (bool)

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

None

implicit_sequence_conversion = True

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

Изменения

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

autocorrect_location_header = False

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

Изменения

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

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

automatically_set_content_length = True

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

Изменения

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

direct_passthrough

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

response: Iterable[str] | Iterable[bytes]

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

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

call_on_close(func)

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

Изменения

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

Параметры:

func (Callable[[], Any])

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

Callable[[], Any]

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 (Ответ) – объект ответа или WSGI-приложение.
• environ (WSGIEnvironment | None) – объект WSGI-среды.

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

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

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

Ответ

classmethod from_app(app, environ, buffered=False)

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

Параметры:

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

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

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

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

Ответ

get_data(as_text: Literal[False] = False) → bytes

get_data(as_text:Literal[True]) → str

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

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

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

Changelog

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

set_data(value)

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

Changelog

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

Параметры:

value (bytes | str)

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

None

property data: bytes | str

Дескриптор, который вызывает get_data() и set_data().

calculate_content_length()

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

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

int | None

make_sequence()

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

Changelog

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

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

None

iter_encoded()

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

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

Iterator[bytes]

property is_streamed: bool

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

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

property is_sequence: bool

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

Changelog

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

close()

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

Changelog

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

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

None

freeze()

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

• Буферизация ответа в список, игнорируя implicity_sequence_conversion и direct_passthrough.
• Установить заголовок Content-Length.
• Сгенерировать заголовок ETag если он не установлен.

Changelog

Изменено в версии 2.1: Убран параметр no_etag.

Изменено в версии 2.0: Заголовок ETag всегда добавляется.

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

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

None

get_wsgi_headers(environ)

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

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

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

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

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

Параметры:

environ (WSGIEnvironment) – среда WSGI запроса.

Возвращает:

возвращает новый объект Headers.

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

Headers

get_app_iter(environ)

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

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

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

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

Параметры:

environ (WSGIEnvironment) – среда WSGI запроса.

Возвращает:

итерируемый объект ответа.

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

t.Iterable[bytes]

get_wsgi_response(environ)

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

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

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

Параметры:

environ (WSGIEnvironment) – среда WSGI запроса.

Возвращает:

кортеж (app_iter, status, headers).

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

tuple[t.Iterable[bytes], str, list[tuple[str, str]]]

json_module = <module 'json' from '/home/docs/.asdf/installs/python/3.12.3/lib/python3.12/json/__init__.py'>

Модуль или другой объект, имеющий функции dumps и loads, которые соответствуют API встроенного модуля json.

property json: Any | None

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

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

get_json(force: bool = False, silent: Literal[False] = False) → Any

get_json(force:bool=False, silent:bool=False) → Any|None

Парсит data как JSON. Полезно при тестировании.

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

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

Параметры:

• force – Игнорировать тип MIME и всегда пытаться распарсить JSON.
• silent – Заглушить ошибки парсинга и вместо этого вернуть None.

property stream: ResponseStream

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

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), но изменяет объект на месте.

Параметры:

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

Исключения:

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

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

Response

Изменения

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

add_etag(overwrite=False, weak=False)

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

Изменения

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

Параметры:

• overwrite (bool)
• weak (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

Максимальное время в секундах, в течение которого настройки управления доступом могут быть кэшированы.

age

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

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

property allow: HeaderSet

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

property cache_control: ResponseCacheControl

Общий заголовок Cache-Control используется для указания директив, которые ДОЛЖНЫ выполняться всеми механизмами кэширования вдоль цепочки запроса/ответа.

content_encoding

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

property content_language: HeaderSet

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

content_length

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

content_location

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

content_md5

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

property content_range: ContentRange

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

Изменения

Добавлен в версии 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.

date

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

Changelog

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

default_mimetype: str | None = 'text/plain'

по умолчанию MIME-тип, если он не указан.

default_status = 200

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

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

Удаляет cookie. При отсутствии ключа ошибка не генерируется.

Параметры:

• ключ (str) – ключ (имя) cookie, который нужно удалить.
• путь (str | None) – если cookie должен быть удален для определенного пути, путь должен быть указан здесь.
• домен (str | None) – если cookie должен быть удален для определенного домена, домен должен быть указан здесь.
• secure (bool) – Если True, cookie будет доступен только через HTTPS.
• httponly (bool) – Запрещает доступ к cookie через JavaScript.
• samesite (str | None) – Ограничивает область действия cookie только запросами «с того же сайта».
• разделенный (bool) – Если True, cookie будет разделен.

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

None

expires

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

Changelog

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

get_etag()

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

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

кортеж[str, bool] | кортеж[None, None]

property is_json: bool

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

last_modified

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

Changelog

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

location

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

max_cookie_size = 4093

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

Changelog

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

property mimetype: str | None

MIME-тип (тип содержимого без набора символов и т.д.).

property mimetype_params: dict[str, str]

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

Changelog

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

property retry_after: datetime | None

Поле заголовка ответа 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, partitioned=False)

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

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

Параметры:

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

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

None

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

Изменено в версии 3.1: Параметр partitioned был добавлен.

set_etag(etag, weak=False)

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

Параметры:

• etag (str)
• weak (bool)

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

None

property status: str

Код HTTP-статуса в виде строки.

property status_code: int

Код HTTP-статуса в виде числа.

property vary: HeaderSet

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

property www_authenticate: WWWAuthenticate

Заголовок WWW-Authenticate, разобранный в объект WWWAuthenticate. Изменение объекта изменит значение заголовка.

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

response.www_authenticate = WWWAuthenticate(
    "basic", {"realm": "Authentication Required"}
)

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

Чтобы удалить этот заголовок, присвойте None или используйте del.

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

Изменено в версии 2.3: Этому атрибуту можно присвоить значение, чтобы установить заголовок. Для установки нескольких значений заголовков можно присвоить список. Используйте del для удаления заголовка.

Изменено в версии 2.3: WWWAuthenticate больше не является dict. Атрибут token был добавлен для аутентификационных запросов, которые используют маркер вместо параметров.