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

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

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

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

Тип:	dict

context

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

Примечание

Новое в версии 2.0: значение по умолчанию context_type (см. ниже) было изменено с dict на базовый класс, и предпочтительный способ передачи данных, специфичных для запроса, теперь — установка атрибутов непосредственно на объект context, например:

req.context.role = 'trial'
req.context.user = 'guest'

Тип:	object

context_type

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

Примечание

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

Тип:	class

scheme

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

Примечание

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

Тип:	str

forwarded_scheme

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

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

Forwarded
X-Forwarded-For

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

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

Тип:	str

method

Запрошенный HTTP-метод (например, ‘GET’, ‘POST’ и т. д.)

Тип:	str

host

Поле заголовка запроса Host

Тип:	str

forwarded_host

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

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

Forwarded
X-Forwarded-Host

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

Примечание

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

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

Тип:	str

port

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

Тип:	int

netloc

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

Тип:	str

subdomain

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

Примечание

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

Тип:	str

app

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

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

Тип:	str

uri

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

Тип:	str

url

Псевдоним для uri.

Тип:	str

forwarded_uri

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

Тип:	str

relative_uri

Часть URI запроса, содержащая путь и строку запроса, без схемы и хоста.

Тип:	str

prefix

Префикс URI запроса, включающий схему, хост и WSGI-приложение (если есть).

Тип:	str

forwarded_prefix

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

Тип:	str

path

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

Примечание

req.path может быть изменено методом process_request() промежуточного ПО для влияния на маршрутизацию. Если исходный путь запроса был закодирован в URL, он будет декодирован перед возвратом этого атрибута. Если это атрибут используется приложением для любых запросов вверх по потоку, любые символы, не являющиеся безопасными в URL, в пути должны быть закодированы в URL обратно перед выполнением запроса.

Тип:	str

query_string

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

Тип:	str

uri_template

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

Тип:	str

remote_addr

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

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

Примечание

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

Тип:	str

access_route

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

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

Forwarded
X-Forwarded-For
X-Real-IP

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

Примечание

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

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

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

Тип:	list

forwarded

Значение заголовка Forwarded, как обработанный список объектов falcon.Forwarded, или None если заголовок отсутствует. Если значение заголовка некорректно, Falcon сделает все возможное для его обработки.

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

Тип:	list

date

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

Тип:	datetime

auth

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

Тип:	str

user_agent

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

Тип:	str

referer

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

Тип:	str

accept

Значение заголовка Accept, или ‘*/*’ если заголовок отсутствует.

Тип:	str

client_accepts_json

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

Тип:	bool

client_accepts_msgpack

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

Тип:	bool

client_accepts_xml

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

Тип:	bool

cookies

Словарь пар имя/значение cookie. Возвращаемый объект следует рассматривать как только для чтения, чтобы избежать непреднамеренных побочных эффектов. Если cookie появляется в запросе более одного раза, доступно будет только первое встреченное значение.

См. также: get_cookie_values()

Тип:	dict

content_type

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

Тип:	str

content_length

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

Тип:	int

stream

Объект входного потока типа «файл» для чтения тела запроса, если таковое имеется. Этот объект предоставляет прямой доступ к потоку данных сервера и не допускает поиска (seek). Чтобы избежать непреднамеренных побочных эффектов и предоставить максимальную гибкость приложению, 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 по методу POST с типом носителя application/x-www-form-urlencoded, и опция auto_parse_form_urlencoded установлена, фреймворк прочитает stream для разбора параметров и объединения их в параметры строки запроса. В этом случае поток будет находиться в конце файла (EOF).

bounded_stream

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

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

data = req.bounded_stream.read()

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

doc = json.load(req.bounded_stream)

expect

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

Тип:	str

media

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

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

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

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

Тип:	object

range

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

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

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

Тип:	кортеж int

range_unit

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

Тип:	str

if_match

Значение заголовка If-Match, в виде обработанного списка объектов falcon.ETag, или None если заголовок отсутствует или его значение пустое.

Этот атрибут предоставляет список всех entity-tags в заголовке, как сильных, так и слабых, в том же порядке, что и в заголовке.

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

Тип:	список

if_none_match

Значение заголовка If-None-Match, в виде обработанного списка объектов falcon.ETag, или None если заголовок отсутствует или его значение пустое.

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

Тип:	список

if_modified_since

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

Тип:	datetime

if_unmodified_since

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

Тип:	datetime

if_range

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

Тип:	str

headers

Необработанные HTTP-заголовки из запроса с каноническими именами через дефис. Разбор всех заголовков для создания этого словаря выполняется при первом обращении к этому атрибуту, и возвращаемый объект должен рассматриваться как только для чтения. Обратите внимание, что этот разбор может быть дорогостоящим, поэтому, если вам не нужны все заголовки в этом формате, используйте метод get_header() или один из удобных атрибутов, чтобы получить значение для определенного заголовка.

Тип:	dict

params

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

Тип:	dict

options

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

Тип:	dict

client_accepts(media_type) [source]

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

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

client_prefers(media_types) [source]

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

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

context_type: псевдоним falcon.util.structures.Context

get_cookie_values(name) [source]

Возвращает все значения, указанные в заголовке Cookie для указанного cookie.

(См. также: Получение файлов cookie)

Параметры:	name (str) – Имя cookie, регистрозависимое.
Возвращает:	Отсортированный список всех значений, указанных в заголовке Cookie для указанного cookie, или `None` если cookie не был включён в запрос. Если cookie указан более одного раза в заголовке, возвращаемый список значений сохранит порядок отдельных `cookie-pair` в заголовке.
Тип возвращаемого значения:	list

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-датами как 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.

Примечание

Аналогично тому, как обрабатываются несколько ключей в данных формы, если параметру строки запроса присвоено значение в виде списка значений, разделенных запятыми (например, foo=a,b,c), будет возвращено только одно из этих значений, и неизвестно, какое именно. Используйте 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=True, default=None) [source]

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

Этот метод рассматривает параметры без значений как флаги. По умолчанию, если для параметра в строке запроса не указано значение, считается и возвращается True. Если параметр отсутствует вообще, возвращается None, как и в других методах get_param_*(), которые легко обрабатываются вызывающей стороной как ложные, по мере необходимости.

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

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` при наличии такого параметра и `False` в противном случае. Чтобы потребовать от клиента явно указать истинное значение, передайте `blank_as_true=False` для возврата `False` при отсутствии значения в строке запроса. default (any) – Если параметр не найден, возвращает это значение вместо `None`.
Возвращает:	Значение параметра, если он найден и может быть преобразован в `bool`. Если параметр не найден, возвращает `None` , если `required` не равно `True`.
Тип возвращаемого значения:	bool
Возбуждает:	`HTTPBadRequest` – Обязательный параметр отсутствует в запросе или не может быть преобразован в `bool`.

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

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

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

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

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

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

get_param_as_float(name, required=False, min_value=None, max_value=None, store=None, default=None) [source]

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

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

Возбуждает исключения

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

get_param_as_int(name, required=False, min_value=None, max_value=None, store=None, default=None) [source]

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

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

Возбуждает исключения

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

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

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

Принимая JSON-значение, декодирует его в соответствующий тип Python, (например, dict, list, str, int, bool, и т.д.)

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

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

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

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

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

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

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

Значение для преобразования должно соответствовать стандартному представлению строки UUID в соответствии с RFC 4122. Например, следующие строки являются допустимыми:

# Lowercase
'64be949b-3433-4d36-a4a8-9f19d352fee8'

# Uppercase
'BE71ECAA-F719-4D42-87FD-32613C2EEB60'

# Mixed
'81c8155C-D6de-443B-9495-39Fa8FB239b5'

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

Возбуждает

HTTPBadRequest: Параметр не был найден в запросе, хотя: он должен был там быть, или он был найден, но не мог быть преобразован в UUID.

has_param(name) [source]

Определяет, существует ли параметр строки запроса.

Параметры:	name (str) – Имя параметра, чувствительное к регистру (например, ‘sort’).
Возвращает:	`True` если параметр найден, или `False` если параметр не найден.
Тип возвращаемого значения:	bool

log_error(message) [source]

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

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

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

class falcon.Forwarded [source]

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

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

src

Значение параметра “for”, или None если параметр отсутствует. Определяет узел, выполнивший запрос к прокси.

Тип:	str

dest

Значение параметра “by”, или None если параметр отсутствует. Определяет интерфейс прокси, обращённый к клиенту.

Тип:	str

host

Значение параметра “host”, или None если параметр отсутствует. Предоставляет поле заголовка запроса “host”, полученное прокси.

Тип:	str

scheme

Значение параметра “proto”, или None если параметр отсутствует. Указывает протокол, используемый для запроса к прокси.

Тип:	str

Ответ

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

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

Примечание

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

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

status

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

Если не задано явно, статус по умолчанию — ‘200 OK’.

Примечание

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

Тип:	str

media

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

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

Тип:	object

body

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

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

Тип:	str или unicode

data

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

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

Примечание

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

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

Тип:	bytes

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

Примечание

Если поток установлен на итерируемый объект, требующий очистки ресурсов, он может реализовать метод close() для этого. Метод close() будет вызван по завершении запроса.

stream_len

Устаревший псевдоним для content_length.

Тип:	int

context

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

Тип:	dict

context

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

Примечание

Новое в 2.0: значение по умолчанию context_type (см. ниже) было изменено со словаря на чистый класс, и предпочтительный способ передачи данных, специфичных для ответа, — это установка атрибутов непосредственно в объекте context, например:

resp.context.cache_strategy = 'lru'

Тип:	object

context_type

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

Примечание

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

Тип:	класс

options

Набор глобальных параметров, переданных от обработчика API.

Тип:	dict

headers

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

Тип:	dict

complete

Устанавливается в True внутри метода middleware для сигнализации фреймворку о том, что обработка запроса должна быть прервана (см. также Middleware).

Тип:	bool

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, разделенных запятыми.

Примечание

Так называемые элементы «расширения ссылок», определенные в 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 вместо title, или предоставить как версию US-ASCII, так и версию Unicode, используя title_star.
title_star (tuple of str) –
Локализованный заголовок, описывающий целевой адрес ссылки (по умолчанию None). Значение должно быть кортежем из двух элементов (языковой тег, текст), где языковой тег — это стандартный идентификатор языка, определенный в RFC 5646, Раздел 2.1, а текст — строка Unicode.

Примечание

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

Примечание

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

append_header(name, value) [source]

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

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

Примечание

Хотя этот метод можно использовать для эффективного добавления необработанных заголовков Set-Cookie в ответ, вы можете найти set_cookie() более удобным.

Параметры:

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

cache_control

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

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

content_length

Установить заголовок Content-Length.

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

Примечание

В случаях, когда содержимое ответа представляет собой поток (объект типа «читаемый файл»), Falcon не предоставит заголовок Content-Length WSGI-серверу, если content_length не установлен явно. Следовательно, сервер может выбрать использование фрагментарной кодировки или одного из других методов, предложенных в PEP-3333.

content_location

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

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

content_range

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

Кортеж имеет вид (start, end, length, [unit]), где start и end обозначают диапазон (включительно), а length — общую длину, или ‘*’, если неизвестно. Для этих чисел вы можете передавать значения int, (нет необходимости предварительно преобразовывать их в str). Необязательное значение unit описывает единицу диапазона и по умолчанию равно ‘bytes’.

Примечание

Вам нужно использовать только альтернативную форму «bytes */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: псевдоним для falcon.util.structures.Context

delete_header(name) [source]

Удалить заголовок, который был ранее задан для этого ответа.

Если заголовок ранее не был задан, ничего не происходит (ошибка не возникает). В противном случае все значения, заданные для заголовка, будут удалены из ответа.

Обратите внимание, что вызов этого метода эквивалентен установке соответствующего свойства заголовка (если такое свойство доступно) на None. Например:

resp.etag = None

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

Этот метод нельзя использовать с заголовком Set-Cookie. Вместо этого используйте unset_cookie(), чтобы удалить cookie и убедиться, что пользовательский агент также удалит свою копию данных.

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

downloadable_as

Устанавливает заголовок Content-Disposition с использованием заданного имени файла.

Значение будет использовано для директивы filename. Например, при 'report.pdf', заголовок Content-Disposition будет установлен на: 'attachment; filename="report.pdf"'.

etag

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

Заголовок ETag будет заключён в двойные кавычки "value" в случае, если пользователь его не передал.

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

Примечание

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

get_header(name, default=None) [source]

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

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

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

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

Примечание

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

location

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

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

retry_after

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

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

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

Установите cookie ответа.

Примечание

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

См. также

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

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

set_header(name, value) [source]

Устанавливает заголовок ответа заданному значению.

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

Вызов этого метода перезаписывает любые ранее установленные значения для этого заголовка. Чтобы добавить дополнительное значение для этого заголовка, используйте append_header() вместо этого.

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

Этот метод нельзя использовать для установки cookie; используйте вместо него append_header() или set_cookie().

Параметры:

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

Возбуждает:

ValueError – name не может быть 'Set-Cookie'.

set_headers(headers) [source]

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

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

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

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

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

Этот метод нельзя использовать для установки cookie; используйте вместо него append_header() или set_cookie().

Параметры:

headers (dict или list) –

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

Примечание

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

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

set_stream(stream, content_length) [source]

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

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

Примечание

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

Параметры:	stream – Чтение файла-подобного объекта. content_length (int) – Длина потока, используемая для заголовка Content-Length в ответе.

stream_len

Установить заголовок Content-Length.

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

Примечание

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

unset_cookie(name) [source]

Удалить cookie в ответе

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

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

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

vary

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

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

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

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

© 2019 by Falcon contributors
Licensed under the Apache License, Version 2.0.
https://falcon.readthedocs.io/en/2.0.0/api/request_and_response.html