werkzeug.routing

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('example.com')

c.build("kb/browse", dict(id=42))
'http://kb.example.com/browse/42/'

c.build("kb/browse", dict())
'http://kb.example.com/browse/'

c.build("kb/browse", dict(id=42, page=3))
'http://kb.example.com/browse/42/3'

c.build("static/about")
'/about'

c.build("static/index", force_external=True)
'http://www.example.com/'

c = m.bind('example.com', subdomain='kb')

c.build("static/about")
'http://www.example.com/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('example.com', '/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('example.com')

c.match("/")
('static/index', {})

c.match("/about")
('static/about', {})

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

c.match("/")
('kb/index', {})

c.match("/browse/42/23")
('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	`AnyConverter`	Matches one of the items provided. Items can either be Python identifiers or strings:
Class	`BaseConverter`	Base class for all converters.
Class	`BuildError`	Raised if the build system cannot find a URL for an endpoint with the values provided.
Class	`EndpointPrefix`	Prefixes all endpoints (which must be strings for this factory) with another string. This can be useful for sub applications:
Class	`FloatConverter`	This converter only accepts floating point values:
Class	`IntegerConverter`	This converter only accepts integer values:
Class	`Map`	No summary
Class	`MapAdapter`	Returned by `Map.bind` or `Map.bind_to_environ` and does the URL matching and building based on runtime information.
Class	`NumberConverter`	Baseclass for `IntegerConverter` and `FloatConverter`.
Class	`PathConverter`	Like the default `UnicodeConverter`, but it also matches slashes. This is useful for wikis and similar applications:
Class	`RequestAliasRedirect`	This rule is an alias and wants to redirect to the canonical URL.
Class	`RequestPath`	Internal exception.
Class	`RequestRedirect`	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	`RoutingException`	Special exceptions that require the application to redirect, notifying about missing urls, etc.
Class	`Rule`	No summary
Class	`RuleFactory`	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	`RuleTemplate`	Returns copies of the rules wrapped and expands string templates in the endpoint, rule, defaults or subdomain sections.
Class	`RuleTemplateFactory`	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	`UnicodeConverter`	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	`ValidationError`	Validation error. If a rule converter raises this exception the rule does not match the current URL and the next URL is tried.
Class	`WebsocketMismatch`	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):

Undocumented

Parameters
argstr:`str`	Undocumented
Returns
`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.

Parameters
rule:`str`	Undocumented
Returns
`t.Iterator[t.Tuple[t.Optional[str], t.Optional[str], str]]`	Undocumented
Unknown Field: internal

DEFAULT_CONVERTERS: t.Mapping[str, t.Type[BaseConverter]] =

Undocumented

Value

{'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

Parameters
src:`str`	Undocumented
Returns
`ast.stmt`	Undocumented

def _pythonize(value):

Undocumented

Parameters
value:`str`	Undocumented
Returns
`t.Union[None, bool, int, float, str]`	Undocumented

_CALL_CONVERTER_CODE_FMT: str =

Undocumented

Value

'self._converters[{elem!r}].to_url()'

_IF_KWARGS_URL_ENCODE_AST =

Undocumented

Value

_prefix_names(_IF_KWARGS_URL_ENCODE_CODE)

_IF_KWARGS_URL_ENCODE_CODE: str =

Undocumented

Value

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

_PYTHON_CONSTANTS: dict =

Undocumented

Value

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

_URL_ENCODE_AST_NAMES =

Undocumented

Value

(_prefix_names('q'), _prefix_names('params'))

_converter_args_re =

Undocumented

_rule_re =

Undocumented

_simple_rule_re =

Undocumented