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

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(schema) [source]

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

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

Примечание

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

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

Пример

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.

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

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

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

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

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

Примечание

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

$ pip install msgpack

Пользователям Python 2.6 потребуется использовать устаревший пакет msgpack-python вместо него, зафиксировав версию 0.4.8.

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

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

class falcon.media.BaseHandler [source]

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

serialize(obj) [source]

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

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

deserialize(raw) [source]

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

Параметры:	raw (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