Routing

The falcon.routing module contains utilities used internally by falcon.API() to route requests. They are exposed here for use by custom routing engines.

Custom routers may derive from the default CompiledRouter engine, or implement a completely different routing strategy (such as object-based routing).

A custom router is any class that implements the following interface:

class FancyRouter(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.

        """

A custom routing engine may be specified when instantiating falcon.API(). For example:

fancy = FancyRouter()
api = API(router=fancy)

Default router and utility functions.

This package implements Falcon’s default routing engine, and also includes utility functions to aid in the implementation of custom routers.

falcon.routing.create_http_method_map(resource)

Maps HTTP methods (e.g., ‘GET’, ‘POST’) to methods of a resource object.

Parameters:resource – An object with responder methods, following the naming convention on_*, that correspond to each method the resource supports. For example, if a resource supports GET and POST, it should define on_get(self, req, resp) and on_post(self, req, resp). Returns:A mapping of HTTP methods to responders. Return type:dict

falcon.routing.compile_uri_template(template)

Compile the given URI template string into a pattern matcher.

This function can be used to construct custom routing engines that iterate through a list of possible routes, attempting to match an incoming request against each route’s compiled regular expression.

Each field is converted to a named group, so that when a match is found, the fields can be easily extracted using re.MatchObject.groupdict().

This function does not support the more flexible templating syntax used in the default router. Only simple paths with bracketed field expressions are recognized. For example:

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

Also, note that if the template contains a trailing slash character, it will be stripped in order to normalize the routing logic.

Parameters:template (str) – The template to compile. Note that field names are restricted to ASCII a-z, A-Z, and the underscore character. Returns:(template_field_names, template_regex) Return type:tuple

class falcon.routing.CompiledRouter

Fast URI router which compiles its routing logic to Python code.

Generally you do not need to use this router class directly, as an instance is created by default when the falcon.API class is initialized.

The router treats URI paths as a tree of URI segments and searches by checking the URI one segment at a time. Instead of interpreting the route tree for each look-up, it generates inlined, bespoke Python code to perform the search, then compiles that code. This makes the route processing quite fast.

add_route(uri_template, method_map, resource)

Adds a route between a URI path template and a resource.

Parameters:

• uri_template (str) – A URI template to use for the route
• method_map (dict) – A mapping of HTTP methods (e.g., ‘GET’, ‘POST’) to methods of a resource object.
• resource (object) – The resource instance to associate with the URI template.

find(uri, req=None)

Search for a route that matches the given partial URI.

Parameters:uri (str) – The requested path to route. Keyword Arguments:  req (Request) – The Request object that will be passed to the routed responder. Currently the value of this argument is ignored by CompiledRouter. Routing is based solely on the path. Returns:

A 4-member tuple composed of (resource, method_map,

params, uri_template), or None if no route matches the requested path.

Return type:tuple