URL Routing — Werkzeug documentation
URL Routing
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 PATH_INFO
and call registered callback functions that return the value.
Werkzeug provides a much more powerful system, similar to Routes. All the objects mentioned on this page must be imported from werkzeug.routing, not from werkzeug
!
Quickstart
Here is a simple example which could be the URL definition for a blog:
from werkzeug.routing import Map, Rule, NotFound, RequestRedirect
url_map = Map([
Rule('/', endpoint='blog/index'),
Rule('/<int:year>/', endpoint='blog/archive'),
Rule('/<int:year>/<int:month>/', endpoint='blog/archive'),
Rule('/<int:year>/<int:month>/<int:day>/', endpoint='blog/archive'),
Rule('/<int:year>/<int:month>/<int:day>/<slug>',
endpoint='blog/show_post'),
Rule('/about', endpoint='blog/about_me'),
Rule('/feeds/', endpoint='blog/feeds'),
Rule('/feeds/<feed_name>.rss', endpoint='blog/show_feed')
])
def application(environ, start_response):
urls = url_map.bind_to_environ(environ)
try:
endpoint, args = urls.match()
except HTTPException, e:
return e(environ, start_response)
start_response('200 OK', [('Content-Type', 'text/plain')])
return ['Rule points to %r with arguments %r' % (endpoint, args)]
So what does that do? First of all we create a new Map
which stores a bunch of URL rules. Then we pass it a list of Rule
objects.
Each Rule
object is instantiated with a string that represents a rule and an endpoint which will be the alias for what view the rule represents. Multiple rules can have the same endpoint, but should have different arguments to allow URL construction.
The format for the URL rules is straightforward, but explained in detail below.
Inside the WSGI application we bind the url_map to the current request which will return a new MapAdapter
. This url_map adapter can then be used to match or build domains for the current request.
The MapAdapter.match()
method can then either return a tuple in the form (endpoint, args)
or raise one of the three exceptions NotFound
, MethodNotAllowed
, or RequestRedirect
. For more details about those exceptions have a look at the documentation of the MapAdapter.match()
method.
Rule Format
Rule strings are URL paths with placeholders for variable parts in the format <converter(arguments):name>
. converter
and arguments
(with parentheses) are optional. If no converter is given, the default
converter is used (string
by default). The available converters are discussed below.
Rules that end with a slash are “branches”, others are “leaves”. If strict_slashes
is enabled (the default), visiting a branch URL without a trailing slash will redirect to the URL with a slash appended.
Many HTTP servers merge consecutive slashes into one when receiving requests. If merge_slashes
is enabled (the default), rules will merge slashes in non-variable parts when matching and building. Visiting a URL with consecutive slashes will redirect to the URL with slashes merged. If you want to disable merge_slashes
for a Rule
or Map
, you’ll also need to configure your web server appropriately.
Built-in Converters
Converters for common types of URL variables are built-in. The available converters can be overridden or extended through Map.converters
.
Maps, Rules and Adapters
Rule Factories
Rule Templates
Custom Converters
You can add custom converters that add behaviors not provided by the built-in converters. To make a custom converter, subclass BaseConverter
then pass the new class to the Map
converters
parameter, or add it to url_map.converters
.
The converter should have a regex
attribute with a regular expression to match with. If the converter can take arguments in a URL rule, it should accept them in its __init__
method.
It can implement a to_python
method to convert the matched string to some other object. This can also do extra validation that wasn’t possible with the regex
attribute, and should raise a werkzeug.routing.ValidationError
in that case. Raising any other errors will cause a 500 error.
It can implement a to_url
method to convert a Python object to a string when building a URL. Any error raised here will be converted to a werkzeug.routing.BuildError
and eventually cause a 500 error.
This example implements a BooleanConverter
that will match the strings "yes"
, "no"
, and "maybe"
, returning a random value for "maybe"
.
from random import randrange
from werkzeug.routing import BaseConverter, ValidationError
class BooleanConverter(BaseConverter):
regex = r"(?:yes|no|maybe)"
def __init__(self, url_map, maybe=False):
super(BooleanConverter, self).__init__(url_map)
self.maybe = maybe
def to_python(self, value):
if value == "maybe":
if self.maybe:
return not randrange(2)
raise ValidationError
return value == 'yes'
def to_url(self, value):
return "yes" if value else "no"
from werkzeug.routing import Map, Rule
url_map = Map([
Rule("/vote/<bool:werkzeug_rocks>", endpoint="vote"),
Rule("/guess/<bool(maybe=True):foo>", endpoint="guess")
], converters={'bool': BooleanConverter})
If you want to change the default converter, assign a different converter to the "default"
key.
Host Matching
New in version 0.7.
Starting with Werkzeug 0.7 it’s also possible to do matching on the whole host names instead of just the subdomain. To enable this feature you need to pass host_matching=True
to the Map
constructor and provide the host argument to all routes:
url_map = Map([
Rule('/', endpoint='www_index', host='www.example.com'),
Rule('/', endpoint='help_index', host='help.example.com')
], host_matching=True)
Variable parts are of course also possible in the host section:
url_map = Map([
Rule('/', endpoint='www_index', host='www.example.com'),
Rule('/', endpoint='user_index', host='<user>.example.com')
], host_matching=True)
WebSockets
New in version 1.0.
If a Rule
is created with websocket=True
, it will only match if the Map
is bound to a request with a url_scheme
of ws
or wss
.
Note
Werkzeug has no further WebSocket support beyond routing. This functionality is mostly of use to ASGI projects.
url_map = Map([
Rule("/ws", endpoint="comm", websocket=True),
])
adapter = map.bind("example.org", "/ws", url_scheme="ws")
assert adapter.match() == ("comm", {})
If the only match is a WebSocket rule and the bind is HTTP (or the only match is HTTP and the bind is WebSocket) a WebsocketMismatch
(derives from BadRequest
) exception is raised.
As WebSocket URLs have a different scheme, rules are always built with a scheme and host, force_external=True
is implied.
url = adapter.build("comm")
assert url == "ws://example.org/ws"