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

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

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

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

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

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

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

from werkzeug.wrappers import Request, Response

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

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

from werkzeug.wrappers import Request, Response

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

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

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

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

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

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

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

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

Базовые обёртки

Эти объекты реализуют общий набор операций. Им не хватает продвинутых дополнительных функций, таких как анализ пользовательского агента или обработка etag. Эти функции доступны путём добавления различных миксин-классов или использования Request и Response.

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

Очень базовый объект запроса. Он не реализует продвинутых функций, таких как разбор тега сущности или управления кешем. Объект запроса создаётся с окружением WSGI в качестве первого аргумента и добавит себя в окружение WSGI как 'werkzeug.request' , если он не был создан с populate_request установленным в False.

Доступно несколько миксинов, которые добавляют дополнительную функциональность объекту запроса, также есть класс Request, который наследуется от BaseRequest и содержит все важные миксины.

Рекомендуется создать пользовательский подкласс BaseRequest и добавить недостающую функциональность, либо через миксины, либо через прямое реализацию. Вот пример таких подклассов:

from werkzeug.wrappers import BaseRequest, ETagRequestMixin

class Request(BaseRequest, ETagRequestMixin):
    pass

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

По умолчанию объект запроса предполагает, что все текстовые данные закодированы в utf-8. Для получения дополнительной информации о настройке поведения см. главу по Unicode.

По умолчанию объект запроса добавляется в окружение WSGI как werkzeug.request для поддержки системы отладки. Если этого не нужно, установите populate_request в False.

Если shallow равно True, окружение инициализируется как поверхностный объект вокруг environ. Любое действие, которое бы каким-либо образом изменило environ (например, обработка данных формы), вызывает исключение, если атрибут shallow не установлен явно в False. Это полезно для мидлверов, где вы не хотите случайно обработать данные формы. Поверхностный запрос не заполняется в окружение WSGI.

Changelog

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

environ: Окружение WSGI, которое используется объектом запроса для извлечения данных.

shallow: True если этот объект запроса является поверхностным (не изменяет environ), False в противном случае.

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

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

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

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

Параметры:

Параметры:	total_content_length – общий объём содержимого всего запроса, гарантированно присутствует. content_type – тип MIME загружаемого файла. filename – имя загружаемого файла. Может быть `None`. content_length – длина этого файла. Обычно это значение не предоставляется, потому что веб-браузеры не предоставляют его.

total_content_length – общий объём содержимого всего запроса, гарантированно присутствует.
content_type – тип MIME загружаемого файла.
filename – имя загружаемого файла. Может быть None.
content_length – длина этого файла. Обычно это значение не предоставляется, потому что веб-браузеры не предоставляют его.

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

classmethod application(f)

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

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

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

Параметры:	f – вызываемый объект WSGI для декорирования
Возвращает:	новый вызываемый объект WSGI

args

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

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

base_url: Аналогично url, но без строки запроса. См. также: trusted_hosts.

charset = 'utf-8': кодировка символов запроса, по умолчанию utf-8

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

Changelog

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

cookies: dict с содержимым всех файлов cookie, переданных вместе с запросом.

data: Содержит входящие данные запроса как строку, если они пришли с типом MIME, с которым Werkzeug не работает.

dict_storage_class: псевдоним для werkzeug.datastructures.ImmutableMultiDict

disable_data_descriptor = False: Указывает, должен ли дескриптор данных разрешать чтение и буферизацию входного потока. По умолчанию включён.

Changelog

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

encoding_errors = 'replace': обработка ошибок при ошибках, по умолчанию ‘replace’

files

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

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

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

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

form

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

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

Changelog

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

form_data_parser_class: псевдоним для werkzeug.formparser.FormDataParser

END_OF_DOCUMENT_MARKER

classmethod from_values(*args, **kwargs)

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

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

Changelog

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

Возвращает:	объект запроса

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

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

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

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

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

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

Changelog

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

headers: Заголовки из WSGI environ как неизменяемый EnvironHeaders.

host: Просто хост, включая порт, если он доступен. См. также: trusted_hosts.

host_url: Просто хост со схемой в качестве IRI. См. также: trusted_hosts.

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

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

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

is_secure: True если запрос защищён.

list_storage_class: псевдоним для werkzeug.datastructures.ImmutableList

make_form_data_parser(): Создаёт обработчик данных формы. Создаёт экземпляр form_data_parser_class с некоторыми параметрами.

Changelog

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

max_content_length = None

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

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

Changelog

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

max_form_memory_size = None

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

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

Changelog

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

method: Метод запроса. (Например, 'GET' или 'POST').

parameter_storage_class: псевдоним для werkzeug.datastructures.ImmutableMultiDict

path: Запрашиваемый путь в виде unicode. Работает аналогично пути в WSGI окружении, но всегда содержит ведущий слеш, даже если обращение происходит к корню URL.

query_string: Параметры URL как необработанная строка байтов.

remote_addr: Удаленный адрес клиента.

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

scheme: Схема URL (http или https).

Changelog

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

script_root: Корневой путь сценария без конечного слеша.

stream

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

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

Changelog

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

trusted_hosts = None

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

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

Changelog

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

url: Восстановленный текущий URL в виде IRI. См. также: trusted_hosts.

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

Изменения

Новая функция в версии 0.6.

url_root: Полный URL-корень (с именем хоста), корень приложения в виде IRI. См. также: trusted_hosts.

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

want_form_data_parsed: Возвращает True, если метод запроса несет данные. Начиная с Werkzeug 0.9, это будет так, если передается тип контента.

Изменения

Новая функция в версии 0.8.

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

Базовый класс ответа. Самое важное свойство объекта ответа заключается в том, что это обычное WSGI-приложение. Он инициализируется несколькими параметрами ответа (заголовки, тело, код состояния и т. д.) и запускает валидный WSGI-ответ при вызове с параметрами environ и start_response.

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

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

from werkzeug.wrappers import BaseResponse as Response

def index():
    return Response('Index page')

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)

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

Чтобы принудительно назначить новый тип уже существующих ответов, можно использовать метод force_type(). Это полезно, если вы работаете с различными подклассами объектов ответа и хотите обработать их с известным интерфейсом.

По умолчанию объект ответа предполагает, что все текстовые данные закодированы в формате utf-8. Подробную информацию о настройке поведения см. в главе о Unicode.

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

Особое замечание для mimetype и content_type: Для большинства типов MIME mimetype и content_type работают одинаково, различие влияет только на типы MIME «text». Если тип MIME, переданный с mimetype, — тип MIME, начинающийся с text/, параметр charset объекта ответа добавляется к нему. В отличие от этого, параметр content_type всегда добавляется как заголовок без изменений.

Изменения

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

Параметры:

Параметры:	response – строка или итерируемый объект ответа. status – строка со статусом или целое число с кодом статуса. headers – список заголовков или объект `Headers`. mimetype – тип MIME ответа. См. примечание выше. content_type – тип содержимого для ответа. См. примечание выше. direct_passthrough – если установлено в значение `True`, `iter_encoded()` не вызывается перед итерацией, что позволяет передавать специальные итераторы без изменений (см. `wrap_file()` для получения дополнительной информации).

response – строка или итерируемый объект ответа.
status – строка со статусом или целое число с кодом статуса.
headers – список заголовков или объект Headers.
mimetype – тип MIME ответа. См. примечание выше.
content_type – тип содержимого для ответа. См. примечание выше.
direct_passthrough – если установлено в значение True, iter_encoded() не вызывается перед итерацией, что позволяет передавать специальные итераторы без изменений (см. wrap_file() для получения дополнительной информации).

response: Итератор приложения. Если он создан из строки, это будет список, в противном случае — объект, предоставленный в качестве итератора приложения. (Первый аргумент, переданный BaseResponse)

headers: Объект Headers представляющий заголовки ответа.

status_code: Код состояния ответа в виде целого числа.

direct_passthrough: Если direct_passthrough=True был передан объекту ответа или если данному атрибуту было присвоено значение True перед использованием объекта ответа как WSGI-приложения, обернутый итератор возвращается без изменений. Это позволяет передавать специальный wsgi.file_wrapper объекту ответа. См. wrap_file() для получения дополнительной информации.

__call__(environ, start_response)

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

Параметры:	environ – WSGI-среда. start_response – вызываемая функция ответа, предоставленная WSGI-сервером.
Возвращает:	итератор приложения

_ensure_sequence(mutable=False): Этот метод может быть вызван методами, которым необходим последовательный тип данных. Если mutable равно true, он также гарантирует, что последовательность ответа является стандартным списком Python.

Изменения

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

autocorrect_location_header = True: Должен ли этот объект ответа исправлять заголовок расположения, чтобы он соответствовал RFC? По умолчанию значение равно true.

Изменения

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

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

Изменения

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

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

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

Изменения

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

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

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

Изменения

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

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

default_mimetype = 'text/plain': тип MIME по умолчанию, если не указан другой.

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

delete_cookie(key, path='/', domain=None)

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

Параметры:	key – ключ (имя) cookie для удаления. path – если cookie ограничен путём, путь должен быть определён здесь. domain – если cookie ограничен доменной зоной, домен должен быть определён здесь.

classmethod force_type(response, environ=None)

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

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

# 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 – объект WSGI-среды.
Возвращает:	объект ответа.

freeze(): Вызовите этот метод, если хотите подготовить объект ответа к сериализации. Это буферизует генератор, если он есть. Также он установит заголовок Content-Length в длину тела.

Изменения

Изменено в версии 0.6: Теперь устанавливается заголовок Content-Length.

classmethod from_app(app, environ, buffered=False)

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

Параметры:	app – WSGI-приложение для выполнения. environ – WSGI-среда для выполнения. buffered – установить в значение `True`, чтобы принудительно включить буферизацию.
Возвращает:	объект ответа.

get_app_iter(environ)

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

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

Изменения

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

Параметры:	environ – WSGI-среда запроса.
Возвращает:	итерируемая последовательность ответа.

get_data(as_text=False)

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

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

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

Изменения

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

get_wsgi_headers(environ)

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

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

Изменения

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

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

Параметры:	environ – WSGI-среда запроса.
Возвращает:	возвращает новый объект `Headers`.

get_wsgi_response(environ)

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

Изменения

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

Параметры:	environ – WSGI-среда запроса.
Возвращает:	кортеж `(app_iter, status, headers)`

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

Изменения

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

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

Изменения

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

is_streamed

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

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

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

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

Изменения

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

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

Изменения

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

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

Устанавливает cookie. Параметры такие же, как в объекте cookie Morsel в стандартной библиотеке Python, но он также принимает данные Юникода.

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

Параметры:

Параметры:	key – ключ (имя) cookie, который нужно установить. value – значение cookie. max_age – должно быть количество секунд, или `None` (по умолчанию), если cookie должен действовать только до окончания сеанса браузера клиента. expires – должен быть объект `datetime` или метка времени Unix. path – ограничивает cookie заданным путём, по умолчанию он охватывает весь домен. domain – если нужно установить cookie для нескольких доменов. Например, `domain=".example.com"` установит cookie, доступный для домена `www.example.com`, `foo.example.com` и т. д. В противном случае cookie будет доступен только для домена, который его установил. secure – Если `True`, cookie будет доступен только через HTTPS httponly – запрещает JavaScript получать доступ к cookie. Это расширение стандарта cookie, и, возможно, не поддерживается всеми браузерами. samesite – Ограничивает область cookie так, что он будет прикреплён только к запросам, если эти запросы являются «одного сайта».

key – ключ (имя) cookie, который нужно установить.
value – значение cookie.
max_age – должно быть количество секунд, или None (по умолчанию), если cookie должен действовать только до окончания сеанса браузера клиента.
expires – должен быть объект datetime или метка времени Unix.
path – ограничивает cookie заданным путём, по умолчанию он охватывает весь домен.
domain – если нужно установить cookie для нескольких доменов. Например, domain=".example.com" установит cookie, доступный для домена www.example.com, foo.example.com и т. д. В противном случае cookie будет доступен только для домена, который его установил.
secure – Если True, cookie будет доступен только через HTTPS
httponly – запрещает JavaScript получать доступ к cookie. Это расширение стандарта cookie, и, возможно, не поддерживается всеми браузерами.
samesite – Ограничивает область cookie так, что он будет прикреплён только к запросам, если эти запросы являются «одного сайта».

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

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

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

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

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

Классы-микшины

Werkzeug также предоставляет вспомогательные микшины для различных функций, связанных с HTTP, таких как теги, контроль кеша, пользовательские агенты и т. д. При наследовании вы можете комбинировать эти классы, чтобы расширить функциональность объекта BaseRequest или BaseResponse объекта. Вот небольшой пример объекта запроса, который анализирует заголовки accept:

from werkzeug.wrappers import AcceptMixin, BaseRequest

class Request(BaseRequest, AcceptMixin):
    pass

Классы Request и Response наследуются от классов BaseRequest и BaseResponse и реализуют все микшины, которые предоставляет Werkzeug:

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

Полностью функциональный объект запроса, реализующий следующие микшины:

AcceptMixin для разбора заголовков accept
ETagRequestMixin для обработки тегов и управления кэшем
UserAgentMixin для интроспекции пользовательского агента
AuthorizationMixin для обработки аутентификации HTTP
CORSRequestMixin для заголовков Cross Origin Resource Sharing
CommonRequestDescriptorsMixin для общих заголовков

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

Полностью функциональный объект ответа, реализующий следующие микшины:

ETagResponseMixin для обработки тегов и управления кэшем
WWWAuthenticateMixin для поддержки аутентификации HTTP
CORSResponseMixin для заголовков Cross Origin Resource Sharing
ResponseStreamMixin для добавления поддержки свойства stream
CommonResponseDescriptorsMixin для различных описателей HTTP

Общие описатели

class werkzeug.wrappers.CommonRequestDescriptorsMixin

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

class werkzeug.wrappers.CommonResponseDescriptorsMixin

Mixin для подклассов BaseResponse. Объекты ответа, которые используют этот класс, автоматически получат описания для нескольких HTTP-заголовков с автоматическим преобразованием типов.

age

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

mimetype: Тип mime без charset и т.д.

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

Changelog

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

retry_after

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

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

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

Поток ответа

class werkzeug.wrappers.ResponseStreamMixin

Mixin для подклассов BaseResponse. Классы, унаследованные от этого миксина, автоматически получат свойство stream, которое предоставляет односторонний интерфейс записи для итерируемого объекта ответа.

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

Accept

class werkzeug.wrappers.AcceptMixin

Mixin для классов с атрибутом environ, чтобы получить все HTTP-заголовки Accept как объекты Accept (или их подклассы).

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

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

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

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

Аутентификация

class werkzeug.wrappers.AuthorizationMixin

Добавляет свойство authorization, которое представляет проанализированное значение заголовка Authorization как объект Authorization.

authorization: Объект Authorization в проанализированном виде.

class werkzeug.wrappers.WWWAuthenticateMixin

Добавляет свойство www_authenticate к объекту ответа.

www_authenticate: Заголовок WWW-Authenticate в проанализированном виде.

CORS

class werkzeug.wrappers.cors.CORSRequestMixin

Mixin для подклассов BaseRequest, добавляющий дескрипторы для заголовков Cross Origin Resource Sharing (CORS).

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

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

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

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

class werkzeug.wrappers.cors.CORSResponseMixin

Mixin для подклассов BaseResponse, добавляющий дескрипторы для заголовков Cross Origin Resource Sharing (CORS).

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

access_control_allow_credentials: Указывает, могут ли браузер и JavaScript-код обмениваться данными. Часть запроса предварительного полёта, указывающая, могут ли использоваться данные в запросе кросс-доменного ресурса.

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

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

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

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

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

ETag

class werkzeug.wrappers.ETagRequestMixin

Добавляет теги сущности и дескрипторы кэша к объекту запроса или объекту с доступной средой WSGI, как environ. Это предоставляет доступ не только к тегам сущности, но и к заголовку управления кэшем.

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

if_match

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

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

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

if_none_match

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

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

if_range

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

Изменения

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

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

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

range

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

Изменения

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

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

class werkzeug.wrappers.ETagResponseMixin

Добавляет дополнительные возможности объекту ответа для обработки etag и кэширования. Этот миксин требует объекта, содержащего как минимум объект headers, реализующего интерфейс словаря, похожий на Headers.

Если вы хотите, чтобы метод freeze() автоматически добавлял etag, вам необходимо добавить этот метод перед базовым классом ответа. Базовый класс ответа по умолчанию этого не делает.

accept_ranges

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

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

Changelog

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

add_etag(overwrite=False, weak=False): Добавить etag для текущего ответа, если его ещё нет.

cache_control: Поле Cache-Control используется для указания директив, которые ОДНОЗНАЧНО должны быть выполнены всеми механизмами кэширования в цепочке запрос/ответ.

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

Changelog

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

freeze(no_etag=False): Вызовите этот метод, если вы хотите подготовить объект ответа для сериализации. Это буферизует генератор, если он есть. Это также устанавливает etag, если no_etag не установлено в True.

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

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

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

Не выполняет никаких действий, если метод запроса в запросе или среде WSGI не GET или HEAD.

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

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

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

Параметры:

Параметры:	request_or_environ – объект запроса или WSGI-среда, используемые для определения условия ответа. accept_ranges – Этот параметр определяет значение заголовка `Accept-Ranges`. Если `False` (значение по умолчанию), заголовок не устанавливается. Если `True`, он будет установлен в `"bytes"`. Если `None`, он будет установлен в `"none"`. Если это строка, будет использовано это значение. complete_length – Будет использоваться только в допустимых запросах с диапазоном. Он установит значение полной длины `Content-Range` и вычислит фактическое значение `Content-Length`. Этот параметр обязателен для успешного завершения запросов с диапазоном.
Возможные исключения:	`RequestedRangeNotSatisfiable` если заголовок `Range` не может быть проанализирован или удовлетворён.

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

Возможные исключения:

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

set_etag(etag, weak=False): Установить etag и перезаписать предыдущее значение, если оно существовало.

User Agent

class werkzeug.wrappers.UserAgentMixin

Добавляет атрибут user_agent в объект запроса, который содержит проанализированный пользовательский агент браузера, вызвавшего запрос, как объект UserAgent.

user_agent: Текущий пользовательский агент.

Дополнительные классы-миксины

Эти миксины не включены в стандартные классы Request и Response. Они обеспечивают дополнительное поведение, которое необходимо включать, создавая собственные подклассы:

class Response(JSONMixin, BaseResponse):
    pass

JSON

class werkzeug.wrappers.json.JSONMixin

Миксин для парсинга data в формате JSON. Может быть добавлен как миксин в классы Request и Response.

Если установлен simplejson, он будет предпочтительнее встроенного модуля Python json.

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

Парсинг data как JSON.

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

Если парсинг завершается ошибкой, вызывается on_json_loading_failed(), и его возвращаемое значение используется как возвращаемое значение.

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

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

json

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

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

json_module

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

Псевдоним _JSONModule

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