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

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

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

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

Изменено в версии 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]

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 (t.Callable[[Request], WSGIApplication]) – вызываемый объект WSGI для декорирования

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

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

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

WSGIApplication

property args: MultiDict[str, str]

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

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

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

property authorization: Authorization | None

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

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

property base_url: str

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

property cache_control: RequestCacheControl

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

property charset: str

Кодировка символов, используемая для декодирования данных тела, формы и cookie. По умолчанию UTF-8.

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 3.0. Данные запроса должны всегда быть в UTF-8.

close()

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

Changelog

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

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

None

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, переданных вместе с запросом.

property data: bytes

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

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

date

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

Changelog

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

dict_storage_class

Псевдоним ImmutableMultiDict

property encoding_errors: str

Как обрабатываются ошибки при декодировании байтов. По умолчанию «заменить».

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 3.0.

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-запросы, поддерживает cookie и т.д.

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

Changelog

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

Возвращает:

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

Параметры:

• args (Any) –
• kwargs (Any) –

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

Request

property full_path: str

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

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, значением возврата будет декодированная строка.

Changelog

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

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.

Changelog

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

headers

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

property host: str

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

property host_url: str

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

property if_match: ETags

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

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

ETags

property if_modified_since: datetime | None

Обработанный заголовок If-Modified-Since как объект datetime.

Changelog

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

property if_none_match: ETags

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

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

ETags

property if_range: IfRange

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

Changelog

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

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

property if_unmodified_since: datetime | None

Обработанный заголовок If-Unmodified-Since как объект datetime.

Changelog

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

input_stream

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

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

Используйте 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: Any | None

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

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

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

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

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

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

json_module = <module 'json' from '/home/docs/.asdf/installs/python/3.10.8/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: int | None = None

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

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

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

max_form_memory_size: int | None = None

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

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

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

max_form_parts = 1000

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

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

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

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 (ValueError | None) – Если разбор завершился неудачно, это исключение. Будет None , если тип содержимого не application/json.

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

Any

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

origin

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

parameter_storage_class

Псевдоним ImmutableMultiDict

path

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

property pragma: HeaderSet

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

query_string

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

property range: Range | None

Обработанный заголовок Range.

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

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

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

Range

referrer

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

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. Полезно для предотвращения изменения потока из промежуточного ПО.

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: Поток всегда установлен (но может быть использован), даже если доступ к разбору формы был получен первым.

trusted_hosts: list[str] | None = None

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

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

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

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

property url: str

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

property url_charset: str

Кодировка символов, используемая при декодировании процентов кодированных байтов в args. По умолчанию соответствует значению charset, которое по умолчанию равно UTF-8.

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 3.0. Процент-кодированные байты всегда должны быть UTF-8.

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

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

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

property allow: HeaderSet

Поле Allow заголовка сущности перечисляет набор методов, поддерживаемых ресурсом, идентифицируемым Request-URI. Цель этого поля — сообщить получателю о допустимых методах, связанных с ресурсом. Заголовок Allow ДОЛЖЕН присутствовать в ответе 405 (Метод запрещён).

autocorrect_location_header = False

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

Изменения

Изменено в версии 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 в противном случае.

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

int | None

call_on_close(func)

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

Changelog

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

Параметры:

func (Callable[[], Any]) –

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

Callable[[], Any]

property charset: str

Кодировка символов, используемая для кодирования данных тела и куки. По умолчанию — UTF-8.

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 3.0. Данные ответа всегда должны быть в кодировке 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: bytes | str

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

date

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

Changelog

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

default_mimetype: str | None = 'text/plain'

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

default_status = 200

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

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

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

Параметры:

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

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

None

direct_passthrough

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

expires

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

Changelog

Изменено в версии 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 (WSGIEnvironment | None) — объект среды WSGI.

Возвращает:

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

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

Response

freeze()

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

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

Changelog

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

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

Изменено в версии 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 требует пустого ответа, возвращается пустая итерируемая последовательность.

Changelog

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

Параметры:

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

Возвращает:

итерируемая последовательность ответа.

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

t.Iterable[bytes]

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.

get_etag()

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

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

tuple[str, bool] | tuple[None, None]

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 вместо этого.

get_wsgi_headers(environ)

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

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

Changelog

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

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

Параметры:

environ (WSGIEnvironment) – окружение WSGI запроса.

Возвращает:

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

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

Headers

get_wsgi_response(environ)

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

Changelog

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

Параметры:

environ (WSGIEnvironment) – окружение WSGI запроса.

Возвращает:

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

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

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

implicit_sequence_conversion = True

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

Changelog

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

property is_json: bool

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

property is_sequence: bool

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

Changelog

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

property is_streamed: bool

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

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

iter_encoded()

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

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

Iterator[bytes]

property json: Any | None

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

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

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

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

last_modified

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

Changelog

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

Параметры:

• 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.

make_sequence()

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

Изменения

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

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

None

max_cookie_size = 4093

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

Изменения

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

property mimetype: str | None

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

property mimetype_params: dict[str, str]

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

Изменения

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

response: Iterable[str] | Iterable[bytes]

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

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

property retry_after: datetime | None

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

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

Изменения

Изменено в версии 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, но заголовок все равно будет установлен.

Параметры:

• 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) – запретить JavaScript доступ к cookie.
• samesite (str | None) – ограничить область действия cookie только запросами «того же сайта».

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

None

set_data(value)

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

Изменения

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

Параметры:

value (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 распарсен в объект WWWAuthenticate. Изменение объекта изменит значение заголовка.

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

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

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

Для отмены этого заголовка присвойте None или используйте del.

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

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