Create a new Mapper instance

All keyword arguments are optional.

controller_scan

Function reference that will be used to return a list of valid controllers used during URL matching. If directory keyword arg is present, it will be passed into the function during its call. This option defaults to a function that will scan a directory for controllers.

directory

Passed into controller_scan for the directory to scan. It should be an absolute path if using the default controller_scan function.

always_scan

Whether or not the controller_scan function should be run during every URL match. This is typically a good idea during development so the server won't need to be restarted anytime a controller is added.

register

Boolean used to determine if the Mapper should use request_config to register itself as the mapper. Since it's done on a thread-local basis, this is typically best used during testing though it won't hurt in other cases.

explicit

Boolean used to determine if routes should be connected with implicit defaults of:

{'controller':'content','action':'index','id':None}

When set to True, these defaults will not be added to route connections and url_for will not use Route memory.

Additional attributes that may be set after mapper initialization (ie, map.ATTRIBUTE = 'something'):

encoding

Used to indicate alternative encoding/decoding systems to use with both incoming URL's, and during Route generation when passed a Unicode string. Defaults to 'utf-8'.

decode_errors

How to handle errors in the encoding, generally ignoring any chars that don't convert should be sufficient. Defaults to 'ignore'.

hardcode_names

Whether or not Named Routes result in the default options for the route being used or if they actually force url generation to use the route. Defaults to False.

Create and connect a new Route to the Mapper.

Usage:

1
2
3
4
5
6
7
8

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

Creates regular expressions for all connected routes

Generate a route from a set of keywords

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

1

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

Match a URL against against one of the routes contained.

Will return None if no valid match is found.

1

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

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"

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'

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.

1

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