Запрос и Ответ

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

import falcon


class Resource(object):

    def on_get(self, req, resp):
        resp.body = '{"message": "Hello world!"}'
        resp.status = falcon.HTTP_200

Запрос

class falcon.Request(env, options=None) [source]

Представляет HTTP-запрос клиента.

Примечание

Request не предназначен для прямого экземпляризации обработчиками ответов.

Именованные аргументы:
Параметры:	env (dict) – Словарь WSGI окружения, переданный сервером. См. также PEP-3333.
	options (dict) – Набор глобальных опций, переданных обработчиком API.

env: dict – Ссылка на WSGI окружение dict , переданное сервером. (См. также PEP-3333.)

context: dict – Словарь для хранения любых данных о запросе, специфичных для приложения (например, объект сессии). Falcon сам не будет взаимодействовать с этим атрибутом после его инициализации.

context_type: class – Классовая переменная, определяющая фабрику или тип для инициализации атрибута context. По умолчанию фреймворк создаст стандартные объекты dict. Однако, вы можете изменить это поведение, создав пользовательский дочерний класс falcon.Request, а затем передав этот новый класс в falcon.API() через параметр request_type.

Примечание

При переопределении context_type с помощью функции-фабрики (в отличие от класса), функция вызывается как метод текущего экземпляра Request. Таким образом, первый аргумент — сам экземпляр Request (self).

scheme: str – Схема URL, используемая для запроса. Либо ‘http’, либо ‘https’.

Примечание

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

forwarded_scheme

str – Исходная схема URL, запрошенная пользователем, если запрос был проксирован. Типичные значения — ‘http’ или ‘https’.

Для определения переданной схемы проверяются следующие заголовки запроса в порядке приоритета:

Forwarded
X-Forwarded-For

Если ни один из этих заголовков недоступен, или если заголовок Forwarded доступен, но не содержит параметра «proto» в первом прыжке, возвращается значение scheme.

(См. также: RFC 7239, Раздел 1)

protocol: str – Устаревший псевдоним для scheme. Будет удален в будущей версии.

method: str – HTTP-метод запроса (например, ‘GET’, ‘POST’ и т.д.)

host: str – Поле заголовка запроса Host

forwarded_host

str – Исходное поле заголовка запроса Host, полученное первым прокси перед сервером приложения.

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

Forwarded
X-Forwarded-Host

Если ни один из вышеперечисленных заголовков недоступен или если заголовок Forwarded доступен, но параметр «host» не включён в первый прыжок, возвращается значение host.

Примечание

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

(См. также: RFC 7239, Раздел 4)

port: int – Порт, используемый для запроса. Если в URI запроса не указан порт, возвращается значение по умолчанию для данной схемы (80 для HTTP и 443 для HTTPS).

netloc: str – Возвращает часть ‘хост:порт’ URL запроса. Порт может быть опущен, если он является значением по умолчанию для схемы URL (80 для HTTP и 443 для HTTPS).

subdomain: str – Самый левый (т.е. самый специфичный) поддомен из имени хоста. Если указано только одно доменное имя, subdomain будет None.

Примечание

Если имя хоста в запросе — IP-адрес, значение subdomain неопределено.

app

str – Начальная часть пути URI запроса, соответствующая объекту приложения, чтобы приложение знало своё виртуальное «местоположение». Это может быть пустая строка, если приложение соответствует «корню» сервера.

(Соответствует переменной окружения «SCRIPT_NAME», определённой в PEP-3333.)

uri: str – Полностью квалифицированный URI для запроса.

url: str – Псевдоним для uri.

forwarded_uri: str – Исходный URI для проксированных запросов. Использует forwarded_scheme и forwarded_host для восстановления исходного URI, запрошенного пользователем.

relative_uri: str – Часть пути и строки запроса URI запроса, без схемы и хоста.

prefix: str – Префикс URI запроса, включая схему, хост и WSGI приложение (если таковое имеется).

forwarded_prefix: str – Префикс исходного URI для проксированных запросов. Использует forwarded_scheme и forwarded_host для восстановления исходного URI.

path: str – Часть пути URI запроса (без строки запроса).

Примечание

req.path может быть изменено методом process_request() middleware для влияния на маршрутизацию.

query_string: str – Часть строки запроса URI запроса, без предшествующего символа ‘?’.

uri_template: str – Шаблон маршрута, который был сопоставлен для этого запроса. Может быть None , если запрос ещё не был маршрутизирован, как в случае с методами middleware process_request() . Также может быть None , если ваше приложение использует пользовательский движок маршрутизации, и движок не предоставляет шаблон URI при разрешении маршрута.

remote_addr

str – IP-адрес ближайшего клиента или прокси к серверу WSGI.

Этот параметр определяется значением REMOTE_ADDR в словаре WSGI окружения. Поскольку этот адрес не получен из HTTP-заголовка, клиенты и прокси не могут его подделать.

Примечание

Если ваше приложение находится за одним или несколькими обратными прокси, вы можете использовать access_route для получения реального IP-адреса клиента.

access_route

list – IP-адрес исходного клиента, а также любые известные адреса прокси, стоящих перед сервером WSGI.

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

Forwarded
X-Forwarded-For
X-Real-IP

Если ни один из этих заголовков недоступен, используется значение remote_addr.

Примечание

Согласно RFC 7239, маршрут доступа может содержать «неизвестные» и замаскированные идентификаторы, помимо IPv4 и IPv6 адресов.

Предупреждение

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

forwarded

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

(См. также: RFC 7239, Раздел 4)

date: дата – Значение заголовка Date, преобразованное в объект datetime. Предполагается, что значение заголовка соответствует RFC 1123.

auth: строка – Значение заголовка Authorization, или None если заголовок отсутствует.

user_agent: строка – Значение заголовка User-Agent, или None если заголовок отсутствует.

referer: строка – Значение заголовка Referer, или None если заголовок отсутствует.

accept: строка – Значение заголовка Accept, или ‘/‘ если заголовок отсутствует.

client_accepts_json: логическое – True если заголовок Accept указывает, что клиент готов принять JSON, в противном случае False.

client_accepts_msgpack: логическое – True если заголовок Accept указывает, что клиент готов принять MessagePack, в противном случае False.

client_accepts_xml: логическое – True если заголовок Accept указывает, что клиент готов принять XML, в противном случае False.

cookies: словарь – Словарь пар имя/значение cookie. (См. также: Получение файлов cookie)

content_type: строка – Значение заголовка Content-Type, или None если заголовок отсутствует.

content_length: целое число – Значение заголовка Content-Length, преобразованное в int, или None если заголовок отсутствует.

stream

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

Поскольку этот объект предоставляется самим сервером WSGI, а не Falcon, его поведение может отличаться в зависимости от способа размещения приложения. Например, попытка прочитать больше байтов, чем ожидается (как определяется заголовком Content-Length), может или не может блокироваться неопределенно долго. Рекомендуется протестировать сервер WSGI, чтобы узнать, как он себя ведет.

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

# Blocks if Content-Length is 0
data = req.stream.read()

Решение достаточно простое, хотя и громоздкое:

# If Content-Length happens to be 0, or the header is
# missing altogether, this will not block.
data = req.stream.read(req.content_length or 0)

В качестве альтернативы, при непосредственном передаче потока потребителю, может потребоваться разветвление значения заголовка Content-Length:

if req.content_length:
    doc = json.load(req.stream)

Для незначительной потери производительности можно использовать bounded_stream, который оборачивает собственный объект ввода WSGI для нормализации его поведения.

Примечание

Если HTML-форма отправляется на API с помощью типа носителя application/x-www-form-urlencoded, и опция auto_parse_form_urlencoded установлена, фреймворк обработает stream для разбора параметров и объединения их с параметрами строки запроса. В этом случае поток будет находиться в состоянии EOF.

bounded_stream

Обёртка, подобная файлу, над stream для нормализации определённых различий между объектами ввода, используемыми различными серверами WSGI. В частности, bounded_stream учитывает ожидаемый размер тела (Content-Length) и никогда не заблокируется при чтении вне пределов, предполагая, что клиент не задерживается при передаче данных на сервер.

Например, следующее не будет блокироваться, если Content-Length равен 0 или заголовок отсутствует:

data = req.bounded_stream.read()

Это также безопасно:

doc = json.load(req.bounded_stream)

expect: строка – Значение заголовка Expect, или None если заголовок отсутствует.

media

объект – Возвращает десериализованную форму потока запроса. При вызове он попытается десериализовать поток запроса, используя заголовок Content-Type, а также обработчики типов носителей, настроенные через falcon.RequestOptions.

См. Тип носителя для получения дополнительной информации об обработке типов носителей.

Предупреждение

Данная операция потребляет поток запроса при первом вызове и кэширует результаты. Последующие вызовы просто извлекают кэшированную версию объекта.

range

кортеж из целых чисел – Двухэлементный tuple парсинг значения заголовка Range.

Два элемента соответствуют начальному и конечному байтовым позициям запрошенного ресурса, включительно. Отрицательные индексы указывают смещение от конца ресурса, где -1 — это последний байт, -2 — второй с конца байт и так далее.

Поддерживаются только непрерывные диапазоны (например, «bytes=0-0,-1» приведет к исключению HTTPBadRequest при обращении к атрибуту).

range_unit: строка – Единица диапазона, полученная из значения заголовка Range, или None если заголовок отсутствует

if_match: строка – Значение заголовка If-Match, или None если заголовок отсутствует.

if_none_match: строка – Значение заголовка If-None-Match, или None если заголовок отсутствует.

if_modified_since: дата – Значение заголовка If-Modified-Since, или None если заголовок отсутствует.

if_unmodified_since: дата – Значение заголовка If-Unmodified-Since, или None если заголовок отсутствует.

if_range: строка – Значение заголовка If-Range, или None если заголовок отсутствует.

headers: словарь – Необработанные HTTP-заголовки из запроса с каноническими именами, разделёнными дефисом. Разбор всех заголовков для создания этого словаря выполняется при первом обращении к этому атрибуту. Этот разбор может быть затратным, поэтому, если вам не нужны все заголовки в этом формате, используйте метод get_header или один из удобных атрибутов, чтобы получить значение для определённого заголовка.

params: словарь – Сопоставление имён параметров строки запроса с их значениями. Если параметр встречается несколько раз в строке запроса, значение, сопоставленное с ключом параметра, будет списком всех значений в порядке их появления.

options: словарь – Набор глобальных опций, переданных обработчиком API.

client_accepts(media_type) [source]

Определяет, принимает ли клиент заданный тип носителя.

Параметры:	media_type (строка) – Тип носителя Интернет для проверки.
Возвращает:	`True` если клиент указал в заголовке Accept, что он принимает указанный тип носителя. В противном случае возвращает `False`.
Тип возвращаемого значения:	логическое

client_prefers(media_types) [source]

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

Параметры:	media_types (итерируемый список строк) – Один или несколько типов интернет-медиа, из которых нужно выбрать предпочтительный тип клиента. Это значение должно быть итерируемым списком строк.
Возвращает:	Предпочтительный тип медиа клиента, на основе заголовка Accept. Возвращает `None` , если клиент не принимает ни один из указанных типов.
Тип возвращаемого значения:	str

context_type: псевдоним dict

get_header(name, required=False, default=None) [source]

Получить значение заданного заголовка в виде строки.

Ключевые аргументы:
Параметры:	name (str) – Название заголовка, регистронезависимое (например, ‘Content-Type’)
	required (bool) – Установите в `True` , чтобы вызвать `HTTPBadRequest` вместо того, чтобы корректно вернуть значение, если заголовок не найден (по умолчанию `False`). default (any) – Значение для возврата, если заголовок не найден (по умолчанию `None`).
Возвращает:	Значение указанного заголовка, если он существует, или значение по умолчанию, если заголовок не найден и не является обязательным.
Тип возвращаемого значения:	str
Возбуждает:	`HTTPBadRequest` – Заголовок не найден в запросе, но был необходим.

get_header_as_datetime(header, required=False, obs_date=False) [source]

Возвращает HTTP-заголовок с значениями HTTP-Date в виде datetime.

Ключевые аргументы:
Параметры:	name (str) – Название заголовка, регистронезависимое (например, ‘Date’)
	required (bool) – Установите в `True` , чтобы вызвать `HTTPBadRequest` вместо того, чтобы корректно вернуть значение, если заголовок не найден (по умолчанию `False`). obs_date (bool) – Поддержка форматов obs-date в соответствии с RFC 7231, например: “Sunday, 06-Nov-94 08:49:37 GMT” (по умолчанию `False`).
Возвращает:	Значение указанного заголовка, если он существует, или `None` , если заголовок не найден и не является обязательным.
Тип возвращаемого значения:	datetime
Возбуждает:	`HTTPBadRequest` – Заголовок не найден в запросе, но был необходим. `HttpInvalidHeader` – Заголовок содержал неправильное/невалидное значение.

get_param(name, required=False, store=None, default=None) [source]

Возвращает необработанное значение параметра строки запроса как строку.

Примечание

Если HTML-форма отправляется в API с помощью типа медиа application/x-www-form-urlencoded, Falcon может автоматически разобрать параметры из тела запроса и объединить их в параметры строки запроса. Чтобы включить эту функциональность, установите auto_parse_form_urlencoded в True через API.req_options.

Если ключ появляется более одного раза в данных формы, одно из значений будет возвращено как строка, но неизвестно какое. Используйте req.get_param_as_list() для получения всех значений.

Примечание

Аналогично тому, как обрабатываются несколько ключей в данных формы, если параметр запроса назначен запятой разделенным списком значений (например, ‘foo=a,b,c’), будет возвращено только одно из этих значений, и неизвестно какое. Используйте req.get_param_as_list() для получения всех значений.

Ключевые аргументы:
Параметры:	name (str) – Имя параметра, чувствительное к регистру (например, ‘sort’).
	required (bool) – Установите в `True` , чтобы вызвать `HTTPBadRequest` вместо возврата `None` , если параметр не найден (по умолчанию `False`). store (dict) – Объект типа `dict`, в котором размещается значение параметра, но только если параметр присутствует. default (any) – Если параметр не найден, возвращает заданное значение вместо None
Возвращает:	Значение параметра как строка, или `None` , если параметр не найден и не является обязательным.
Тип возвращаемого значения:	str
Возбуждает:	`HTTPBadRequest` – Требуемый параметр отсутствует в запросе.

get_param_as_bool(name, required=False, store=None, blank_as_true=False) [source]

Возвращает значение параметра строки запроса как булево.

Поддерживаются следующие строковые представления булевых значений:

TRUE_STRINGS = ('true', 'True', 'yes', '1', 'on')
FALSE_STRINGS = ('false', 'False', 'no', '0', 'off')

Ключевые аргументы:
Параметры:	name (str) – Имя параметра, чувствительное к регистру (например, ‘detailed’).
	required (bool) – Установите в `True` для повышения `HTTPBadRequest`, вместо возвращения `None`, если параметр не найден или не распознаётся как строковое представление булева значения (по умолчанию `False`). store (dict) – Объект типа `dict`, в который будет помещено значение параметра, но только если параметр найден (по умолчанию `None`). blank_as_true (bool) – Если `True`, пустая строка будет интерпретирована как `True` (по умолчанию `False`). Обычно пустые строки игнорируются; если вы хотите распознавать такие параметры, вы должны установить параметр `keep_blank_qs_values` запроса в `True`. Параметры запроса устанавливаются глобально для каждого экземпляра `falcon.API` через атрибут `req_options`.
Возвращает:	Значение параметра, если он найден и может быть преобразован в `bool`. Если параметр не найден, возвращает `None`, за исключением случаев, когда required установлено в `True`.
Тип возвращаемого значения:	bool
Возбуждает:	`HTTPBadRequest` – Требуемый параметр отсутствует в запросе.

get_param_as_date(name, format_string='%Y-%m-%d', required=False, store=None) [source]

Возвращает значение параметра строки запроса как дату.

Ключевые аргументы:
Параметры:	name (str) – Имя параметра, чувствительное к регистру (например, ‘ids’).
	format_string (str) – Строка, используемая для разбора значения параметра в дату. Поддерживаются любые форматы, распознаваемые функцией strptime() (по умолчанию `"%Y-%m-%d"`). required (bool) – Установите в `True` для повышения `HTTPBadRequest` вместо возвращения `None` при отсутствии параметра (по умолчанию `False`). store (dict) – Объект типа `dict`, в который будет помещено значение параметра, но только если параметр найден (по умолчанию `None`).
Возвращает:	Значение параметра, если он найден и может быть преобразован в `date` в соответствии с предоставленной строкой формата. Если параметр не найден, возвращает `None`, за исключением случаев, когда required установлено в `True`.
Тип возвращаемого значения:	datetime.date
Возбуждает:	`HTTPBadRequest` – Требуемый параметр отсутствует в запросе. `HTTPInvalidParam` – Функция преобразования подняла исключение `ValueError`.

get_param_as_datetime(name, format_string='%Y-%m-%dT%H:%M:%SZ', required=False, store=None) [source]

Возвращает значение параметра строки запроса как datetime.

Ключевые аргументы:
Параметры:	name (str) – Имя параметра, чувствительное к регистру (например, ‘ids’).
	format_string (str) – Строка, используемая для разбора значения параметра в datetime. Поддерживаются любые форматы, распознаваемые функцией strptime() (по умолчанию `'%Y-%m-%dT%H:%M:%SZ'`). required (bool) – Установите в `True` для повышения `HTTPBadRequest` вместо возвращения `None` при отсутствии параметра (по умолчанию `False`). store (dict) – Объект типа `dict`, в который будет помещено значение параметра, но только если параметр найден (по умолчанию `None`).
Возвращает:	Значение параметра, если он найден и может быть преобразован в `datetime` в соответствии с предоставленной строкой формата. Если параметр не найден, возвращает `None`, за исключением случаев, когда required установлено в `True`.
Тип возвращаемого значения:	datetime.datetime
Возбуждает:	`HTTPBadRequest` – Требуемый параметр отсутствует в запросе. `HTTPInvalidParam` – Функция преобразования подняла исключение `ValueError`.

get_param_as_dict(name, required=False, store=None) [source]

Возвращает значение параметра строки запроса как словарь.

Принимает значение в формате JSON, парсит и возвращает его как словарь.

Ключевые аргументы:
Параметры:	name (str) – Имя параметра, чувствительное к регистру (например, ‘payload’).
	required (bool) – Установите в `True` для повышения `HTTPBadRequest` вместо возвращения `None` при отсутствии параметра (по умолчанию `False`). store (dict) – Объект типа `dict`, в который будет помещено значение параметра, но только если параметр найден (по умолчанию `None`).
Возвращает:	Значение параметра, если он найден. В противном случае, возвращает `None`, за исключением случаев, когда required установлено в `True`.
Тип возвращаемого значения:	dict
Возбуждает:	`HTTPBadRequest` – Требуемый параметр отсутствует в запросе. `HTTPInvalidParam` – Значение параметра не может быть обработано как JSON.

get_param_as_int(name, required=False, min=None, max=None, store=None) [source]

Возвращает значение параметра строки запроса как целое число.

Ключевые аргументы:
Параметры:	name (str) – Имя параметра, чувствительное к регистру (например, ‘limit’).
	required (bool) – Установите в `True` для повышения `HTTPBadRequest` вместо возвращения `None`, когда параметр не найден или не является целым числом (по умолчанию `False`). min (int) – Установите минимальное значение, разрешённое для этого параметра. Если параметр найден и меньше min, генерируется `HTTPError`. max (int) – Установите максимальное значение, разрешённое для этого параметра. Если параметр найден и его значение больше max, генерируется `HTTPError`. store (dict) – Объект типа `dict`, в который помещается значение параметра, но только если параметр найден (по умолчанию `None`).
Возвращает:	Значение параметра, если он найден и может быть преобразован в целое число. Если параметр не найден, возвращается `None`, если `required` не равно `True`.
Тип возвращаемого значения:	int

Исключения

HTTPBadRequest: Параметр не найден в запросе,: даже если он был необходим. Также генерируется, если значение параметра выходит за заданный интервал, т.е., значение должно быть в интервале: min <= value <= max, чтобы избежать ошибки.

get_param_as_list(name, transform=None, required=False, store=None) [source]

Возвращает значение параметра строки запроса в виде списка.

Элементы списка должны быть разделены запятыми или должны быть предоставлены как несколько экземпляров одного и того же параметра в строке запроса по типу application/x-www-form-urlencoded.

Ключевые аргументы:
Параметры:	name (str) – Имя параметра, чувствительное к регистру (например, ‘ids’).
	transform (callable) – Необязательная функция преобразования, которая принимает каждый элемент списка как `str` и возвращает преобразованный элемент для включения в список, который будет возвращен. Например, передача `int` преобразует элементы списка в числа. required (bool) – Установите в `True` для повышения `HTTPBadRequest` вместо возвращения `None` при отсутствии параметра (по умолчанию `False`). store (dict) – Объект типа `dict`, в который помещается значение параметра, но только если параметр найден (по умолчанию `None`).
Возвращает:	Значение параметра, если он найден. В противном случае возвращается `None`, если required не True. Пустые элементы списка будут отброшены. Например, следующие строки запроса приведут к `[‘1’, ‘3’]`: things=1,,3 things=1&things=&things=3
Тип возвращаемого значения:	list
Исключения:	`HTTPBadRequest` – Требуемый параметр отсутствует в запросе. `HTTPInvalidParam` – Функция преобразования подняла исключение `ValueError`.

log_error(message) [source]

Записывает сообщение об ошибке в журнал сервера.

Добавляет отметку времени и информацию о запросе к сообщению и записывает результат в поток ошибок WSGI-сервера (wsgi.error).

Параметры:	message (str или unicode) – Описание проблемы. В Python 2 экземпляры `unicode` будут преобразованы в UTF-8.

class falcon.Forwarded [source]

Представляет собой обработанное поле заголовка Forwarded.

(См. также: RFC 7239, Раздел 4)

src: str – Значение параметра «for», или None если параметр отсутствует. Определяет узел, который отправляет запрос прокси.

dest: str – Значение параметра «by», или None если параметр отсутствует. Определяет клиентский интерфейс прокси.

host: str – Значение параметра «host», или None если параметр отсутствует. Предоставляет значение поля заголовка хоста, полученного прокси.

scheme: str – Значение параметра «proto», или None если параметр отсутствует. Указывает протокол, который использовался для отправки запроса прокси.

Ответ

class falcon.Response(options=None) [source]

Представляет HTTP-ответ на запрос клиента.

Примечание

Response не предназначен для непосредственного создания отвечателями.

Ключевые аргументы:
	options (dict) – Набор глобальных опций, переданных обработчиком API.

status

str – Строка HTTP-статуса (например, «200 OK»). Falcon требует полной строки статуса, а не только кода (например, 200). Такой дизайн делает фреймворк более эффективным, поскольку ему не нужно выполнять преобразование или поиск при составлении WSGI-ответа.

Если не указано явно, статус по умолчанию «200 OK».

Примечание

Falcon предоставляет ряд констант для распространённых кодов статуса. Все они начинаются с префикса HTTP_, как в: falcon.HTTP_204.

media

object – Сериализуемый объект, поддерживаемый обработчиками медиа, настроенными через falcon.RequestOptions.

См. Медиа для получения дополнительной информации об обработке медиа.

body

str или unicode – Строка, представляющая содержимое ответа.

Если задано значение типа Unicode (unicode в Python 2 или str в Python 3), Falcon закодирует текст как UTF-8 в ответе. Если содержимое уже строка байтов, используйте атрибут data (он быстрее).

data

bytes – Строка байтов, представляющая содержимое ответа.

Используйте этот атрибут вместо body, когда ваше содержимое уже является строкой байтов (str или bytes в Python 2 или просто bytes в Python 3). Смотрите также примечание ниже.

Примечание

В Python 2.x, если ваше содержимое имеет тип str, использование атрибута data вместо body является наиболее эффективным подходом. Однако, если ваш текст имеет тип unicode, вам потребуется использовать атрибут body.

В Python 3.x, с другой стороны, тип 2.x str можно считать заменённым на то, что раньше было типом unicode, и поэтому вы всегда должны использовать атрибут body для строк, чтобы гарантировать, что символы Юникода должным образом закодированы в HTTP-ответе.

stream: Или объект, похожий на файл, с методом read(), который принимает необязательный аргумент размера и возвращает блок байтов, или итерируемый объект, представляющий содержимое ответа, и возвращающий блоки в виде строк байтов. Falcon будет использовать wsgi.file_wrapper, если он предоставлен WSGI-сервером, для эффективной обработки объектов, похожих на файлы.

stream_len: int – Ожидаемая длина stream. Если stream задано, но stream_len нет, Falcon не будет передавать заголовок Content-Length WSGI-серверу. В результате сервер может выбрать использование кодирования блоками или один из других стратегий, предложенных PEP-3333.

context: dict – Словарь для хранения любых данных об ответе, специфичных для вашего приложения. Сам Falcon не будет взаимодействовать с этим атрибутом после его инициализации.

context_type: class – Классовая переменная, определяющая фабрику или тип, используемый для инициализации атрибута context. По умолчанию фреймворк будет создавать стандартные объекты dict. Однако вы можете изменить это поведение, создав пользовательский дочерний класс falcon.Response, а затем передав этот новый класс в falcon.API() через параметр response_type.

Примечание

При переопределении context_type функцией-фабрикой (вместо класса), функция вызывается как метод текущего экземпляра Response. Поэтому первым аргументом является сам экземпляр Response (self).

options: dict – Набор глобальных опций, переданных обработчиком API.

accept_ranges

Установите заголовок Accept-Ranges.

Заголовок Accept-Ranges указывает клиенту, какие единицы диапазонов поддерживаются (например, «bytes») для целевого ресурса.

Если запросы диапазонов не поддерживаются для целевого ресурса, заголовок может быть установлен на «none», чтобы проинформировать клиента не пытаться выполнять такие запросы.

Примечание

«none» — это буквальная строка, а не встроенный тип Python None.

add_link(target, rel, title=None, title_star=None, anchor=None, hreflang=None, type_hint=None) [source]

Добавить заголовок ссылки в ответ.

(См. также: RFC 5988, Раздел 1)

Примечание

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

Примечание

Так называемые элементы «link-extension», определенные в RFC 5988, пока не поддерживаются. См. также вопрос #288.

Параметры:

Параметры:	target (str) – Целевой IRI для ресурса, идентифицированного ссылкой. Будет преобразован в URI, если необходимо, согласно RFC 3987, Раздел 3.1. rel (str) – Тип отношения ссылки, такой как «next» или «bookmark». (См. также: http://www.iana.org/assignments/link-relations/link-relations.xhtml)
Ключевые аргументы:
	title (str) – Читабельное для человека обозначение назначения ссылки (по умолчанию `None`). Если заголовок содержит не-ASCII символы, вам необходимо использовать `title_star` или предоставить как версию US-ASCII, используя `title`, и версию Юникод, используя `title_star`. title_star (tuple of str) – Локализованный заголовок, описывающий пункт назначения ссылки (по умолчанию `None`). Значение должно быть кортежем из двух элементов (language-tag, text), где language-tag — стандартный идентификатор языка, как определено в RFC 5646, Раздел 2.1, а text — строка Юникод. Примечание language-tag может быть пустой строкой, в этом случае клиент предположит язык из общего контекста текущего запроса. Примечание text всегда будет закодирован в UTF-8. Если строка содержит не-ASCII символы, она должна быть передана как строка типа `unicode` (требуется префикс «u» в Python 2). anchor (str) – Переопределить контекстный IRI другим URI (по умолчанию None). По умолчанию контекстный IRI для ссылки — это просто IRI запрашиваемого ресурса. Переданное значение может быть относительным URI. hreflang (str or iterable) – Либо один language-tag, либо `list` или `tuple` таких тегов, чтобы дать подсказку клиенту о языке результата перехода по ссылке. Список тегов может быть указан, чтобы указать клиенту, что целевой ресурс доступен на нескольких языках. type_hint (str) – Предоставляет подсказку о типе медиа результата дериферирования ссылки (по умолчанию `None`). Как указано в RFC 5988, это только подсказка и не переопределяет заголовок Content-Type, возвращаемый при переходе по ссылке.

target (str) – Целевой IRI для ресурса, идентифицированного ссылкой. Будет преобразован в URI, если необходимо, согласно RFC 3987, Раздел 3.1.
rel (str) –
Тип отношения ссылки, такой как «next» или «bookmark».

(См. также: http://www.iana.org/assignments/link-relations/link-relations.xhtml)

Ключевые аргументы:

title (str) – Читабельное для человека обозначение назначения ссылки (по умолчанию None). Если заголовок содержит не-ASCII символы, вам необходимо использовать title_star или предоставить как версию US-ASCII, используя title, и версию Юникод, используя title_star.
title_star (tuple of str) –
Локализованный заголовок, описывающий пункт назначения ссылки (по умолчанию None). Значение должно быть кортежем из двух элементов (language-tag, text), где language-tag — стандартный идентификатор языка, как определено в RFC 5646, Раздел 2.1, а text — строка Юникод.

Примечание

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

Примечание

text всегда будет закодирован в UTF-8. Если строка содержит не-ASCII символы, она должна быть передана как строка типа unicode (требуется префикс «u» в Python 2).
anchor (str) – Переопределить контекстный IRI другим URI (по умолчанию None). По умолчанию контекстный IRI для ссылки — это просто IRI запрашиваемого ресурса. Переданное значение может быть относительным URI.
hreflang (str or iterable) – Либо один language-tag, либо list или tuple таких тегов, чтобы дать подсказку клиенту о языке результата перехода по ссылке. Список тегов может быть указан, чтобы указать клиенту, что целевой ресурс доступен на нескольких языках.
type_hint (str) – Предоставляет подсказку о типе медиа результата дериферирования ссылки (по умолчанию None). Как указано в RFC 5988, это только подсказка и не переопределяет заголовок Content-Type, возвращаемый при переходе по ссылке.

append_header(name, value) [source]

Установите или добавьте заголовок для этого ответа.

Предупреждение

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

Предупреждение

Для установки файлов cookie см. set_cookie()

Параметры:

Параметры:	name (str) – Имя заголовка (регистронезависимое). Ограничения, указанные ниже для значения заголовка, также применяются здесь. value (str) – Значение заголовка. Должно быть типа `str` или `StringType` и содержать только символы US-ASCII. В Python 2.x также принимается тип `unicode`, хотя такие строки также ограничены символами US-ASCII.

name (str) – Имя заголовка (регистронезависимое). Ограничения, указанные ниже для значения заголовка, также применяются здесь.
value (str) – Значение заголовка. Должно быть типа str или StringType и содержать только символы US-ASCII. В Python 2.x также принимается тип unicode, хотя такие строки также ограничены символами US-ASCII.

cache_control

Установите заголовок Cache-Control.

Используется для установки списка директив кеширования, которые будут использованы в качестве значения заголовка Cache-Control. Список будет соединён запятыми и пробелами для получения значения заголовка.

content_location

Установите заголовок Content-Location.

Это значение будет закодировано в URI в соответствии с RFC 3986. Если устанавливаемое значение уже закодировано в URI, оно должно быть предварительно декодировано, или заголовок должен быть установлен вручную с помощью метода set_header.

content_range

Кортеж для использования при построении значения заголовка Content-Range.

Кортеж имеет вид (начало, конец, длина, [единица]), где начало и конец обозначают диапазон (включительно), а длина — общую длину или «*», если неизвестна. Вы можете передавать значения int для этих чисел (нет необходимости предварительно преобразовывать их в str). Необязательное значение единица описывает единицу диапазона и по умолчанию равно «байты»

Примечание

Вам необходимо использовать альтернативную форму «байты */1234» только для ответов, использующих статус «416 Range Not Satisfiable». В этом случае поднятие falcon.HTTPRangeNotSatisfiable сделает всё правильно.

(См. также: RFC 7233, Раздел 4.2)

content_type

Устанавливает заголовок Content-Type.

Модуль falcon предоставляет ряд констант для общих типов медиа, включая falcon.MEDIA_JSON, falcon.MEDIA_MSGPACK, falcon.MEDIA_YAML, falcon.MEDIA_XML, falcon.MEDIA_HTML, falcon.MEDIA_JS, falcon.MEDIA_TEXT, falcon.MEDIA_JPEG, falcon.MEDIA_PNG, и falcon.MEDIA_GIF.

context_type: Псевдоним dict

delete_header(name) [source]

Удалить заголовок для этого ответа.

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

Параметры:	name (str) – Имя заголовка (регистронезависимое). Должно быть типа `str` или `StringType` и содержать только символы US-ASCII. В Python 2.x также принимается тип `unicode`, хотя такие строки также ограничены символами US-ASCII.

etag: Установите заголовок ETag.

get_header(name) [source]

Получить строковое значение заголовка в сыром виде.

Параметры:	name (str) – Имя заголовка, регистронезависимое. Должно быть типа `str` или `StringType`, и на платформах с использованием широких символов могут использоваться только символьные значения от 0x00 до 0xFF.
Возвращает:	Значение заголовка, если установлен, в противном случае `None`.
Тип возвращаемого значения:	str

last_modified: Установите заголовок Last-Modified. Установите экземпляр datetime (UTC).

Примечание

Falcon отформатирует datetime в строку даты HTTP.

location

Установите заголовок Location.

retry_after

Установите заголовок Retry-After.

Ожидаемое значение — целое число секунд, используемое в качестве значения заголовка. Синтаксис HTTP-даты не поддерживается.

END_OF_DOCUMENT_MARKER

set_cookie(name, value, expires=None, max_age=None, domain=None, path=None, secure=None, http_only=True) [source]

Установить куки в ответе.

Примечание

Этот метод можно вызывать несколько раз, чтобы добавить один или несколько куки в ответ.

См. также

Чтобы узнать больше о настройке куки, см. Настройка куки. Параметры, перечисленные ниже, соответствуют параметрам, определённым в RFC 6265.

Ключевые аргументы:
Параметры:	name (str) – Имя куки value (str) – Значение куки
	expires (datetime) – Указывает, когда куки должно истечь. По умолчанию куки истекает при выходе пользователя из браузера. (См. также: RFC 6265, Раздел 4.1.2.1) max_age (int) – Определяет срок действия куки в секундах. По умолчанию куки истекает при выходе пользователя из браузера. Если оба `max_age` и `expires` установлены, пользовательский агент игнорирует последнее. Примечание Попытка приведения к типу `int` выполняется, если задано `float` или `str`. (См. также: RFC 6265, Раздел 4.1.2.2) domain (str) – Ограничивает куки определенным доменом и любыми его поддоменами. По умолчанию пользовательский агент вернёт куки только исходному серверу. При переопределении этого поведения, указанный домен должен включать исходный сервер. В противном случае пользовательский агент отклонит куки. (См. также: RFC 6265, Раздел 4.1.2.3) path (str) – Ограничивает куки указанным путем и любыми подкаталогами по этому пути (символ «/» интерпретируется как разделитель каталогов). Если куки не указывает путь, пользовательский агент по умолчанию использует путь запрошенного URI. Предупреждение Интерфейсы пользовательских агентов не всегда изолируют куки по пути, поэтому это неэффективное средство защиты. (См. также: RFC 6265, Раздел 4.1.2.4) secure (bool) – Инструктирует клиент возвращать куки только в последующих запросах, если они отправляются по HTTPS (по умолчанию: `True`). Это предотвращает чтение злоумышленниками конфиденциальных данных куки. Примечание Значение по умолчанию для этого аргумента обычно `True`, но может быть изменено настройкой `secure_cookies_by_default` через `API.resp_options`. Предупреждение Для того чтобы атрибут куки `secure` был эффективным, ваше приложение должно использовать HTTPS. (См. также: RFC 6265, Раздел 4.1.2.5) http_only (bool) – Инструктирует клиент передавать куки только в нескриптовых HTTP-запросах (по умолчанию: `True`). Это призвано снизить риски XSS атак. (См. также: RFC 6265, Раздел 4.1.2.6)
Возбуждает:	`KeyError` – `name` - некорректное имя куки. `ValueError` – `value` - некорректное значение куки.

set_header(name, value) [source]

Установить заголовок ответа.

Предупреждение

Вызов этого метода перезаписывает существующее значение, если оно есть.

Предупреждение

Для установки куки используйте set_cookie().

Параметры:

Параметры:	name (str) – Имя заголовка (регистронезависимое). Применяются те же ограничения к значению заголовка, что указаны ниже. value (str) – Значение заголовка. Должно быть типа `str` или `StringType` и содержать только символы US-ASCII. В Python 2.x также поддерживается тип `unicode`, но такие строки также ограничены символами US-ASCII.

name (str) – Имя заголовка (регистронезависимое). Применяются те же ограничения к значению заголовка, что указаны ниже.
value (str) – Значение заголовка. Должно быть типа str или StringType и содержать только символы US-ASCII. В Python 2.x также поддерживается тип unicode, но такие строки также ограничены символами US-ASCII.

set_headers(headers) [source]

Установить несколько заголовков одновременно.

Предупреждение

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

Параметры:

Параметры:	headers (dict или list) – Словарь имён и значений заголовков для установки или список кортежей (name, value). И name, и value должны быть типа `str` или `StringType` и содержать только символы US-ASCII. В Python 2.x также поддерживается тип `unicode`, но такие строки также ограничены символами US-ASCII. Примечание Falcon может обрабатывать список кортежей немного быстрее, чем словарь.
Возбуждает:	`ValueError` – `headers` не был `dict` или списком кортежей `list` из `tuple`.

headers (dict или list) –

Словарь имён и значений заголовков для установки или список кортежей (name, value). И name, и value должны быть типа str или StringType и содержать только символы US-ASCII. В Python 2.x также поддерживается тип unicode, но такие строки также ограничены символами US-ASCII.

Примечание

Falcon может обрабатывать список кортежей немного быстрее, чем словарь.

Возбуждает: ValueError – headers не был dict или списком кортежей list из tuple.

set_stream(stream, stream_len) [source]

Удобный метод для установки как stream, так и stream_len.

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

Примечание

Если длина потока неизвестна, вы можете установить stream напрямую и игнорировать stream_len. В этом случае сервер WSGI может выбрать использование кодирования с чанками или другие стратегии, предложенные в PEP-3333.

unset_cookie(name) [source]

Удалить куки из ответа

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

Предупреждение

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

vary

Значение для использования в заголовке Vary.

Установите это свойство в итерируемый объект имён заголовков. Для одного звёздочки или значения поля, просто передайте одноэлементный list или tuple.

Поле заголовка «Vary» в ответе описывает, какие части сообщения запроса, помимо метода, поля заголовка Host и целевого запроса, могут повлиять на процесс обработки исходного сервера для выбора и представления этого ответа. Значение состоит либо из одной звёздочки («*»), либо из списка имён полей заголовков (регистр не учитывается).

(См. также: RFC 7231, Раздел 7.1.4)

© 2012–2016 by Rackspace Hosting, Inc. and other contributors
Licensed under the Apache License, Version 2.0.
https://falcon.readthedocs.io/en/1.3.0/api/request_and_response.html