СМИ

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

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

Если вы создаёте JSON-API, настройка не требуется. Просто обратитесь к свойству 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 Schema; тем не менее, JSON Schema очень универсален и может использоваться для проверки любого десериализованного типа СМИ, который также поддерживает JSON (т.е. словари, списки и т.д.).

falcon.media.validators.jsonschema.validate(schema) [source]

Декоратор, который проверяет req.media с помощью JSON Schema.

Параметры:	схема (dict) – Словарь, соответствующий спецификации JSON Schema. Дополнительную информацию о определении совместимого словаря см. на сайте json-schema.org.

Пример

from falcon.media.validators import jsonschema

# -- snip --

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

# -- snip --

Примечание

Для работы этого валидатора необходимо установить библиотеку jsonschema из PyPI. Библиотека также требует Python 2.7+.

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

Переговоры по типу содержимого

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

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

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

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

При создании объекта API вы можете добавить или полностью заменить все обработчики. Например, предположим, что вы хотите создать API, который отправляет и получает MessagePack. Мы можем легко сделать это, сообщив нашему Falcon API, что мы хотим по умолчанию тип медиа 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 [source]

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

class falcon.media.MessagePackHandler [source]

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

Примечание

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

Примечание

Для работы этого обработчика необходимо установить пакет python-msgpack.

Пользовательский тип обработчика

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

class falcon.media.BaseHandler [source]

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

serialize(obj) [source]

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

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

deserialize(raw) [source]

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

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

Обработчики

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