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

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

Ваше приложение 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 environ генерируется сервером WSGI и содержит информацию о конфигурации сервера и запросе клиента.
• populate_request (bool) – Добавить этот объект запроса в WSGI environ как 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]

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[[Запрос], 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 для входящих заголовков управления кэшем.

close()

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

Изменения

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

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

None

content_encoding

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

Изменения

Введено в версии 0.9.

property content_length: int | None

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

content_md5

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

Изменения

Введено в версии 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.

Изменения

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

dict_storage_class

Псевдоним ImmutableMultiDict

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.

Изменения

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

form_data_parser_class

Псевдоним FormDataParser

classmethod from_values(*args, **kwargs)

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

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

Изменения

Изменено в версии 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 Неподдерживаемый тип медиа.

Параметры:

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

Changelog

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

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

headers

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

property host: str

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

property host_url: str

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

property if_match: ETags

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

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

ETags

property if_modified_since: datetime | None

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

Changelog

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

property if_none_match: ETags

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

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

ETags

property if_range: IfRange

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

Changelog

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

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

property if_unmodified_since: 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.12/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 объём данных в памяти для данных POST превышает указанное значение, генерируется исключение 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) ресурса, из которого был получен запрос 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.

Changelog

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

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

trusted_hosts: list[str] | None = None

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

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

Changelog

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

property url: str

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

property url_root: str

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

property user_agent: UserAgent

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

Changelog

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

user_agent_class

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

property values: CombinedMultiDict[str, str]

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

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

Changelog

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

property want_form_data_parsed: bool

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

Changelog

Добавлена в версии 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 истинно, он также гарантирует, что последовательность ответа является стандартным списком Python.

Изменения

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

Параметры:

mutable (bool) –

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

None

accept_ranges

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

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

Изменения

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

property access_control_allow_credentials: bool

Указывает, могут ли данные проверки подлинности быть общими для браузера и кода JavaScript. В рамках запроса предварительной обработки указывается, могут ли данные проверки подлинности использоваться при кросс-доменном запросе.

access_control_allow_headers

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

access_control_allow_methods

Методы, которые могут быть использованы для кросс-доменного запроса.

access_control_allow_origin

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

access_control_expose_headers

Заголовки, которые могут быть общими для браузера и кода JavaScript.

access_control_max_age

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

add_etag(overwrite=False, weak=False)

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

Изменения

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

Параметры:

• overwrite (bool) –
• weak (bool) –

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

None

age

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

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

property allow: HeaderSet

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

autocorrect_location_header = False

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

Изменения

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

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

automatically_set_content_length = True

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

Изменения

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

property cache_control: ResponseCacheControl

Поле заголовка Cache-Control используется для указания директив, которые ОБЯЗАТЕЛЬНО должны выполняться всеми механизмами кеширования вдоль цепочки запроса/ответа.

calculate_content_length()

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

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

int | None

call_on_close(func)

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

Изменения

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

Параметры:

func (Callable[[], Any]) –

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

Callable[[], Any]

close()

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

Изменения

Новая в версии 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. Доступен даже если заголовок не задан.

Изменения

Новая в версии 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.

Изменения

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

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

Параметры:

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

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

None

direct_passthrough

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

expires

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

Изменения

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

classmethod force_type(response, environ=None)

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

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

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

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

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

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

Параметры:

• response (Ответ) – объект ответа или WSGI-приложение.
• environ (WSGIEnvironment | None) – объект WSGI-окружения.

Возвращает:

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

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

Ответ

freeze()

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

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

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

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

Возвращает:

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

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

Ответ

get_app_iter(environ)

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

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

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

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

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

Введено в версии 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-адресом среды. Также длина содержимого автоматически устанавливается в ноль для определённых кодов состояния.

Изменения

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

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

Параметры:

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

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

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

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

Headers

get_wsgi_response(environ)

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

Изменения

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

Параметры:

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

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

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

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

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

implicit_sequence_conversion = True

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

Изменения

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

property is_json: bool

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

property is_sequence: bool

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

Изменения

Добавлена в версии 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.12/lib/python3.10/json/__init__.py'>

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

last_modified

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

Изменения

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

location

Поле Location response-header используется для перенаправления получателя в местоположение, отличное от 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 | Запрос) – объект запроса или WSGI-окружение, используемое для создания условного ответа.
• accept_ranges (bool | строка) – Этот параметр определяет значение заголовка Accept-Ranges. Если False, заголовок не устанавливается. Если True, он будет установлен на значение "bytes". Если это строка, используется это значение.
• complete_length (целое | None) – Используется только в корректных запросах с диапазоном. Установит значение полной длины Content-Range и вычислит фактическое значение Content-Length. Этот параметр обязателен для успешного завершения запросов с диапазонами.

Исключения:

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

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

Ответ

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

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

make_sequence()

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

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

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

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

None

max_cookie_size = 4093

Выводить предупреждение, если размер заголовка cookie превышает этот размер. Значение по умолчанию 4093 должно быть безопасно поддерживаться большинством браузеров. Куки, размер которых больше этого значения, всё равно будут отправлены, но некоторые браузеры могут игнорировать их или обращаться с ними неправильно. Установите в 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 (строка) – ключ (имя) устанавливаемого cookie.
• value (строка) – значение cookie.
• max_age (timedelta | целое | None) – должно быть числом секунд, или None (по умолчанию), если cookie должно действовать только в течение сеанса браузера клиента.
• expires (строка | datetime | целое | число с плавающей точкой | None) – должен быть объектом datetime или меткой времени Unix.
• path (строка | None) – ограничивает cookie заданным путём, по умолчанию он охватывает весь домен.
• domain (строка | None) – если вы хотите установить cookie для другого домена. Например, domain="example.com" установит cookie, который доступен для домена www.example.com, foo.example.com и т. д. В противном случае cookie будет доступен только для домена, который его установил.
• secure (булево) – Если True, cookie будет доступен только через HTTPS.
• httponly (булево) – Запрещает доступ к cookie через JavaScript.
• samesite (строка | None) – Ограничивает область действия cookie, чтобы он прикреплялся только к запросам, которые являются «одного сайта».

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

None

set_data(value)

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

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

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

Параметры:

value (байты | строка) –

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

None

set_etag(etag, weak=False)

Установить тег, а при необходимости переопределить старый.

Параметры:

• 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 был добавлен для вызовов аутентификации, использующих токен вместо параметров.