Reference

Routes

Match dictionary

Expressions on the form :key match any string and passes the argument by name onto the controller. Examples:

/search/:term
/:category/:id

Match keys must be valid Python variable names.

Note that all values are returned as unquoted unicode strings.

Asterix

The asterisk character "*" matches any number of path segments (non-greedy). Its value is always a tuple of unquoted path segments.

There are two modes of operation. If the asterisk is immediately followed by a Python identifier, it will available from the match dictionary.

An anonymous asterisk invokes the object mapper.

Examples of routes which use the asterisk:

/*
/*path
/*/:version
/documents/*

It is invalid to use more than one asterisk in a route path. Note that the asterisk may be escaped using the backslash character, e.g. \*.

Object mapping

An object mapper can be defined either on the publisher/application or set on individual routes.

It’s function is to map paths to objects and vice-versa.

To invoke the object mapper, routes must include an anonymous asterisk.

Trailing slash

These URLs often indicate a container-like object. Although the two spellings are fungible in the eyes of a web browser, applications should not allow two same documents be returned from different URLs (for both caching and SEO reasons). One variant should redirect to the other – 301 Redirect.

The router comes with support for such redirection. We can demonstrate it with a trivial example:

@app.connect("/")
def controler(request):
    return webob.Response(u"Hello world!")

If we visit the application without a trailing slash, e.g. http://localhost, we should get redirected to the URL that does end in a trailing slash:

301 Moved Permanently
Content-Type: text/html; charset=UTF-8
Content-Length: 0
location: http://localhost/

The browser will follow the redirect to http://localhost/:

200 OK
Content-Type: text/html; charset=UTF-8
Content-Length: 12

Hello world!

Path generation

The path method of the route object returns a path given keyword arguments. If object mapping is used on the route, the path segment tuple should be provided either as the first positional argument (for an unnamed asterisk), or by keyword argument.

Note that for asterisk arguments, either a path segment tuple or string may be provided.

All values should be unicode. The result of the path method is always a quoted string.

Controllers

Type

The type parameter may be used to define a controller which is only available for a particular type. It’s only available for routes which use the asterisk character. Example:

@index.controller('/', type=Document)
def view(context, request):
    ...

API

class otto.Application(mapper=None)

Bases: otto.publisher.Publisher

WSGI-Application.

This class adds a WSGI application interface to the HTTP publisher. The publish method can be overriden to intercept errors (the HTTP exception classes are provided by WebOb).

__call__(environ, start_response)

WSGI application callable.

publish(environ)

Return response for request given by environ.

class otto.Publisher(mapper=None)

HTTP publisher.

The mapper argument is optional; if provided, it will be used as the default mapper.

Route definitions are added using the route method. It takes an optional mapper argument which is then used in place of the default value.

__init__(mapper=None)

The optional mapper argument specifies the default route mapper.

connect(path, controller=None, mapper=None)

Use this method to add routes.

match(path)

Match path with routing table and return route controller.

class otto.Router

Interface to the routing engine.

__call__(path)

Returns an iterator which yields route matches.

connect(route)

Use this method to add routes.

class otto.Route(path)

__init__(path)

Create route given by path.

match(path)

Match the path against the route. Returns a match dictionary or None.

path(**matchdict)

Generate path given **matchdict.

class otto.publisher.Dispatcher(path, controller=None, mapper=None)

Bases: otto.router.Route

Route which integrates with publisher.

__init__(path, controller=None, mapper=None)

bind(type=None)

Return controller; if type is specified, use adaptation on the type hierarchy.

controller(controller=None, type=None)

Register controller for this route; if type is provided, the controller is used only for objects that contain this type in its class hierarchy.

path(context=None, **matchdict)

Generate route path. When traversal is used, context must be provided (usually as first positional argument).