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

Экземпляры классов 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.

scheme: str – Либо ‘http’, либо ‘https’.

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

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

host: str – Имя хоста, запрошенное клиентом

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

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

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

Примечание

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

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

app: str – Имя WSGI приложения (если используется WSGI-концепция виртуального хостинга).

access_route

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

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

Forwarded
X-Forwarded-For
X-Real-IP

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

Примечание

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

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

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

remote_addr

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

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

Примечание

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

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

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

Примечание

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

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

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

relative_uri: str – Часть пути + строка запроса полного URI.

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

Примечание

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

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

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

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

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

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

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

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

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

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

content_length: int – Значение заголовка 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 для разбора параметров и объединения их в параметры строки запроса. В этом случае поток будет находиться в конце файла.

bounded_stream

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

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

data = req.bounded_stream.read()

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

doc = json.load(req.bounded_stream)

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

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

range

кортеж из int – 2-элементный tuple, разобранный из значения заголовка Range.

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

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

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

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

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

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

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

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

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

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

cookies: dict – Словарь пар имя/значение cookie. См. также: Получение Cookie

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

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

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, например: «Вторник, 06-ноя-94 08:49:37 GMT» (по умолчанию `False`).
Возвращаемое значение:	Значение указанного заголовка, если он существует, или `None` , если заголовок не найден и не является обязательным.
Тип возвращаемого значения:	datetime
Возможные исключения:	`HTTPBadRequest` – Заголовок не найден в запросе, но он был обязательным. `HttpInvalidHeader` – Заголовок содержал некорректное/невалидное значение.

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

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

Примечание

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

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

Примечание

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

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

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

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

Поддерживаются следующие булевы строки:

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

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

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

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

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

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

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

Если значение параметра имеет формат JSON, то оно парсится и возвращается в виде словаря.

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

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

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

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

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

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

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

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

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

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

log_error(message) [source]

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

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

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

Response

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.

body: str или unicode – Строка, представляющая содержимое ответа. Если Unicode, 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-серверу. В результате сервер может выбрать использование кодировки блоками или одного из других стратегий, предложенных PEP-3333.

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

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

Примечание

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

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

accept_ranges

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

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

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

Примечание

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

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

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

См. также: https://tools.ietf.org/html/rfc5988

Примечание

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

Примечание

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

Параметры:

Параметры:	target (str) – Целевой IRI для ресурса, идентифицированного ссылкой. Будет преобразован в URI, если необходимо, в соответствии с RFC 3987, раздел 3.1. rel (str) – Тип связи ссылки, например, «следующий» или «закладка». См. также http://goo.gl/618GHr для списка зарегистрированных типов связей ссылок.
Ключевые аргументы:
	title (str) – Читабельное для человека описание пункта назначения ссылки (по умолчанию `None`). Если заголовок содержит символы, не входящие в ASCII, вам нужно использовать `title_star` вместо этого или предоставить как версию US-ASCII с помощью `title`, так и версию Unicode с помощью `title_star`. title_star (кортеж из str) – Локализованное описание пункта назначения ссылки (по умолчанию `None`). Значение должно быть кортежем из двух элементов в формате (идентификатор_языка, текст), где идентификатор_языка — стандартный идентификатор языка, как определено в RFC 5646, раздел 2.1, а текст — строка Unicode. Примечание идентификатор_языка может быть пустой строкой, в этом случае клиент предположит язык из общего контекста текущего запроса. Примечание текст всегда будет закодирован как UTF-8. Если строка содержит символы, не входящие в ASCII, она должна передаваться как строка типа %%%CODE_BLOCK_247%% (требуется префикс ‘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://goo.gl/618GHr для списка зарегистрированных типов связей ссылок.

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

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

Примечание

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

Примечание

текст всегда будет закодирован как UTF-8. Если строка содержит символы, не входящие в ASCII, она должна передаваться как строка типа %%%CODE_BLOCK_247%% (требуется префикс ‘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` или `StringType` и содержать только символы US-ASCII. В Python 2.x также принимается тип `unicode`, хотя такие строки также ограничены US-ASCII.

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

cache_control

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

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

content_location

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

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

content_range

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

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

Примечание

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

См. также: http://goo.gl/Iglhp

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

delete_header(name) [source]

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

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

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

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

get_header(name) [source]

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

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

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

Примечание

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

location

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

Это значение будет закодировано по 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 заданным путем и всеми подкаталогами (символ «/» интерпретируется как разделитель каталогов). Если 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]

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

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

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

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

Для установки cookie см. вместо этого set_cookie()

Параметры:

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

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

set_headers(headers) [source]

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

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

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

Параметры:

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

headers (dict или list) –

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

Примечание

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

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

set_stream(stream, stream_len) [source]

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

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

Примечание

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

unset_cookie(name) [source]

Сбросить cookie в ответе

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

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

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

vary

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

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

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

(Википедия)

См. также: http://goo.gl/NGHdL

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