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

Объекты запроса и ответа оборачивают среду 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.

Изменено в версии 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: Если существует заголовок переадресации, это список всех 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, который автоматически закроет его.

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

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

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

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

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

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

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

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

classmethod from_values(*args, **kwargs)

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

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

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

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

is_xhr: True, если запрос был инициирован через JavaScript XMLHttpRequest. Это работает только с библиотеками, которые поддерживают заголовок X-Requested-With и устанавливают его в «XMLHttpRequest». Такие библиотеки — prototype, jQuery и Mochikit, а также, вероятно, ещё некоторые.

Устарело начиная с версии 0.13: X-Requested-With не является стандартным и ненадёжен. Вы можете использовать AcceptMixin.accept_mimetypes вместо этого.

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

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

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

max_content_length = None

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

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

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

max_form_memory_size = None

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

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

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

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

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

stream

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

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

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

trusted_hosts = None

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

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

Добавлен в версии 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-ответ при вызове с окружением и вызываемой функцией 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 «текст». Если тип 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 – вызываемая функция 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, IRIs в заголовках расположения и расположения содержимого обрабатываются правильно.

Также начиная с версии 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): Устанавливает новую строку как ответ. Устанавливаемое значение должно быть либо строкой Юникод, либо байтовым объектом. Если установлена строка Юникод, она автоматически кодируется в кодировку ответа (по умолчанию utf-8).

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

status: Код HTTP-состояния

status_code: Код HTTP-состояния как число

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

Werkzeug также предоставляет вспомогательные миксины для различных функций, связанных с HTTP, таких как etags, управление кэшем, пользовательские агенты и т. д. При наследовании вы можете смешивать эти классы, чтобы расширить функциональность объекта 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 для обработки etag и управления кэшем
UserAgentMixin для интроспекции пользовательского агента
AuthorizationMixin для обработки аутентификации HTTP
CommonRequestDescriptorsMixin для общих заголовков

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

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

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

class werkzeug.wrappers.AcceptMixin

Миксин для классов с атрибутом 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.ETagRequestMixin

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

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

if_match

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

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

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

if_none_match

Объект, содержащий все etags в заголовке 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'.

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

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

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

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

Добавлена в версии 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 и переопределить предыдущее значение, если оно было.

class werkzeug.wrappers.ResponseStreamMixin

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

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

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 (также «referrer», хотя название заголовка написано неправильно).

class werkzeug.wrappers.CommonResponseDescriptorsMixin

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

age

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

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

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

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_type: Поле сущностного заголовка Content-Type указывает тип медиа тела сущности, отправленного получателю или, в случае метода HEAD, тип медиа, который был бы отправлен, если бы запрос был GET.

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

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

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

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

mimetype: mimetype (тип содержимого без кодировки и т.д.)

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

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

retry_after

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

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

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

class werkzeug.wrappers.WWWAuthenticateMixin

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

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

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.