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

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.

Идентификатор: 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.create_http_method_map(resource) [source]

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

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