routes module

Provides common classes and functions most users will want access to.

class routes.Mapper(controller_scan=<function controller_scan>, directory=None, always_scan=False, register=True, explicit=True)

Basi: SubMapperParent

Mapper handles URL generation and URL recognition in a web application.

Mapper is built handling dictionary’s. It is assumed that the web application will handle the dictionary returned by URL recognition to dispatch appropriately.

URL generation is done by passing keyword parameters into the generate function, a URL is then returned.

connect(*args, **kargs)

Create and connect a new Route to the Mapper.

Usage:

m = Mapper()
m.connect(':controller/:action/:id')
m.connect('date/:year/:month/:day', controller="blog",
          action="view")
m.connect('archives/:page', controller="blog", action="by_page",
requirements = { 'page':'\d{1,2}' })
m.connect('category_list', 'archives/category/:section',
          controller='blog', action='category',
          section='home', type='list')
m.connect('home', '', controller='blog', action='view',
          section='home')

create_regs(*args, **kwargs)

Atomically creates regular expressions for all connected routes

property environ

extend(routes, path_prefix='')

Extends the mapper routes with a list of Route objects

If a path_prefix is provided, all the routes will have their path prepended with the path_prefix.

Example:

>>> map = Mapper(controller_scan=None)
>>> map.connect('home', '/', controller='home', action='splash')
>>> map.matchlist[0].name == 'home'
True
>>> routes = [Route('index', '/index.htm', controller='home',
...                 action='index')]
>>> map.extend(routes)
>>> len(map.matchlist) == 2
True
>>> map.extend(routes, path_prefix='/subapp')
>>> len(map.matchlist) == 3
True
>>> map.matchlist[2].routepath == '/subapp/index.htm'
True

Nota

This function does not merely extend the mapper with the given list of routes, it actually creates new routes with identical calling arguments.

generate(*args, **kargs)

Generate a route from a set of keywords

Returns the url text, or None if no URL could be generated.

m.generate(controller='content',action='view',id=10)

make_route(*args, **kargs)

Make a new Route object

A subclass can override this method to use a custom Route class.

match(url=None, environ=None)

Match a URL against against one of the routes contained.

Will return None if no valid match is found.

resultdict = m.match('/joe/sixpack')

redirect(match_path, destination_path, *args, **kwargs)

Add a redirect route to the mapper

Redirect routes bypass the wrapped WSGI application and instead result in a redirect being issued by the RoutesMiddleware. As such, this method is only meaningful when using RoutesMiddleware.

By default, a 302 Found status code is used, this can be changed by providing a _redirect_code keyword argument which will then be used instead. Note that the entire status code string needs to be present.

When using keyword arguments, all arguments that apply to matching will be used for the match, while generation specific options will be used during generation. Thus all options normally available to connected Routes may be used with redirect routes as well.

Example:

map = Mapper()
map.redirect('/legacyapp/archives/{url:.*}', '/archives/{url}')
map.redirect('/home/index', '/',
             _redirect_code='301 Moved Permanently')

resource(member_name, collection_name, **kwargs)

Generate routes for a controller resource

The member_name name should be the appropriate singular version of the resource given your locale and used with members of the collection. The collection_name name will be used to refer to the resource collection methods and should be a plural version of the member_name argument. By default, the member_name name will also be assumed to map to a controller you create.

The concept of a web resource maps somewhat directly to “CRUD” operations. The overlying things to keep in mind is that mapping a resource is about handling creating, viewing, and editing that resource.

All keyword arguments are optional.

controller

If specified in the keyword args, the controller will be the actual controller used, but the rest of the naming conventions used for the route names and URL paths are unchanged.

collection

Additional action mappings used to manipulate/view the entire set of resources provided by the controller.

Example:

map.resource('message', 'messages', collection={'rss':'GET'})
# GET /message/rss (maps to the rss action)
# also adds named route "rss_message"

member

Additional action mappings used to access an individual “member” of this controllers resources.

Example:

map.resource('message', 'messages', member={'mark':'POST'})
# POST /message/1/mark (maps to the mark action)
# also adds named route "mark_message"

new

Action mappings that involve dealing with a new member in the controller resources.

Example:

map.resource('message', 'messages', new={'preview':'POST'})
# POST /message/new/preview (maps to the preview action)
# also adds a url named "preview_new_message"

path_prefix

Prepends the URL path for the Route with the path_prefix given. This is most useful for cases where you want to mix resources or relations between resources.

name_prefix

Perpends the route names that are generated with the name_prefix given. Combined with the path_prefix option, it’s easy to generate route names and paths that represent resources that are in relations.

Example:

map.resource('message', 'messages', controller='categories',
    path_prefix='/category/:category_id',
    name_prefix="category_")
# GET /category/7/message/1
# has named route "category_message"

requirements

A dictionary that restricts the matching of a variable. Can be used when matching variables with path_prefix.

Example:

map.resource('message', 'messages',
     path_prefix='{project_id}/',
     requirements={"project_id": R"\d+"})
# POST /01234/message
#    success, project_id is set to "01234"
# POST /foo/message
#    404 not found, won't be matched by this route

parent_resource

A dict containing information about the parent resource, for creating a nested resource. It should contain the member_name and collection_name of the parent resource. This dict will be available via the associated Route object which can be accessed during a request via request.environ['routes.route']

If parent_resource is supplied and path_prefix isn’t, path_prefix will be generated from parent_resource as «<parent collection name>/:<parent member name>_id».

If parent_resource is supplied and name_prefix isn’t, name_prefix will be generated from parent_resource as «<parent member name>_».

Example:

>>> from routes.util import url_for
>>> m = Mapper()
>>> m.resource('location', 'locations',
...            parent_resource=dict(member_name='region',
...                                 collection_name='regions'))
>>> # path_prefix is "regions/:region_id"
>>> # name prefix is "region_"
>>> url_for('region_locations', region_id=13)
'/regions/13/locations'
>>> url_for('region_new_location', region_id=13)
'/regions/13/locations/new'
>>> url_for('region_location', region_id=13, id=60)
'/regions/13/locations/60'
>>> url_for('region_edit_location', region_id=13, id=60)
'/regions/13/locations/60/edit'

Overriding generated path_prefix:

>>> m = Mapper()
>>> m.resource('location', 'locations',
...            parent_resource=dict(member_name='region',
...                                 collection_name='regions'),
...            path_prefix='areas/:area_id')
>>> # name prefix is "region_"
>>> url_for('region_locations', area_id=51)
'/areas/51/locations'

Overriding generated name_prefix:

>>> m = Mapper()
>>> m.resource('location', 'locations',
...            parent_resource=dict(member_name='region',
...                                 collection_name='regions'),
...            name_prefix='')
>>> # path_prefix is "regions/:region_id"
>>> url_for('locations', region_id=51)
'/regions/51/locations'

routematch(url=None, environ=None)

Match a URL against against one of the routes contained.

Will return None if no valid match is found, otherwise a result dict and a route object is returned.

resultdict, route_obj = m.match('/joe/sixpack')

class routes.URLGenerator(mapper, environ)

Basi: object

The URL Generator generates URL’s

It is automatically instantiated by the RoutesMiddleware and put into the wsgiorg.routing_args tuple accessible as:

url = environ['wsgiorg.routing_args'][0][0]

Or via the routes.url key:

url = environ['routes.url']

The url object may be instantiated outside of a web context for use in testing, however sub_domain support and fully qualified URL’s cannot be generated without supplying a dict that must contain the key HTTP_HOST.

current(*args, **kwargs)

Generate a route that includes params used on the current request

The arguments for this method are identical to __call__ except that arguments set to None will remove existing route matches of the same name from the set of arguments used to construct a URL.

routes.redirect_to(*args, **kargs)

Issues a redirect based on the arguments.

Redirect’s should occur as a «302 Moved» header, however the web framework may utilize a different method.

All arguments are passed to url_for to retrieve the appropriate URL, then the resulting URL it sent to the redirect function as the URL.

routes.request_config(original=False)

Returns the Routes RequestConfig object.

To get the Routes RequestConfig:

>>> from routes import *
>>> config = request_config()

The following attributes must be set on the config object every request:

mapper

mapper should be a Mapper instance thats ready for use

host

host is the hostname of the webapp

protocol

protocol is the protocol of the current request

mapper_dict

mapper_dict should be the dict returned by mapper.match()

redirect

redirect should be a function that issues a redirect, and takes a url as the sole argument

prefix (optional)

Set if the application is moved under a URL prefix. Prefix will be stripped before matching, and prepended on generation

environ (optional)

Set to the WSGI environ for automatic prefix support if the webapp is underneath a “SCRIPT_NAME”

Setting the environ will use information in environ to try and populate the host/protocol/mapper_dict options if you’ve already set a mapper.

Using your own requst local

If you have your own request local object that you’d like to use instead of the default thread local provided by Routes, you can configure Routes to use it:

from routes import request_config()
config = request_config()
if hasattr(config, 'using_request_local'):
    config.request_local = YourLocalCallable
    config = request_config()

Once you have configured request_config, its advisable you retrieve it again to get the object you wanted. The variable you assign to request_local is assumed to be a callable that will get the local config object you wish.

This example tests for the presence of the “using_request_local” attribute which will be present if you haven’t assigned it yet. This way you can avoid repeat assignments of the request specific callable.

Should you want the original object, perhaps to change the callable its using or stop this behavior, call request_config(original=True).

routes.url_for(*args, **kargs)

Generates a URL

All keys given to url_for are sent to the Routes Mapper instance for generation except for:

anchor          specified the anchor name to be appened to the path
host            overrides the default (current) host if provided
protocol        overrides the default (current) protocol if provided
qualified       creates the URL with the host/port information as
                needed

The URL is generated based on the rest of the keys. When generating a new URL, values will be used from the current request’s parameters (if present). The following rules are used to determine when and how to keep the current requests parameters:

• If the controller is present and begins with “/”, no defaults are used

• If the controller is changed, action is set to “index” unless otherwise specified

For example, if the current request yielded a dict of {“controller”: “blog”, “action”: “view”, “id”: 2}, with the standard “:controller/:action/:id” route, you’d get the following results:

url_for(id=4)                    =>  '/blog/view/4',
url_for(controller='/admin')     =>  '/admin',
url_for(controller='admin')      =>  '/admin/view/2'
url_for(action='edit')           =>  '/blog/edit/2',
url_for(action='list', id=None)  =>  '/blog/list'

Static and Named Routes

If there is a string present as the first argument, a lookup is done against the named routes table to see if there’s any matching routes. The keyword defaults used with static routes will be sent in as GET query arg’s if a route matches.

If no route by that name is found, the string is assumed to be a raw URL. Should the raw URL begin with / then appropriate SCRIPT_NAME data will be added if present, otherwise the string will be used as the url with keyword args becoming GET query args.