Маршрутизация

Falcon маршрутизирует входящие запросы к ресурсам на основе набора шаблонов URI. Если путь, запрошенный клиентом, соответствует шаблону для данного маршрута, запрос передаётся соответствующему ресурсу для обработки.

Если ни один маршрут не соответствует запросу, управление передаётся по умолчанию обработчику, который просто поднимает экземпляр HTTPNotFound. Обычно это приводит к отправке клиенту ответа 404.

Вот быстрый пример, чтобы показать, как всё вместе работает:

import json

import falcon

class ImagesResource(object):

    def on_get(self, req, resp):
        doc = {
            'images': [
                {
                    'href': '/images/1eaf6ef1-7f2d-4ecc-a8d5-6e8adba7cc0e.png'
                }
            ]
        }

        # Create a JSON representation of the resource
        resp.body = json.dumps(doc, ensure_ascii=False)

        # The following line can be omitted because 200 is the default
        # status returned by the framework, but it is included here to
        # illustrate how this may be overridden as needed.
        resp.status = falcon.HTTP_200

api = application = falcon.API()

images = ImagesResource()
api.add_route('/images', images)

Обработчик по умолчанию

По умолчанию Falcon использует механизм маршрутизации, основанный на дереве решений, которое сначала компилируется в код Python, а затем оценивается во время выполнения.

Метод add_route() используется для связывания шаблона URI с ресурсом. Falcon затем сопоставляет входящие запросы с ресурсами на основе этих шаблонов.

По умолчанию Falcon использует классы Python для представления ресурсов. На практике эти классы выполняют роль контроллеров в вашем приложении. Они преобразуют входящий запрос в одно или несколько внутренних действий, а затем формируют ответ клиенту на основе результатов этих действий. (См. также: Учебник: Создание ресурсов)

           ┌────────────┐
request  → │            │
           │ Resource   │ ↻ Orchestrate the requested action
           │ Controller │ ↻ Compose the result
response ← │            │
           └────────────┘

Каждый класс ресурса определяет различные методы «обработчиков», по одному на каждый HTTP-метод, который поддерживает ресурс. Имена обработчиков начинаются с on_ и называются в соответствии с тем HTTP-методом, который они обрабатывают, как в on_get(), on_post(), on_put(), и т.д.

Обработчики должны всегда определять как минимум два аргумента для получения объектов Request и Response соответственно:

def on_post(self, req, resp):
    pass

Объект Request представляет собой входящий HTTP-запрос. Он предоставляет свойства и методы для проверки заголовков, параметров строки запроса и других метаданных, связанных с запросом. Также предоставляется объект потока типа «файл» для чтения любых данных, включенных в тело запроса.

Объект Response представляет собой HTTP-ответ приложения на указанный запрос. Он предоставляет свойства и методы для установки статуса, данных заголовка и тела. Объект Response также предоставляет свойство, подобное словарю, context, для передачи произвольных данных методам хуков и middleware.

Помимо стандартных req и resp параметров, если шаблон маршрута содержит выражения полей, любой обработчик, который хочет получать запросы для этого маршрута, должен принимать аргументы, именованные по соответствующим именам полей, определённым в шаблоне.

Выражение поля состоит из имени поля в квадратных скобках. Например, приведённом шаблоне:

/user/{name}

PUT-запрос на «/user/kgriffs» был бы маршрутизирован к:

def on_put(self, req, resp, name):
    pass

Поскольку имена полей соответствуют именам аргументов в методах обработчиков, они должны быть допустимыми идентификаторами Python.

Отдельные сегменты пути могут содержать одно или несколько выражений полей, а поля не обязательно должны охватывать весь сегмент пути. Например:

/repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}
/serviceRoot/People('{name}')

(См. также Учебник Falcon для дополнительных примеров и пошагового руководства по настройке маршрутов в контексте демонстрационного приложения.)

Преобразователи полей

По умолчанию Falcon поддерживает использование преобразователей полей для преобразования значения поля шаблона URI. Преобразователи полей также могут выполнять простую валидацию входных данных. Например, следующий шаблон URI использует преобразователь int для преобразования значения tid в Pythonский int, но только если оно имеет ровно восемь цифр:

/teams/{tid:int(8)}

Если значение имеет неверный формат и не может быть преобразовано, Falcon отклонит запрос с ответом 404 клиенту.

Преобразователи инициализируются со спецификацией аргументов, указанной в выражении поля. Эти спецификации следуют стандартному синтаксису Python для передачи аргументов. Например, комментарии в следующем коде показывают, как преобразователь был бы инициализирован при различных спецификациях аргументов в шаблоне URI:

# IntConverter()
api.add_route(
    '/a/{some_field:int}',
    some_resource
)

# IntConverter(8)
api.add_route(
    '/b/{some_field:int(8)}',
    some_resource
)

# IntConverter(8, min=10000000)
api.add_route(
    '/c/{some_field:int(8, min=10000000)}',
    some_resource
)

Встроенные преобразователи

class falcon.routing.IntConverter(num_digits=None, min=None, max=None) [source]

Преобразует значение поля в целое число.

Идентификатор: int

Ключевые аргументы:
	num_digits (int) – Требует, чтобы значение имело заданное количество цифр. min (int) – Отклоняет значение, если оно меньше этого числа. max (int) – Отклоняет значение, если оно больше этого числа.

class falcon.routing.UUIDConverter [source]

Преобразует значение поля в uuid.UUID.

Идентификатор: uuid

Для преобразования значение поля должно состоять из строки из 32 шестнадцатеричных цифр, как определено в RFC 4122, раздел 3. Обратите внимание, однако, что дефисы и префикс URN являются необязательными.

class falcon.routing.DateTimeConverter(format_string='%Y-%m-%dT%H:%M:%SZ') [source]

Преобразует значение поля в datetime.

Идентификатор: dt

Ключевые аргументы:
	format_string (str) – Строка, используемая для парсинга значения поля в datetime. Поддерживаются любые форматы, распознаваемые функцией strptime() (по умолчанию '%Y-%m-%dT%H:%M:%SZ').

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

Пользовательские преобразователи могут быть зарегистрированы через параметр маршрутизатора converters. Преобразователь — это просто класс, реализующий интерфейс BaseConverter:

class falcon.routing.BaseConverter [source]

Абстрактный базовый класс для преобразователей полей шаблонов URI.

convert(value) [source]

Преобразует значение поля шаблона URI в другой формат или тип.

Параметры:	value (str) – Исходная строка для преобразования.
Возвращает:	Converted field value, or None if the field невозможно преобразовать.
Тип возвращаемого значения:	object

Настраиваемые маршрутизаторы

Настраиваемый механизм маршрутизации можно указать при создании экземпляра falcon.API(). Например:

router = MyRouter()
api = API(router=router)

Настраиваемые маршрутизаторы могут наследоваться от стандартного CompiledRouter движка или реализовывать совершенно другую стратегию маршрутизации (например, основанную на объектах).

Настраиваемый маршрутизатор — это любой класс, реализующий следующий интерфейс:

class MyRouter(object):
    def add_route(self, uri_template, method_map, resource):
        """Adds a route between URI path template and resource.

        Args:
            uri_template (str): The URI template to add.
            method_map (dict): A method map obtained by calling
                falcon.routing.create_http_method_map.
            resource (object): Instance of the resource class that
                will handle requests for the given URI.
        """

    def find(self, uri, req=None):
        """Search for a route that matches the given partial URI.

        Args:
            uri(str): The requested path to route.

        Keyword Args:
             req(Request): The Request object that will be passed to
                the routed responder. The router may use `req` to
                further differentiate the requested route. For
                example, a header may be used to determine the
                desired API version and route the request
                accordingly.

                Note:
                    The `req` keyword argument was added in version
                    1.2. To ensure backwards-compatibility, routers
                    that do not implement this argument are still
                    supported.

        Returns:
            tuple: A 4-member tuple composed of (resource, method_map,
                params, uri_template), or ``None`` if no route matches
                the requested path.

        """

Утилиты маршрутизации

Модуль falcon.routing содержит следующие утилиты, которые могут использоваться настраиваемыми механизмами маршрутизации.

falcon.routing.map_http_methods(resource) [source]

Сопоставляет HTTP-методы (например, ‘GET’, ‘POST’) с методами объекта ресурса.

Параметры:	resource – Объект с методами responder, следующими соглашению об именовании on_*, которые соответствуют каждому поддерживаемому методу ресурса. Например, если ресурс поддерживает GET и POST, он должен определить on_get(self, req, resp) и on_post(self, req, resp).
Возвращает:	Сопоставление HTTP-методов с явно определёнными обработчиками ресурсов.
Тип возвращаемого значения:	dict

falcon.routing.set_default_responders(method_map) [source]

Сопоставляет HTTP-методы, не явно определённые на ресурсе, со стандартными обработчиками.

Параметры:	method_map – Словарь, в котором HTTP-методы сопоставлены с обработчиками, явно определёнными в ресурсе.

falcon.routing.create_http_method_map(resource) [source]

Сопоставляет HTTP-методы (например, ‘GET’, ‘POST’) с методами объекта ресурса.

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

Этот метод устарел и будет удален в будущей версии. Пожалуйста, используйте map_http_methods() и map_http_methods() вместо него.

Параметры:	resource – Объект с методами responder, следующими соглашению об именовании on_*, которые соответствуют каждому поддерживаемому методу ресурса. Например, если ресурс поддерживает GET и POST, он должен определить on_get(self, req, resp) и on_post(self, req, resp).
Возвращает:	Сопоставление HTTP-методов с обработчиками.
Тип возвращаемого значения:	dict

falcon.routing.compile_uri_template(template) [source]

Компилирует заданную строку шаблона URI в согласователь шаблонов.

Эта функция может использоваться для создания настраиваемых механизмов маршрутизации, которые итеративно проходят по списку возможных маршрутов, пытаясь сопоставить входящий запрос с составленным регулярным выражением каждого маршрута.

Каждый элемент преобразуется в именованную группу, так что при обнаружении совпадения элементы можно легко извлечь, используя re.MatchObject.groupdict().

Эта функция не поддерживает более гибкий синтаксис шаблонов, используемый в стандартном маршрутизаторе. Поддерживаются только простые пути с выражениями полей в квадратных скобках. Например:

/
/books
/books/{isbn}
/books/{isbn}/characters
/books/{isbn}/characters/{name}

Также обратите внимание, что если шаблон содержит символ косой черты следом, он будет удалён для нормализации логики маршрутизации.

Параметры:	template (str) – Шаблон для компиляции. Обратите внимание, что имена полей ограничены ASCII a-z, A-Z и символом подчеркивания.
Возвращает:	(template_field_names, template_regex)
Тип возвращаемого значения:	tuple