route - the routing subsystem

This module is also available under the name r.

import '/dogeweb/r'

handler = r.path ...

WILDCARDRE

A precompiled regular expression that matches wildcards in routes. By default, the syntax is <type:name> or <name> (short for <str:name>.)

wildcards

A dict that maps types to (regex, parser) tuples. regex must be a valid non-compiled (i.e. a string) regular expression that matches whatever parser accepts; parser must be a function that accepts the matched substring and returns some object that will be passed on to the handler.

By default, the following types are supported:

str (any sequence of characters excluding /);
path (any sequence of characters, period);
int (a positive integer).

If the type is not specified, None is used. By default, that’s the same as specifying str.

concrete args path

Sort of a reverse of pathregex; given a dict that maps group names to values and a path route with wildcards, construct a complete path. For example, calling this with {'name': 'spam'} and "/u/<name>/" would result in "/u/spam/".

wraps f g

Basically same thing as functools.update_wrapper (but with reversed order of arguments): this function copies metadata from function f to function g. The only difference is that it does not overwrite attributes already defined on g.

In all of the functions outlined below, a handler is a function that accepts a request as an argument and returns a response (or something else supported by response.responsify.) Optionally, it may also accept some keyword arguments that correspond to wildcards in paths; for example, if you have a route for /u/<name>, its handler must accept a keyword argument name.

If anonymous functions are not your style, all these routers can be used as decorators, too. First, create an instance of the router of your choice:

h = dogeweb.route.path()

Second, add some handlers through the route decorator:

@h.route('/')
def hello(request):
    return 'Hello, World!'

Optionally, add can be used if the function already exists:

h.add('/hello/', 'hello_copy', hello)

Third, use the router as you would a function:

app = dogeweb.app(dogeweb.route.get(h))

The result is roughly equivalent to

app = dogeweb.app $ dogeweb.route.get $ dogeweb.route.path
  '/',       'hello',      request -> 'Hello, World!'
  '/hello/', 'hello_copy', request -> 'Hello, World!'

host routes

Route on HTTP Host header. Routes must be (host, handler) tuples; the first handler that corresponds to a non-strict superdomain is used. (For example, spam.com would match both spam.com, spam.com:8080 and eggs.spam.com, but not eggs.org.)

upgrade routes

Route on HTTP Upgrade header. Routes must be (protocol, handler) tuples. If the client does not wish to switch protocols (i.e. did not specify an Upgrade header), http is used.

accept routes

Route on HTTP Accept header. Routes must be (mime, handler) tuples; the handler that corresponds to a MIME type with highest quality is chosen. See request.Request.accept.

method routes

Route on HTTP method. Routes must be (method, handler) tuples.

get route

Normally, all handlers are allowed to accept all methods, unless explicitly overriden via method. It is, however, common to create routes that only handle GET request. Use this as a decorator to make a handler respond with HTTP 405 to other methods:

# dg
greet_on_get = dogeweb.route.get $ request -> 'Hello, World!'

# python
@dogeweb.route.get
def greet_on_get(request):
    return 'Hello, World!'

If you’re using the decorator form of get with the decorator form of some other router, note that the order is important!

# This would add a route that only handles GET requests:
@smth.route('/')
@dogeweb.route.get
def _(req): ...

# This is pure nonsense:
@dogeweb.route.get
@smth.route('/')
def _(req): ...

path routes

Route on the requested path. Routes must be (path, handler) or (path, name, handler) tuples. The name item is used for constructing URLs; see request.Request.url_for. path may contain wildcards; see WILDCARDRE, wildcards, and pathregex. If a route ends with a slash but the requested path does not (but otherwise matches the regex), the client is redirected to a path that contains the slash. (For example, given a route for /smth/, a redirect from /smth to /smth/ is created automatically.)

dir routes

Route between modules. The arguments are the same as for path, except the paths must end with slashes. Unlike path, routes do not have to match the whole path, only the beginning of it. Note that path routes relative to the current module; for example, if you have a module /users/ and you wish to match /users/login, this is the structure you want:

handler = r.dir
  '/users/', r.path
    '/login', ...