module documentation

When it comes to combining multiple controller or view functions (however you want to call them) you need a dispatcher. A simple way would be applying regular expression tests on the PATH_INFO and calling registered callback functions that return the value then.

This module implements a much more powerful system than simple regular expression matching because it can also convert values in the URLs and build URLs.

Here a simple example that creates a URL map for an application with two subdomains (www and kb) and some URL rules:

m = Map([
    # Static URLs
    Rule('/', endpoint='static/index'),
    Rule('/about', endpoint='static/about'),
    Rule('/help', endpoint='static/help'),
    # Knowledge Base
    Subdomain('kb', [
        Rule('/', endpoint='kb/index'),
        Rule('/browse/', endpoint='kb/browse'),
        Rule('/browse/<int:id>/', endpoint='kb/browse'),
        Rule('/browse/<int:id>/<int:page>', endpoint='kb/browse')
], default_subdomain='www')

If the application doesn't use subdomains it's perfectly fine to not set the default subdomain and not use the Subdomain rule factory. The endpoint in the rules can be anything, for example import paths or unique identifiers. The WSGI application can use those endpoints to get the handler for that URL. It doesn't have to be a string at all but it's recommended.

Now it's possible to create a URL adapter for one of the subdomains and build URLs:

c = m.bind('')"kb/browse", dict(id=42))
''"kb/browse", dict())
''"kb/browse", dict(id=42, page=3))
'/about'"static/index", force_external=True)

c = m.bind('', subdomain='kb')"static/about")

The first argument to bind is the server name without the subdomain. Per default it will assume that the script is mounted on the root, but often that's not the case so you can provide the real mount point as second argument:

c = m.bind('', '/applications/example')

The third argument can be the subdomain, if not given the default subdomain is used. For more details about binding have a look at the documentation of the MapAdapter.

And here is how you can match URLs:

c = m.bind('')

('static/index', {})

('static/about', {})

c = m.bind('', '/', 'kb')

('kb/index', {})

('kb/browse', {'id': 42, 'page': 23})

If matching fails you get a NotFound exception, if the rule thinks it's a good idea to redirect (for example because the URL was defined to have a slash at the end but the request was missing that slash) it will raise a RequestRedirect exception. Both are subclasses of HTTPException so you can use those errors as responses in the application.

If matching succeeded but the URL rule was incompatible to the given method (for example there were only rules for GET and HEAD but routing tried to match a POST request) a MethodNotAllowed exception is raised.

Class ​Any​Converter Matches one of the items provided. Items can either be Python identifiers or strings:
Class ​Base​Converter Base class for all converters.
Class ​Build​Error Raised if the build system cannot find a URL for an endpoint with the values provided.
Class ​Endpoint​Prefix Prefixes all endpoints (which must be strings for this factory) with another string. This can be useful for sub applications:
Class ​Float​Converter This converter only accepts floating point values:
Class ​Integer​Converter This converter only accepts integer values:
Class ​Map No summary
Class ​Map​Adapter Returned by Map.bind or Map.bind_to_environ and does the URL matching and building based on runtime information.
Class ​Number​Converter Baseclass for IntegerConverter and FloatConverter.
Class ​Path​Converter Like the default UnicodeConverter, but it also matches slashes. This is useful for wikis and similar applications:
Class ​Request​Alias​Redirect This rule is an alias and wants to redirect to the canonical URL.
Class ​Request​Path Internal exception.
Class ​Request​Redirect Raise if the map requests a redirect. This is for example the case if strict_slashes are activated and an url that requires a trailing slash.
Class ​Routing​Exception Special exceptions that require the application to redirect, notifying about missing urls, etc.
Class ​Rule No summary
Class ​Rule​Factory As soon as you have more complex URL setups it's a good idea to use rule factories to avoid repetitive tasks. Some of them are builtin, others can be added by subclassing RuleFactory and overriding get_rules.
Class ​Rule​Template Returns copies of the rules wrapped and expands string templates in the endpoint, rule, defaults or subdomain sections.
Class ​Rule​Template​Factory A factory that fills in template variables into rules. Used by RuleTemplate internally.
Class ​Subdomain All URLs provided by this factory have the subdomain set to a specific domain. For example if you want to use the subdomain for the current language this can be a good setup:
Class ​Submount Like Subdomain but prefixes the URL rule with a given string:
Class ​Unicode​Converter This converter is the default converter and accepts any string but only one path segment. Thus the string can not include a slash.
Class ​UUIDConverter This converter only accepts UUID strings:
Class ​Validation​Error Validation error. If a rule converter raises this exception the rule does not match the current URL and the next URL is tried.
Class ​Websocket​Mismatch The only matched rule is either a WebSocket and the request is HTTP, or the rule is HTTP and the request is a WebSocket.
Function parse​_converter​_args Undocumented
Function parse​_rule Parse a rule and return it as generator. Each iteration yields tuples in the form (converter, arguments, variable). If the converter is None it's a static url part, otherwise it's a dynamic one.
Constant DEFAULT​_CONVERTERS Undocumented
Function ​_prefix​_names ast parse and prefix names with . to avoid collision with user vars
Function ​_pythonize Undocumented
Constant ​_CALL​_CONVERTER​_CODE​_FMT Undocumented
Constant ​_IF​_KWARGS​_URL​_ENCODE​_AST Undocumented
Constant ​_IF​_KWARGS​_URL​_ENCODE​_CODE Undocumented
Constant ​_PYTHON​_CONSTANTS Undocumented
Constant ​_URL​_ENCODE​_AST​_NAMES Undocumented
Variable ​_converter​_args​_re Undocumented
Variable ​_rule​_re Undocumented
Variable ​_simple​_rule​_re Undocumented
def parse_converter_args(argstr):


t.Tuple[t.Tuple, t.Dict[str, t.Any]]Undocumented
def parse_rule(rule):
Parse a rule and return it as generator. Each iteration yields tuples in the form (converter, arguments, variable). If the converter is None it's a static url part, otherwise it's a dynamic one.
t.Iterator[t.Tuple[t.Optional[str], t.Optional[str], str]]Undocumented
Unknown Field: internal
DEFAULT_CONVERTERS: t.Mapping[str, t.Type[BaseConverter]] =


{'default': UnicodeConverter,
 'string': UnicodeConverter,
 'any': AnyConverter,
 'path': PathConverter,
 'int': IntegerConverter,
 'float': FloatConverter,
 'uuid': UUIDConverter}
def _prefix_names(src):
ast parse and prefix names with . to avoid collision with user vars
def _pythonize(value):


t.Union[None, bool, int, float, str]Undocumented




'''if kwargs:
    q = \'?\'
    params = self._encode_query_vars(kwargs)
    q = params = \'\'


{'None': None, 'True': True, 'False': False}


(_prefix_names('q'), _prefix_names('params'))
_converter_args_re =


_rule_re =


_simple_rule_re =