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.

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):
        """Search for a route that matches the given URI.

        Args:
            uri (str): Request URI to match to a route.

        Returns:
            tuple: A 3-member tuple composed of (resource, method_map, params)
                or ``None`` if no route is found.
        """

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

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

falcon.routing.create_http_method_map(resource, before, after)

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).
• before – An action hook or list of hooks to be called before each on_* responder defined by the resource.
• after – An action hook or list of hooks to be called after each on_* responder defined by the resource.

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 URI path template and resource.

find(uri)

Finds resource and method map for a URI, or returns None.