Setting up routes

It is assumed that you are using a framework that has preconfigured Routes for you. In Pylons, you define your routes in the make_map function in your myapp/config/routing.py module. Here is a typical configuration:

from routes import Mapper
map = Mapper()
map.connect(None, "/error/{action}/{id}", controller="error")
map.connect("home", "/", controller="main", action="index")
# ADD CUSTOM ROUTES HERE
map.connect(None, "/{controller}/{action}")
map.connect(None, "/{controller}/{action}/{id}")

Lines 1 and 2 create a mapper.

Line 3 matches any three-component route that starts with “/error”, and sets the “controller” variable to a constant, so that a URL “/error/images/arrow.jpg” would produce:

{"controller": "error", "action": "images", "id": "arrow.jpg"}

Line 4 matches the single URL “/”, and sets both the controller and action to constants. It also has a route name “home”, which can be used in generation. (The other routes have None instead of a name, so they don’t have names. It’s recommended to name all routes that may be used in generation, but it’s not necessary to name other routes.)

Line 6 matches any two-component URL, and line 7 matches any 3-component URL. These are used as catchall routes if we’re too lazy to define a separate route for every action. If you have defined a route for every action, you can delete these two routes.

Note that a URL “/error/images/arrow.jpg” could match both line 3 and line 7. The mapper resolves this by trying routes in the order defined, so this URL would match line 3.

If no routes match the URL, the mapper returns a “match failed” condition, which is seen in Pylons as HTTP 404 “Not Found”.

Here are some more examples of valid routes:

m.connect("/feeds/{category}/atom.xml", controller="feeds", action="atom")
m.connect("history", "/archives/by_eon/{century}", controller="archives",
          action="aggregate")
m.connect("article", "/article/{section}/{slug}/{page}.html",
          controller="article", action="view")

Extra variables may be any Python type, not just strings. However, if the route is used in generation, str() will be called on the value unless the generation call specifies an overriding value.

Other argument syntaxes are allowed for compatibility with earlier versions of Routes. These are described in the Backward Compatibility section.

Route paths should always begin with a slash (“/”). Earlier versions of Routes allowed slashless paths, but their behavior now is undefined.

Requirements

It’s possible to restrict a path variable to a regular expression; e.g., to match only a numeric component or a restricted choice of words. There are two syntaxes for this: inline and the requirements argument. An inline requirement looks like this:

map.connect(R"/blog/{id:\d+}")
map.connect(R"/download/{platform:windows|mac}/{filename}")

This matches “/blog/123” but not “/blog/12A”. The equivalent requirements syntax is:

map.connect("/blog/{id}", requirements={"id": R"\d+"}
map.connect("/download/{platform}/{filename}",
    requirements={"platform": R"windows|mac"})

Note the use of raw string syntax (R"") for regexes which might contain backslashes. Without the R you’d have to double every backslash.

Another example:

m.connect("/archives/{year}/{month}/{day}", controller="archives",
          action="view", year=2004,
          requirements=dict(year=R"\d{2,4}", month=R"\d{1,2}"))

The inline syntax was added in Routes (XXX 1.10?? not in changelog). Previous versions had only the requirements argument. Two advantages of the requirements argument are that if you have several variables with identical requirements, you can set one variable or even the entire argument to a global:

NUMERIC = R"\d+"
map.connect(..., requirements={"id": NUMERIC})

ARTICLE_REQS = {"year": R"\d\d\d\d", "month": R"\d\d", "day": R"\d\d"}
map.connect(..., requirements=ARTICLE_REQS)

Because the argument requirements is reserved, you can’t define a routing variable by that name.

Magic path_info

If the “path_info” variable is used at the end of the URL, Routes moves everything preceding it into the “SCRIPT_NAME” environment variable. This is useful when delegating to another WSGI application that does its own routing: the subapplication will route on the remainder of the URL rather than the entire URL. You still need the “:.*” requirement to capture the following URL components into the variable.

map.connect(None, "/cards/{path_info:.*}",
    controller="main", action="cards")
# Incoming URL "/cards/diamonds/4.png"
=> {"controller": "main", action: "cards", "path_info": "/diamonds/4.png"}
# Second WSGI application sees:
# SCRIPT_NAME="/cards"   PATH_INFO="/diamonds/4.png"

This route does not match “/cards” because it requires a following slash. Add another route to get around this:

map.connect("cards", "/cards", controller="main", action="cards",
    path_info="/")

Tip

You may think you can combine the two with the following route:

map.connect("cards", "/cards{path_info:.*}",
    controller="main", action="cards")

There are two problems with this, however. One, it would also match “/cardshark”. Two, Routes 1.10 has a bug: it forgets to take the suffix off the SCRIPT_NAME.

A future version of Routes may delegate directly to WSGI applications, but for now this must be done in the framework. In Pylons, you can do this in a controller action as follows:

from paste.fileapp import DirectoryApp
def cards(self, environ, start_response):
    app = DirectoryApp("/cards-directory")
    return app(environ, start_response)

Or create a fake controller module with a __controller__ variable set to the WSGI application:

from paste.fileapp import DirectoryApp
__controller__ = DirectoryApp("/cards-directory")

Conditions

Conditions impose additional constraints on what kinds of requests can match. The conditions argument is a dict with up to three keys:

method

A list of uppercase HTTP methods. The request must be one of the listed methods.

sub_domain

Can be a list of subdomains, True, False, or None. If a list, the request must be for one of the specified subdomains. If True, the request must contain a subdomain but it can be anything. If False or None, do not match if there’s a subdomain.

New in Routes 1.10: ``False`` and ``None`` values.

function

A function that evaluates the request. Its signature must be func(environ, match_dict) => bool. It should return true if the match is successful or false otherwise. The first arg is the WSGI environment; the second is the routing variables that would be returned if the match succeeds. The function can modify match_dict in place to affect which variables are returned. This allows a wide range of transformations.

Examples:

# Match only if the HTTP method is "GET" or "HEAD".
m.connect("/user/list", controller="user", action="list",
          conditions=dict(method=["GET", "HEAD"]))

# A sub-domain should be present.
m.connect("/", controller="user", action="home",
          conditions=dict(sub_domain=True))

# Sub-domain should be either "fred" or "george".
m.connect("/", controller="user", action="home",
          conditions=dict(sub_domain=["fred", "george"]))

# Put the referrer into the resulting match dictionary.
# This function always returns true, so it never prevents the match
# from succeeding.
def referals(environ, result):
    result["referer"] = environ.get("HTTP_REFERER")
    return True
m.connect("/{controller}/{action}/{id}",
    conditions=dict(function=referals))

Wildcard routes

By default, path variables do not match a slash. This ensures that each variable will match exactly one component. You can use requirements to override this:

map.connect("/static/{filename:.*?}")

This matches “/static/foo.jpg”, “/static/bar/foo.jpg”, etc.

Beware that careless regexes may eat the entire rest of the URL and cause components to the right of it not to match:

# OK because the following component is static and the regex has a "?".
map.connect("/static/{filename:.*?}/download")

The lesson is to always test wildcard patterns.

Format extensions

A path component of {.format} will match an optional format extension (e.g. “.html” or “.json”), setting the format variable to the part after the “.” (e.g. “html” or “json”) if there is one, or to None otherwise. For example:

map.connect('/entries/{id}{.format}')

will match “/entries/1” and “/entries/1.mp3”. You can use requirements to limit which extensions will match, for example:

map.connect('/entries/{id:\d+}{.format:json}')

will match “/entries/1” and “/entries/1.json” but not “/entries/1.mp3”.

As with wildcard routes, it’s important to understand and test this. Without the \d+ requirement on the id variable above, “/entries/1.mp3” would match successfully, with the id variable capturing “1.mp3”.

New in Routes 1.12.

Submappers

A submapper lets you add several similar routes without having to repeat identical keyword arguments. There are two syntaxes, one using a Python with block, and the other avoiding it.

# Using 'with'
with map.submapper(controller="home") as m:
    m.connect("home", "/", action="splash")
    m.connect("index", "/index", action="index")

# Not using 'with'
m = map.submapper(controller="home")
m.connect("home", "/", action="splash")
m.connect("index", "/index", action="index")

# Both of these syntaxes create the following routes::
# "/"      => {"controller": "home", action="splash"}
# "/index" => {"controller": "home", action="index"}

You can also specify a common path prefix for your routes:

with map.submapper(path_prefix="/admin", controller="admin") as m:
    m.connect("admin_users", "/users", action="users")
    m.connect("admin_databases", "/databases", action="databases")

# /admin/users     => {"controller": "admin", "action": "users"}
# /admin/databases => {"controller": "admin", "action": "databases"}

All arguments to .submapper must be keyword arguments.

The submapper is not a complete mapper. It’s just a temporary object with a .connect method that adds routes to the mapper it was spawned from.

New in Routes 1.11.

Submapper helpers

Submappers contain a number of helpers that further simplify routing configuration. This:

with map.submapper(controller="home") as m:
    m.connect("home", "/", action="splash")
    m.connect("index", "/index", action="index")

can be written:

with map.submapper(controller="home", path_prefix="/") as m:
    m.action("home", action="splash")
    m.link("index")

The action helper generates a route for one or more HTTP methods (‘GET’ is assumed) at the submapper’s path (‘/’ in the example above). The link helper generates a route at a relative path.

There are specific helpers corresponding to the standard index, new, create, show, edit, update and delete actions. You can use these directly:

with map.submapper(controller="entries", path_prefix="/entries") as entries:
    entries.index()
    with entries.submapper(path_prefix="/{id}") as entry:
        entry.show()

or indirectly:

with map.submapper(controller="entries", path_prefix="/entries",
                   actions=["index"]) as entries:
    entries.submapper(path_prefix="/{id}", actions=["show"])

Collection/member submappers nested in this way are common enough that there is helper for this too:

map.collection(collection_name="entries", member_name="entry",
               controller="entries",
               collection_actions=["index"], member_actions["show"])

This returns a submapper instance to which further routes may be added; it has a member property (a nested submapper) to which which member-specific routes can be added. When collection_actions or member_actions are omitted, the full set of actions is generated (see the example under “Printing” below).

See “RESTful services” below for map.resource, a precursor to map.collection that does not use submappers.

New in Routes 1.12.

Adding routes from a nested application

New in Routes 1.11. Sometimes in nested applications, the child application gives the parent a list of routes to add to its mapper. These can be added with the .extend method, optionally providing a path prefix:

from routes.route import Route
routes = [
    Route("index", "/index.html", controller="home", action="index"),
    ]

map.extend(routes)
# /index.html => {"controller": "home", "action": "index"}

map.extend(routes, "/subapp")
# /subapp/index.html => {"controller": "home", "action": "index"}

This does not exactly add the route objects to the mapper. It creates identical new route objects and adds those to the mapper.

New in Routes 1.11.