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

If it’s named (e.g. *foo), it will be passed by keyword argument to the controller.

An unnamed asterisk (not immediately followed by an identifier) will invoke the the traverser. The publisher calls the traverser’s resolve method with the path segments (a tuple) and passes the result to the controller as the first positional argument (before the request argument).

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. \*.

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 traversal 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(traverser=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(traverser=None)

HTTP publisher.

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

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

__init__(traverser=None)

The optional traverser argument specifies the default route traverser.

connect(path, controller=None, traverser=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, traverser=None)

Bases: otto.router.Route

Route which integrates with publisher.

__init__(path, controller=None, traverser=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).