deb-python-falcon/docs/api/routing.rst

Routing

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

Custom routers may derive from the default :py~.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 :pyfalcon.API. For example:

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

falcon.routing