Chapter 9: URLs, Routing and Dispatch

Pylons Dispatch

Once a URL has been matched against a route and the controller has been verified to exist, Pylons checks to see whether it can find the action.

Pylons is set up so that any controller methods that start with an _ character are not considered actions at all and cannot be called as a result of a URL dispatch. If the action specified in the routing variables doesn’t exist or it starts with an _ character, then the check fails. In debug mode for development, this raises an exception to explain the mistake; in production mode, it simply results in a 404 Not Found error page being displayed.

If the controller and action both exist, then Pylons looks for a __before__() method attached to the controller class. If the method exists, it is executed. The __before__() method can therefore be used to set up per-request objects or perform other processing to be carried out before each action in the controller is called.

Next, Pylons inspects the action to see what arguments it takes and calls it in such a way that any arguments that have the same names as the routing variables are called with the value of the routing variable as the argument. Here are some examples:

# No routing variables used in the action
def no_routing_variables(self):
    return 'No routing variables used'

# Populate the ``id`` with the value of the ``id`` routing variable
def id_present(self, id):
    return 'The id is %s' % id

In addition to routing variables, you can also specify both environ and start_response as arguments in your actions. The environ argument will get populated with the same WSGI environment dictionary you can access via the Pylons request global as request.environ, and the start_response() callable is a WSGI callable you’ll learn about in Chapter 16. Both environ and start_response get added as attributes to the template context global c in the same way as the routing variables do if you use them in an action. To see all these features in action, consider the following example. When the test() action is called, the browser will display True, True, True, True:

def __before__(self, id):
    c.id_set_in_before = id

def test(self, environ, start_response, controller, id):
    w = c.id_set_in_before == id
    x = c.environ == environ == request.environ
    y = c.start_response == start_response
    z = c.controller == controller
    request.content_type = 'text/plain'
    return "%s %s, %s, %s"%(w, x, y, z)

After an action is called, Pylons looks for an __after__() method attached to the controller, and if it exists, it is called too. You can use __after__() for performing any cleanup of objects you created in the __before__() method.

Both the __before__() and __after__() methods can also accept any of the routing variable names as arguments in exactly the same way as the controller action can.

Of course, there are occasions where it is useful to be able to access the routing variables outside your controller code. All the routing variables are available in the request.urlvars dictionary and are also available in request.environ["wsgiorg.routing_args"].

Route Parts

As you’ve already seen, a route is specified by arguments to map.connect() that include a route path and a number of options. The route path itself can consist of a number of different types of parts between / characters:

Static parts

These are plain-text parts of the URL that don’t result in any route variables being defined. In the default Pylons setup, the string error in the route path /error/{action} is a static part.

Dynamic parts

The text in the URL matching the dynamic part is assigned to a routing variable of that name. Dynamic parts are marked in the route path as the routing variable name within curly brackets. In the default Pylons setup, the string {action} in the route path /error/{action} is a dynamic part. Dynamic parts can also be specified by the routing variable name preceded by a colon, which is the style used in earlier versions of Routes. For example, you could change the first error route path from /error/{action} to /error/:action, and it would still work.

Wildcard parts

A wildcard part will match everything (including / characters) except the other parts around it. Wildcard parts are marked in the route path by preceding them with the * character. The default Pylons setup doesn’t include any routes that use wildcard parts, but you can use them in your own routes if you need to do so.

To demonstrate the different types of route parts, consider the following URL:

/wiki/page/view/some/variable/depth/file.html

and a route path to match it, which includes a wildcard part:

/wiki/{controller}/{action}/*url

In this case, wiki is treated as a static part, and page is a dynamic part that is assigned to the controller route variable. In Routes, / characters separating dynamic or wildcard parts are not treated as static parts, so the next / is ignored. view is a dynamic part assigned to the action route variable. The following / is also ignored, and the whole of the rest of the URL is considered a wildcard part and assigned to the url route variable.

Any URL starting with /wiki/ followed by two sets of characters, each followed by a / character, will be matched by this route path as long as the controller exists.

Let’s test this with a simple example. Rather than modifying the SimpleSite project, you can set up your own route map directly. You just have to specify a dummy controller_scan function to return a list of valid controllers. In the example, map.minimization is set to False so that the route map is set up in the same way it would be in a Pylons application. The controller_scan() function will just return ['error', 'page'] to simulate that only the page and error controllers exist. Here’s what the route map looks like:

>>> def controller_scan(directory=None):
>>>     return ['error', 'page']
...
>>> from routes import Mapper
>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = False
>>> map.connect('/wiki/{controller}/{action}/*url')
>>> print map.match('/wiki/page/view/some/variable/depth/file.html')
{'action': u'view', 'url': u'some/variable/depth/file.html', 'controller': u'page'}

The URL is matched as expected. Let’s try to match some different URLs:

>>> print map.match('/some/other/url')
None
>>> print map.match('/wiki/folder/view/some/variable/depth/file.html')
None

Notice that if the URL doesn’t match or if the matched controller doesn’t exist, the route is not matched, and the map.match() function returns None.

The Pylons implementation of Routes doesn’t require the dynamic and wildcard portions of the route path to be separated by a / character. Here you’re using a . character as a separator. Note that you need to create a new Mapper to set this new route because you have already called map.connect() on the previous one. Once again, you use the dummy controller_scan() function and set map.minimization = False to turn off minimization in the same way as the Pylons setup:

>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = False
>>> map.connect('/blog/{controller}.{action}.*url')
>>> print map.match('/blog/page.view.some/variable/depth/file.html')
{'action': u'view', 'url': u'some/variable/depth/file.html', 'controller': u'page'}

As these examples have demonstrated, you can think of wildcard parts as being very much like dynamic parts but also matching / characters.

Although wildcard parts are a powerful tool, they generally aren’t used very often and can be a sign that you haven’t designed your routes very well. The risk is that because they match any character including /, they will match very many URLs. If you were to have a wildcard route near the top of your route map, it could easily match URLs for which there was a more specific route later in the route map. The vast majority of the time you will just use static and dynamic parts in your route paths, but if you do use wildcard routes, they should always be placed near the bottom of the route map to avoid them accidentally matching URLs when there is a more specific route later in the map.

These are three cases when you might choose to use wildcard routes:

• When an entire portion of the URL is going to be passed to another application (for example, Paste’s static file server)

• When you are trying to match a string ID that might include / characters

• When you want to pass the entire request URL to a particular action to handle an error condition, rather than allowing a 404 Not Found error page to be returned

Default Variables

With the knowledge you’ve already gained, you will be able to create most of the routes you are likely to need, but there is one problem. Every route matched must result in at least the routing variables controller and action being assigned a value, but URLs such as / don’t contain enough characters to be able to deduce the controller and action names from them.

To solve this problem, Routes allows you to specify default values for any routing variables as part of the routing map’s connect() function. You’ve already seen default variables in action during the discussion of Pylons’ error route, but let’s look at another example:

>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = False
>>> map.connect('/archives/by_eon/{century}', controller='page', action='list')

In this example, the controller and action both have default values, so they are called default variables. You’ll notice that you can’t create a URL that will affect the value of the controller and action variables since they aren’t present in the route path, so their default values of 'page' and 'list' will always be used. Such variables are known as hard-coded variables.

The value assigned to the century routing variable will depend on the URL with which it is matched:

>>> print map.match('/archives/by_eon/')
None
>>> print map.match('/archives/by_eon')
None
>>> print map.match('/archives/by_eon/1800')
{'action': u'list', 'controller': u'page', 'century': u'1800'}

It is possible to take the use of default variables to an extreme. A route where the controller and action are hard-coded is known as an explicit route. Here’s an example:

map.connect('/blog/view/1', controller='blog', action='view', id=1)

Here the whole route path is made only from static parts, and all the routing variables are hard-coded as default variables. The benefit of this approach is that only one URL will ever match this route, but the drawback is that defining all your URLs this way requires adding an awful lot of routes to your application.

Named Routes

If you are regularly using the same route in your application, it can quickly become tedious to type all the routing variables every time you want to use h.url_for(). This is where named routes come in. A named route is like an ordinary route, but you access it directly via a name.

Here’s an example:

map.connect('category_home', 'category/{section}', controller='blog', action='view',
          section='home')

Then in your Pylons application you might use this:

h.url_for('category_home')

This is equivalent to generating the URL using the routing variables in full, both generate the URL /category/home:

h.url_for(controller='blog', action='view', section='home')

As you can see, this saves a bit of typing. You can also specify keyword arguments, and it will override defaults associated with the route name. The following:

h.url_for('category_home', section='admin')

generates the URL /category/admin and is equivalent to this:

h.url_for(controller='blog', action='view', section='admin')

Static Named Routes

Routes also supports a feature called static named routes. These are routes that do not involve actual URL generation but instead allow you to quickly alias common URLs that are external to your site. To make a route static, you add _static=True as an argument. For example, if your route map contained this:

map.connect('google_search', 'http://www.google.com/search', _static=True)

you could now reference http://www.google.com/search by typing this in your application:

h.url_for('google_search')

This is especially useful if you are accessing resources throughout your application that you think might change because it means you have to change the URL in only one place. Static named routes are ignored entirely when matching a URL.

Internal Static Routes

You can also use h.url_for() to reference static resources in your project’s public directory. Routes will automatically prepend the URL you give it with the proper SCRIPT_NAME so that even if you are running your Pylons application under a different URL, the correct URL will be generated. For example, if your Pylons application was mounted at /forms and you used this in your application, the URL /forms/css/source.css would be correctly generated with this code:

h.url_for('/css/source.css')

For portable web applications, it’s highly encouraged that you use h.url_for() for all your URLs, even those that are static resources and images. This will ensure that the URLs are properly handled in any of the possible deployment setups you could use for your application.

Route Minimization

Previous versions of Pylons had a feature called route minimization enabled by default. Route minimization allowed you to specify optional default variables for a particular route. To demonstrate route minimization, let’s look at the previous example again but this time with minimization enabled and with an optional default variable, century:

>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = True
>>> map.connect('/archives/by_eon/{century}', controller='page',
...      action='aggregate', century=1800)
>>> print map.match('/archives/by_eon/')
{'action': u'aggregate', 'controller': u'page', 'century': u'1800'}
>>> print map.match('/archives/by_eon')
{'action': u'aggregate', 'controller': u'page', 'century': u'1800'}
>>> print map.match('/archives/by_eon/1800')
{'action': u'aggregate', 'controller': u'page', 'century': u'1800'}

Notice this time that all three URLs result in a match, even though two of them don’t have a part of the URL that could correspond to the century dynamic part. This is because with minimization enabled, Routes assumes you want to use the optional default variables automatically if they aren’t specified in the URL.

Here are some of the reasons why route minimization is a bad idea:

• It means multiple URLs serve the same page, which as explained earlier is bad for caches and search engine rankings.

• It makes it difficult to choose which URL should be generated for a particular action when using h.url_for(), so Routes always generates the shortest URL with minimization enabled.

• Complex routes and many defaults can make it hard to predict which route will be matched.

It is recommended that you leave route minimization disabled by keeping map.minimization set to False at the top of your route map.

Route Memory

One feature of Routes that was designed to make your life as a developer easier was called route memory. When your controller and action are matched from the URL, the routing variables that are set get remembered for the rest of that request. This means that when you are using h.url_for(), you actually only need to specify routing variables, that are different from the ones matched in the current request.

Consider this route:

map.connect('/archives/{year}/{month}/{day}', controller='page', action='view')

If the URL /archives/2008/10/4 was entered, this route would match the following variables:

{'controller': 'page', 'action': 'view', 'year': '2008', 'month': '10', 'day': '4'}

With these routing variables matched, h.url_for() would generate the following results:

h.url_for(day=6)          # =>     /page/2008/10/6
h.url_for(month=4)        # =>     /page/2008/4/4
h.url_for(year=2009)      # =>     /page/2009/10/4

The majority of times you use h.url_for() will be in view templates. Since the same template is often called from multiple different controllers and actions, you can’t always rely on h.url_for() generating the same URL in the same template, and this can introduce unexpected bugs, so it is usually much better to specify all your routing arguments explicitly.

There is another problem with route memory. Consider a route map set up with the following routes:

map.connect('/{controller}/{action}')
map.connect('/{controller}/{action}/{id}')

With route memory enabled, let’s imagine someone visited the URL /page/view/1. Here are the routing variables that would be matched:

{'controller': 'page', 'action': 'view', 'id': '1'}

Now try to work out which URL would be generated with this code:

h.url_for(controller='page', action='new')

The result is /page/new/1 even though the new() action might not take an id argument. This means that in order to have this matched by the first route to generate the URL /page/new, you would have to explicitly specify id=None like this:

h.url_for(controller='page', action='new', id=None)

You may not have noticed, but this is exactly what you did in the footer for the SimpleSite view.html template in Chapter 8. If route memory was disabled globally, you would not have had to specify id=None for the new(), list(), or delete() action routes.

As well as explicitly setting a routing variable to None, you can also disable route memory on a per-call basis by specifying the controller starting with a / character. For example:

h.url_for(controller='/page', action='new')

This is not ideal either, though. To avoid this complication, it is highly recommended that you disable route memory completely and always specify all arguments to h.url_for() explicitly. You can do this by passing explicit=True to the Mapper() constructor in your project’s config/routing.py. This will ensure route memory isn’t used, and you will have to explicitly specify each routing variable in every call to h.url_for():

map = Mapper(directory=config['pylons.paths']['controllers'],
      always_scan=config['debug'], explicit=True)

If you should choose not to disable the route memory feature, you should be aware that it works only with h.url_for() and not with its counterpart redirect_to().

Implicit Defaults

Routes has a surprising legacy feature that means that if you don’t specify a controller and an action for a particular route, the implicit defaults of controller='content' and action='index' will be used for you. This can be demonstrated very simply:

>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = False
>>> map.connect('/archives/')
>>> print map.match('/archives/')
{'action': u'index', 'controller': u'content'}

It is highly unlikely you want Routes to make up action and controller variables for you, so it’s strongly recommended that you disable this feature. You can do this by passing _explicit=True as an argument to the individual routes you want implicit defaults to be disabled for:

>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = False
>>> map.connect('/archives/', _explicit=True)
>>> print map.match('/archives/')
None

In reality, it is likely you will want these implicit defaults disabled for all your routes. Luckily, the explicit=True option you passed to the Mapper() object to disable route memory also disables implicit defaults, which is another reason to use it.

Best Practice

With route minimization, route memory, and implicit defaults disabled, the way you use Routes in your application might be quite different from the way you used it in previous versions of Pylons. To demonstrate this, let’s look at an old routing structure that you might have used in Pylons 0.9.6:

>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimize = True
>>> map.connect(':controller/:action/:id', controller='blog', action='view', id=1)

Here minimization is enabled as well as implicit routes and route memory. Look how many different URLs match the same controller, action, and ID. This clearly breaks the URL disambiguation rule listed earlier in the “Choosing Good URLs” section:

>>> print map.match('/blog/view/1/')
{'action': u'view', 'controller': u'blog', 'id': u'1'}
>>> print map.match('/blog/view/1')
{'action': u'view', 'controller': u'blog', 'id': u'1'}
>>> print map.match('/blog/view/')
{'action': u'view', 'controller': u'blog', 'id': u'1'}
>>> print map.match('/blog/view')
{'action': u'view', 'controller': u'blog', 'id': u'1'}
>>> print map.match('/blog/')
{'action': u'view', 'controller': u'blog', 'id': u'1'}
>>> print map.match('/blog')
{'action': u'view', 'controller': u'blog', 'id': u'1'}
>>> print map.match('/')
{'action': u'view', 'controller': u'blog', 'id': u'1'}

With route minimization, route memory, and implicit defaults disabled, you would have to add the following routes to achieve the same effect:

>>> map = Mapper(controller_scan=controller_scan, explicit=True)
>>> map.minimize = False
>>> map.connect('/', controller='blog', action='view', id=1)
>>> map.connect('/{controller}', action='view', id=1)
>>> map.connect('/{controller}/', action='view', id=1)
>>> map.connect('/{controller}/{action}', id=1)
>>> map.connect('/{controller}/{action}/', id=1)
>>> map.connect('/{controller}/{action}/{id}')
>>> map.connect('/{controller}/{action}/{id}/')

Of course, as has been mentioned, it is generally a bad idea to have more than one URL map to the same resource, so you are unlikely to want to do this in most applications. Even if you did want to do this, the explicit approach requires a lot more typing, but it is also much clearer what is happening. Although using explicit routes can sometimes mean more typing, being explicit about what you expect to happen makes life much easier when you have more complicated route setups.

Disabling route memory, implicit defaults, and route minimization also requires you to do more work when generating URLs, but once again, this will prevent you from finding obscure URL generation problems later in a project. To generate the URL to view the blog post with ID 1 and with the explicit argument set to True, you would always have to type the following, no matter which routing variables were generated for the request that calls the code:

h.url_for(controller='blog', action='view', id=1)

This would generate the URL / because this is the first route to match. Since routes are matched from top to bottom, if you wanted this to generate the URL /blog/view/1 instead you could move the second-to-last route to the top so that it was matched first. This would affect the way URLs were generated for other controllers too, though:

>>> map = Mapper(controller_scan=controller_scan, explicit=True)
>>> map.minimize = False
>>> map.connect('/{controller}/{action}/{id}')
>>> map.connect('/', controller='blog', action='view', id=1)
>>> map.connect('/{controller}', action='view', id=1)
>>> map.connect('/{controller}/', action='view', id=1)
>>> map.connect('/{controller}/{action}', id=1)
>>> map.connect('/{controller}/{action}/', id=1)
>>> map.connect('/{controller}/{action}/{id}/')

Alternatively, you could add an explicit route as the first route. You’ll remember from the discussion of default variables earlier in the chapter that an explicit route matches only one URL:

>>> map = Mapper(controller_scan=controller_scan, explicit=True)
>>> map.minimize = False
>>> map.connect('/blog/view/1', controller='blog', action='view', id=1)
>>> map.connect('/', controller='blog', action='view', id=1)
>>> map.connect('/{controller}', action='view', id=1)
>>> map.connect('/{controller}/', action='view', id=1)
>>> map.connect('/{controller}/{action}', id=1)
>>> map.connect('/{controller}/{action}/', id=1)
>>> map.connect('/{controller}/{action}/{id}')
>>> map.connect('/{controller}/{action}/{id}/')

Some people would argue that you should always specify the controller and action for every URL as hard-coded default variables using an explicit or named route. There are some other advantages to this approach:

• Temporarily blocking access to a particular controller can be difficult with nonexplicit routes because it isn’t always obvious whether another route you have specified will also resolve the URL to the controller. If you have named or explicit routes, you can just comment out the routes that point at the controller in question, and you’re all set.

• Imagine you have a Pylons application that is a couple of years old and has an established group of users who have bookmarked various parts of your site. If you were to refactor the application, moving controllers around or putting certain actions in different controllers, you would find it difficult to maintain the existing URL structure if you were using implicit routes. With explicit or named routes, you could simply update where the URL pointed to so that the old URLs would still work.

I hope what is clear from the discussion in this section is that you should always set explicit=True in your Mapper to disable route memory and implicit defaults and that you should disable route minimization with map.minimization=False, but it is up to you whether you choose to go further and be even more explicit about your routes with hard-coded defaults for the controller and action or named routes.

Only you can decide whether ordinary, explicit, or named routes are the correct choice for your application. Ordinary routes that use the “convention over configuration” philosophy don’t result in disambiguated URLs. Named and explicit routes give you complete control over how your URLs are generated but are more effort to set up. The nice thing about Routes is, of course, that you can use all three techniques together.

Requirements

Any route you specify can have a requirement argument specified as a keyword to the map’s connect() method. The requirement argument should be a dictionary of routing variable names for any dynamic or wildcard parts and a corresponding regular expression to match their values against. Regular expressions are documented in the Python documentation for the re module. Any valid Python regular expression can be used.

Here’s an example:

map.connect('archives/{year}/{month}/{day}', controller='archives', action='view',
    year=2004,requirements={'year': '\d{2,4}', 'month': '\d{1,2}'})

One particularly useful regular expression used in the previous example is \d, which matches a digit. In this case, the year can be either two or four digits long, and the month can be one or two digits long.

Here’s another example; this time we are ensuring the theme is one of the allowed themes:

theme_map = 'admin|home|members|system'
map.connect('users/{theme}/edit', controller='users',
    requirements={'theme': theme_map})

Conditions

Conditions specify a set of special conditions that must be met for the route to be accepted as a valid match for the URL. The conditions argument must always be a dictionary and can accept three different keys:

method

The request must be one of the HTTP methods defined here. This argument must be a list of HTTP methods and should be uppercase.

function

This is a function that will be used to evaluate whether the route is a match. This must return True or False and will be called with environ and match_dict as arguments. The match_dict is a dictionary with all the routing variables for the request. Any modifications your function makes to the match_dict will be picked up by Routes and used as the routing variables from that point on.

sub_domain

If this is present, it should be either True (which will match any subdomain) or a Python list of subdomain strings, one of which must match the subdomain used in the request for the route to match.

These three types of conditions can all be used together in the same route by specifying each argument to the conditions dictionary, but I’ll discuss them each in turn.

Let’s deal with the method option first. This allows you to match a URL based on the HTTP method the request was made with. One problem with testing examples using the method condition is that the match depends on information from the WSGI environment, which is usually set during a request. Since there isn’t a real HTTP request for this test code, you have to emulate it, so in the following examples you set map.environ with fake environment information to test how the matching works. Obviously, you wouldn’t do this in your own code. The example also sets up a new controller_scan() function which only accepts the value user for the controller:

>>> from routes import Mapper
>>> def controller_scan(directory=None):
>>>     return ['user']
...
>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = False
>>> map.connect('/user/new/preview', controller='user', action='preview',
...      conditions=dict(method=['POST']))
>>> # The method to be either GET or HEAD
>>> map.connect('/user/list', controller='user', action='list',
...     conditions=dict(method=['GET', 'HEAD']))
>>> map.environ = {'REQUEST_METHOD':'POST'}
>>> print map.match('/user/new/preview')
{'action': u'preview', 'controller': u'user'}
>>> print map.match('/user/list')
None
>>> map.environ = {'REQUEST_METHOD':'GET'}
>>> print map.match('/user/new/preview')
None
>>> print map.match('/user/list')
{'action': u'list', 'controller': u'user'}

As you can see, the method condition works as expected, allowing the routes to match only when the request contains the correct request method.

Now let’s look at the function condition. This condition is extremely powerful because it effectively allows you to write custom code to extend Routes’ functionality. The function can return True to indicate the route matches or False if it doesn’t. The function also has full access to the WSGI environment and the dictionary of routing variables, which have already been matched, so the function is free to modify or add to them as well.

Here’s an example of a function that extracts the action to be called from the X-ACTION HTTP header in the request and compares it to allowed values:

from webob import Request
def get_action(environ, result):

    # Create a Pylons-style request object from the environment for
    # easier manipulation
    req = Request(environ)

    action = req.GET.get('X-ACTION')
    if action in ['call', 'get', 'view']:
        result['action'] = action
        return True

    return False

You wouldn’t often design this sort of functionality into your routes if you were creating your own application from scratch, but having such low-level access to the underlying details of the request is very powerful and can be useful when writing a Pylons application to replace legacy code.

Here is another use that might be useful in your application, this time to treat the referrer as an ordinary routing variable:

def referals(environ, result):
    result['referer'] = environ.get('HTTP_REFERER')
    return True

You could use this function in a route like this to add the referrer to the matched routing variables:

map.connect('/{controller}/{action}/{id}', conditions=dict(function=referals))

Now let’s think about subdomains. These are easiest to demonstrate with examples, and once again you have to create a fake HTTP request environment for your examples to emulate requests coming from different subdomains.

First let’s set up the map object. Notice that you specify map.sub_domains=True to enable subdomain support:

>>> from routes import Mapper
>>> def controller_scan(directory=None):
...     return ['user']
...
>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = False
>>> map.sub_domains = True

Now let’s set up two routes. The first will accept any subdomain and produce an action routing variable with a value any, and the second will accept only the subdomains foo and bar and will produce an action routing variable certain:

>>> map.connect('/user/any', controller='user', action='any',
... conditions={'sub_domain':True})
>>> map.connect('/user/certain', controller='user', action='certain',
... conditions={'sub_domain': ['foo', 'bar']})

Now let’s attempt some matches, emulating different requests by setting different environ dictionaries. First let’s emulate a domain foo.example.com and test two URLs. The first will test what happens when sub_domain is set to True, and the second will test what happens when it is restricted to ['foo', 'bar']:

>>> map.environ = {'HTTP_HOST':'foo.example.com'}
>>> print map.match('/user/any')
{'action': u'any', 'controller': u'user', 'sub_domain': 'foo'}
>>> print map.match('/user/certain')
{'action': u'certain', 'controller': u'user', 'sub_domain': 'foo'}

As you can see, both the routes match because foo is a valid subdomain for either condition. Notice how 'sub_domain': 'foo' is added to the matched routing variables.

Now let’s try the domain not.example.com:

>>> map.environ = {'HTTP_HOST':'not.example.com'}
>>> print map.match('/user/any')
{'action': u'any', 'controller': u'user', 'sub_domain': 'not'}
>>> print map.match('/user/certain')
None

This time, since not is not one of the allowed domains for the second route, only the first example works. Let’s see what happens if no subdomain is specified in the request:

>>> map.environ = {'HTTP_HOST':'example.com'}
>>> print map.match('/user/any')
None
>>> print map.match('/user/certain')
None

As you can see, neither of the routes matches.

To avoid matching common aliases to your main domain like www, the subdomain support can be set to ignore certain specified subdomains. Here’s an example:

>>> from routes import Mapper
>>> def controller_scan(directory=None):
...     return ['user']
...
>>> map = Mapper(controller_scan=controller_scan)
>>> map.minimization = False
>>> # Remember to turn on sub-domain support
... map.sub_domains = True
>>> # Ignore the ``www`` sub-domain
... map.sub_domains_ignore = ['www']
>>> map.connect('/user/any', controller='user', action='any',
...     conditions=dict(sub_domain=True))
>>> map.connect('/user/certain', controller='user', action='certain',
...     conditions=dict(sub_domain=['www', 'foo']))
>>> map.environ = {'HTTP_HOST':'foo.example.com'}
>>> print map.match('/user/any')
{'action': u'any', 'controller': u'user', 'sub_domain': 'foo'}
>>> print map.match('/user/certain')
{'action': u'certain', 'controller': u'user', 'sub_domain': 'foo'}
>>> map.environ = {'HTTP_HOST':'www.example.com'}
>>> print map.match('/user/any')
None
>>> print map.match('/user/certain')
None

You can see that requests to the www subdomain are not matched even if one of the conditions specifies that the subdomain www should be matched. Now let’s look at how h.url_for() handles subdomains.

When subdomain support is on, the h.url_for() function will accept a sub_domain keyword argument. Routes then ensures that the generated URL has the subdomain indicated. For example:

h.url_for(controller='user', action='certain', sub_domain='foo')

would generate the following URL but it will only work during a Pylons request, not from the interactive Python session we've been using so far in this chapter:

http://foo.example.com/user/certain

Filter Functions

Named routes can have functions associated with them that will operate on the arguments used during generation. Filter functions don’t work with implicit or explicit routes because the filter function itself can affect the route that actually gets chosen, so the only way to be explicit about which route to use is to specify it with a name.

To highlight the problem filter functions solve, consider this route:

map.connect('/archives/{year}/{month}/{day}', controller='archives',
          action='view', year=2008,
          requirements=dict(year='\d{2,4}', month='\d{1,2}'))

Generating a URL for this will require a month and day argument and a year argument if you don’t want to use 2008. Imagine this route links to a story and that your model has a story object with year, month, and day attributes. You could generate a URL for the story like this:

h.url_for(year=story.year, month=story.month, day=story.day)

This isn’t terribly convenient and can be brittle if for some reason you need to change the story object’s interface. It would be useful to be able to pass the story object directly to h.url_for() and have Routes extract the information it requires automatically. You can do this with a filter function.

Here’s what the filter function for the story object might look like:

def story_expand(result):
    # Only alter args if a story keyword arg is present
    if 'story' not in result:
        return result

    story = result.pop('story')
    result['year'] = story.year
    result['month'] = story.month
    result['day'] = story.day

    return result

You can then create a named route with a _filter argument like this:

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

This filter function will be used when using the named route archives. If a story keyword argument is present, it will use that and alter the keyword arguments used to generate the actual route.

If you have a story object with those attributes, you would now be able to generate a URL like this:

h.url_for('archives', story=my_story)

As well as making it substantially easier to generate the URL, you can also easily change how the arguments are pulled out of the story object simply by changing the filter function if the story object interface were ever to change.

Although filter functions can be very powerful, you might decide against using them in your application because they can also make it less obvious what is happening to generate your URLs.