Средства массовой информации

Falcon позволяет легко и настраиваемо обрабатывать типы интернет-медиа. По умолчанию Falcon включает только один обработчик JSON. Однако дополнительные обработчики можно настроить с помощью объектов falcon.RequestOptions и falcon.ResponseOptions, указанных в вашем объекте falcon.API.

Использование

Конфигурация не требуется, если вы создаёте API JSON. Просто обратитесь к атрибуту media или установите его соответствующим образом и позвольте Falcon выполнить тяжёлую работу за вас.

import falcon


class EchoResource(object):
    def on_post(self, req, resp):
        message = req.media.get('message')

        resp.media = {'message': message}
        resp.status = falcon.HTTP_200

Проверка медиа

В настоящее время Falcon предоставляет только валидатор медиа JSON-схемы; однако JSON-схема очень универсальна и может использоваться для проверки любого десериализованного типа медиа, который также поддерживает JSON (т.е. словари, списки и т.д.).

falcon.media.validators.jsonschema.validate(req_schema=None, resp_schema=None) [source]

Декоратор для проверки req.media с помощью JSON-схемы.

Этот декоратор обеспечивает стандартную проверку JSON-схемы с помощью пакета jsonschema, доступного на PyPI. Семантическая проверка через ключевое слово format включена для обработчиков по умолчанию, реализованных пакетом jsonschema.FormatChecker.

Примечание

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

См. json-schema.org для получения дополнительной информации об определении совместимого словаря.

Параметры:	req_schema (dict, необязательно) – Словарь, соответствующий спецификации JSON-схемы. Запрос будет проверен по этой схеме. resp_schema (dict, необязательно) – Словарь, соответствующий спецификации JSON-схемы. Ответ будет проверен по этой схеме.

Пример

from falcon.media.validators import jsonschema

# -- snip --

@jsonschema.validate(my_post_schema)
def on_post(self, req, resp):

# -- snip --

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

Переговоры о формате содержимого

В настоящее время Falcon поддерживает только частичные переговоры «из коробки». По умолчанию при использовании атрибута media он пытается де/сериализовать данные на основе значения заголовка Content-Type. Отсутствующим элементом, который Falcon не предоставляет, является связь между заголовком falcon.Request Accept , предоставленным пользователем, и заголовком falcon.Response Content-Type.

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

class NegotiationMiddleware(object):
    def process_request(self, req, resp):
        resp.content_type = req.accept

Замена обработчиков по умолчанию

При создании объекта API вы можете добавить или полностью заменить все обработчики. Например, предположим, что вы хотите создать API, который отправляет и получает MessagePack. Мы легко можем это сделать, сообщив нашему API Falcon, что мы хотим использовать тип медиа по умолчанию application/msgpack, а затем создадим новый объект Handlers, указав требуемый тип медиа и обработчик, который может обрабатывать эти данные.

import falcon
from falcon import media


handlers = media.Handlers({
    'application/msgpack': media.MessagePackHandler(),
})

api = falcon.API(media_type='application/msgpack')

api.req_options.media_handlers = handlers
api.resp_options.media_handlers = handlers

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

import falcon
from falcon import media


extra_handlers = {
    'application/msgpack': media.MessagePackHandler(),
}

api = falcon.API()

api.req_options.media_handlers.update(extra_handlers)
api.resp_options.media_handlers.update(extra_handlers)

Поддерживаемые типы обработчиков

class falcon.media.JSONHandler(dumps=None, loads=None) [source]

Обработчик JSON-медиа.

Этот обработчик по умолчанию использует стандартную библиотеку Python json, но его легко настроить для использования любого из ряда сторонних библиотек JSON в зависимости от ваших потребностей. Например, под CPython часто можно получить значительный прирост производительности, используя стороннюю библиотеку. Хорошими вариантами в этом отношении являются orjson, python-rapidjson, и mujson.

Примечание

Если вы развертываете на PyPy, мы рекомендуем использовать стандартную реализацию JSON библиотеки, поскольку она будет быстрее в большинстве случаев по сравнению со сторонней библиотекой.

Переопределение реализации JSON по умолчанию — это просто вопрос указания желаемых функций dumps и loads.

import falcon
from falcon import media

import rapidjson

json_handler = media.JSONHandler(
    dumps=rapidjson.dumps,
    loads=rapidjson.loads,
)
extra_handlers = {
    'application/json': json_handler,
}

api = falcon.API()
api.req_options.media_handlers.update(extra_handlers)
api.resp_options.media_handlers.update(extra_handlers)

По умолчанию, ensure_ascii передаётся функции json.dumps. Если вы переопределите функцию dumps, вам нужно будет явно установить ensure_ascii в False , чтобы включить сериализацию символов Unicode в UTF-8. Это легко сделать, используя functools.partial для применения желаемого ключевого аргумента. На самом деле, вы можете использовать эту же технику для настройки любых параметров, поддерживаемых функциями dumps и loads:

from functools import partial

from falcon import media
import rapidjson

json_handler = media.JSONHandler(
    dumps=partial(
        rapidjson.dumps,
        ensure_ascii=False, sort_keys=True
    ),
)

Ключевые аргументы:
	dumps (func) – Функция для сериализации JSON-ответов. loads (func) – Функция для десериализации JSON-запросов.

deserialize(stream, content_type, content_length) [source]

Десериализовать тело falcon.Request.

Параметры:	stream (object) – Входные данные для десериализации. content_type (str) – Тип содержимого запроса. content_length (int) – Длина содержимого запроса.
Возвращает:	Десериализованный объект.
Тип возвращаемого значения:	object

serialize(media, content_type) [source]

Сериализовать объект медиа в falcon.Response.

Параметры:	media (object) – Сериализуемый объект. content_type (str) – Тип содержимого ответа.
Возвращает:	Результат сериализации байтов из входного объекта.
Тип возвращаемого значения:	bytes

class falcon.media.MessagePackHandler [source]

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

Этот обработчик использует msgpack.unpackb() и msgpack.packb(). Тип MessagePack bin используется для различения строк Unicode (str в Python 3, unicode в Python 2) и байтовых строк (bytes в Python 2/3 или str в Python 2).

Примечание

Для этого обработчика требуется дополнительный пакет msgpack (версия 0.5.2 или выше), который необходимо установить дополнительно к falcon из PyPI:

$ pip install msgpack

deserialize(stream, content_type, content_length) [source]

Десериализация тела falcon.Request.

Параметры:	stream (объект) – Входные данные для десериализации. content_type (строка) – Тип содержимого запроса. content_length (целое число) – Длина содержимого запроса.
Возвращает:	Десериализованный объект.
Тип возвращаемого значения:	объект

serialize(media, content_type) [source]

Сериализация объекта медиа в falcon.Response.

Параметры:	media (объект) – Сериализуемый объект. content_type (строка) – Тип содержимого ответа.
Возвращает:	Результирующие сериализованные байты из входного объекта.
Тип возвращаемого значения:	байты

Тип пользовательского обработчика

Если в Falcon нет обработчика интернет-типов медиа, который поддерживает ваш случай использования, вы можете легко реализовать свой собственный, используя предоставляемый Falcon абстрактный базовый класс:

class falcon.media.BaseHandler [source]

Абстрактный базовый класс для обработчика интернет-типов медиа

serialize(media, content_type) [source]

Сериализация объекта медиа в falcon.Response

Параметры:	media (объект) – Сериализуемый объект. content_type (строка) – Тип содержимого ответа.
Возвращает:	Результирующие сериализованные байты из входного объекта.
Тип возвращаемого значения:	байты

deserialize(stream, content_type, content_length) [source]

Десериализация тела falcon.Request.

Параметры:	stream (объект) – Входные данные для десериализации. content_type (строка) – Тип содержимого запроса. content_length (целое число) – Длина содержимого запроса.
Возвращает:	Десериализованный объект.
Тип возвращаемого значения:	объект

Обработчики

class falcon.media.Handlers(initial=None) [source]

Объект, подобный словарю, который управляет обработчиками интернет-типов медиа.

Константы типов медиа

Модуль 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