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

Экземпляры классов 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) [исходный код]

Представляет 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 – Возвращает часть ‘host:port’ 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 если запрос еще не был обработано, как это может быть для методов process_request() middleware. Также может быть None если ваше приложение использует пользовательский движок маршрутизации, и движок не предоставляет шаблон URI при решении маршрута.

remote_addr

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

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

Примечание

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

END_OF_DOCUMENT_MARKER

access_route

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

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

Forwarded
X-Forwarded-For
X-Real-IP

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

Примечание

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

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

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

forwarded

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

(См. также: 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: словарь – Словарь пар имя/значение куки. (См. также: Получение куки)

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

client_prefers(media_types) [source]

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

Параметры:	media_types (итерируемый список str) – Один или несколько типов интернет-медиа, из которых выбирается предпочтительный тип клиента. Это значение обязательно должно быть итерируемым набором строк.
Возвращаемое значение:	Предпочтительный тип медиа клиента, основанный на заголовке 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.

Примечание

Аналогично тому, как обрабатываются несколько ключей в данных формы, если параметру строки запроса назначен список значений через запятую (например, 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=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`.
Возвращает:	Значение параметра, если он найден и может быть преобразован в булево значение. Если параметр не найден, возвращается `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`).
Возвращает:	Значение параметра, если он найден и может быть преобразован в дату в соответствии с заданной строкой формата. Если параметр не найден, возвращается `None`, если значение required равно `True`.
Тип возвращаемого значения:	datetime.date
Исключения:	`HTTPBadRequest` – Требуемый параметр отсутствует в запросе или значение не может быть преобразовано в дату.

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` – Требуемый параметр отсутствует в запросе или значение не может быть преобразовано в datetime.

get_param_as_dict(name, required=False, store=None): Устаревшее псевдоним для get_param_as_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`).
Возвращает:	Значение параметра, если он найден и может быть преобразован в `int`. Если параметр не найден, возвращает `None`, если `required` равно `True`.
Тип возвращаемого значения:	int

Возбуждает

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

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

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

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

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

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` – Требуемый параметр отсутствует в запросе или функция преобразования возбудила исключение `ValueError`.

get_param_as_uuid(name, required=False, store=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`).
Возвращает:	Значение параметра, если он найден и может быть преобразован в `UUID`. Если параметр не найден, возвращает `None`, если `required` равно `True`.
Тип возвращаемого значения:	UUID

Возбуждает

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

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 если параметр отсутствует. Предоставляет поле заголовка host запроса, полученного прокси.

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

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

stream_len: int – Ожидаемая длина stream. Если stream задано, но stream_len нет, Falcon не будет передавать заголовок Content-Length WSGI-серверу. В результате сервер может использовать кодирование chunks или один из других стратегий, предложенных в 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 указывает клиенту, какие единицы диапазонов поддерживаются (например, «байты») для целевого ресурса.

Если запросы диапазона не поддерживаются для целевого ресурса, заголовок может быть установлен на «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) – Тип связи ссылки, такой как «следующий» или «закладка». (См. также: http://www.iana.org/assignments/link-relations/link-relations.xhtml)
Ключевые аргументы:
	title (str) – Читабельное для человека описание назначения ссылки (по умолчанию `None`). Если описание содержит не-ASCII символы, вам потребуется использовать `title_star` или предоставить и версию US-ASCII используя `title` и версию Unicode используя `title_star`. title_star (кортеж строк) – Локализованное описание назначения ссылки (по умолчанию `None`). Значение должно быть кортежем из двух элементов в формате (идентификатор языка, текст), где идентификатор языка — стандартный идентификатор языка, как определён в RFC 5646, Раздел 2.1, и текст — строка Unicode. Примечание идентификатор языка может быть пустой строкой, в этом случае клиент будет предполагать язык из общего контекста текущего запроса. Примечание текст всегда будет закодирован как UTF-8. Если строка содержит символы не-ASCII, она должна передаваться как строка типа `unicode` (требуется префикс ‘u’ в Python 2). anchor (str) – Переопределить контекстный IRI другим URI (по умолчанию None). По умолчанию, контекстный IRI для ссылки — это просто IRI запрашиваемого ресурса. Переданное значение может быть относительным URI. hreflang (str или итерируемый объект) – Либо один идентификатор языка, либо `list` или `tuple` таких идентификаторов, чтобы дать подсказку клиенту о языке результата перехода по ссылке. Список тегов может быть задан, чтобы указать клиенту, что целевой ресурс доступен на нескольких языках. type_hint (str) – Предоставляет подсказку о типе медиа результата де-референцирования ссылки (по умолчанию `None`). Как отмечается в RFC 5988, это только подсказка и не переопределяет заголовок Content-Type, возвращаемый при переходе по ссылке.

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

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

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

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

Примечание

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

Примечание

текст всегда будет закодирован как UTF-8. Если строка содержит символы не-ASCII, она должна передаваться как строка типа unicode (требуется префикс ‘u’ в Python 2).
anchor (str) – Переопределить контекстный IRI другим URI (по умолчанию None). По умолчанию, контекстный IRI для ссылки — это просто IRI запрашиваемого ресурса. Переданное значение может быть относительным URI.
hreflang (str или итерируемый объект) – Либо один идентификатор языка, либо 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` или быть типа `str` или `StringType`. Строки должны содержать только символы US-ASCII. В Python 2.x также принимается тип `unicode`, хотя такие строки также ограничены US-ASCII.

name (str) – Имя заголовка (регистронезависимое). Применимы ограничения, указанные ниже, для значения заголовка.
value (str) – Значение заголовка. Должно быть преобразуемо в 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.

Кортеж имеет вид (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: псевдоним для dict

delete_header(name) [source]

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

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

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

resp.etag = None

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

downloadable_as

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

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

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 не поддерживается.

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`). Это предназначено для снижения некоторых форм межсайтового скриптинга. (См. также: RFC 6265, Раздел 4.1.2.6)
Возбуждает:	`KeyError` – `name` не является допустимым именем куки. `ValueError` – `value` не является допустимым значением куки.

set_header(name, value) [source]

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

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

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

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

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

Параметры:

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

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

set_headers(headers) [source]

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

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

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

Параметры:

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

headers (dict or list) –

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

Примечание

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

Возбуждает: ValueError – headers не был dict или списком кортежей 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–2017 by Rackspace Hosting, Inc. and other contributors
Licensed under the Apache License, Version 2.0.
https://falcon.readthedocs.io/en/1.4.1/api/request_and_response.html