Router

The router is used to match incoming requests to request handler functions. Typically users don’t interact with the router directly, but instead send a list of routes to register when starting the server. However it is also possible to add routes after starting the server by calling the register method on the server’s router property.

Routes are represented by a three item tuple:

(methods, path_match, handler)

methods is either a string or a list of strings indicating the HTTP methods to match. In cases where all methods should match there is a special sentinel value any_method provided as a property of the router module that can be used.

path_match is an expression that will be evaluated against the request path to decide if the handler should match. These expressions follow a custom syntax intended to make matching URLs straightforward and, in particular, to be easier to use than raw regexp for URL matching. There are three possible components of a match expression:

• Literals. These match any character. The special characters *, { and } must be escaped by prefixing them with a \.

• Match groups. These match any character other than / and save the result as a named group. They are delimited by curly braces; for example:

  {abc}
  

  would create a match group with the name abc.

• Stars. These are denoted with a * and match any character including /. There can be at most one star per pattern and it must follow any match groups.

Path expressions always match the entire request path and a leading / in the expression is implied even if it is not explicitly provided. This means that /foo and foo are equivalent.

For example, the following pattern matches all requests for resources with the extension .py:

*.py

The following expression matches anything directly under /resources with a .html extension, and places the “filename” in the name group:

/resources/{name}.html

The groups, including anything that matches a * are available in the request object through the route_match property. This is a dictionary mapping the group names, and any match for * to the matching part of the route. For example, given a route:

/api/{sub_api}/*

and the request path /api/test/html/test.html, route_match would be:

{"sub_api": "html", "*": "html/test.html"}

handler is a function taking a request and a response object that is responsible for constructing the response to the HTTP request. See Handlers for more details on handler functions.

Interface

class wptserve.router.Router(doc_root, routes)

Object for matching handler functions to requests.

Parameters:

• doc_root – Absolute path of the filesystem location from which to serve tests

• routes – Initial routes to add; a list of three item tuples (method, path_pattern, handler_function), defined as for register()

get_handler(request)

Get a handler for a request or None if there is no handler.

Parameters:

request – Request to get a handler for.

Return type:

Callable or None

register(methods, path, handler)

Register a handler for a set of paths.

Parameters:

• methods – Set of methods this should match. “*” is a special value indicating that all methods should be matched.

• path_pattern –

  Match pattern that will be used to determine if

  a request path matches this route. Match patterns consist of either literal text, match groups, denoted {name}, which match any character except /, and, at most one *, which matches and character and creates a match group to the end of the string. If there is no leading “/” on the pattern, this is automatically implied. For example:

  api/{resource}/*.json
  

  Would match /api/test/data.json or /api/test/test2/data.json, but not /api/test/data.py.

  The match groups are made available in the request object as a dictionary through the route_match property. For example, given the route pattern above and the path /api/test/data.json, the route_match property would contain:

  {"resource": "test", "*": "data.json"}
  

• handler – Function that will be called to process matching requests. This must take two parameters, the request object and the response object.

wptserve.router.compile_path_match(route_pattern)

tokens: / or literal or match or *