Latest Version: 0.9.6.2

routes

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

Functions

f 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.

f 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).

f 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.

Classes

C Mapper(...) ...

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.

This class contains 2 members.

See the source for more information.

Top