matchrouter – Routes request based on URL match.

Module contents

class pluggdapps.web.matchrouter.MatchRouter(pa, *args, **kwargs)

Bases: pluggdapps.plugin.Plugin

Plugin to resolve HTTP request to a view-callable by matching patterns on request-URL. Refer to pluggdapps.web.interfaces.IHTTPRouter interface spec. to understand the general intent and purpose of this plugin. On top of that, this plugin also supports server side HTTP content negotiation.

When creating a web application using pluggdapps, developers must implement a router class, a plugin, implementing pluggdapps.web.interfaces.IHTTPRouter interfaces. The general thumb rule is to derive their router class from one of the base routers defined under pluggdapps.web package. MatchRouter is one such base class. When an application derives its router from this base class, it can override onboot() method and call add_view() to add view representations for matching resource.

This router plugin adheres to HTTP concepts like resource, representation and views. As per the nomenclature, a resource is always identified by request-URL and same resource can have any number of representation. View is a callable entity that is capable of generating the desired representation. Note that a web page that is encoded with gzip compression is a different representation of the same resource that does not use gzip compression.

Instead of programmatically configuring URL routing, it is possible to configure them using a mapper file. Which is a python file containing a list of dictionaries where each dictionary element will be converted to add_view() method call during onboot().

map file specification,

[ { 'name'             : <variant-name as string>,
    'pattern'          : <regex pattern-to-match-with-request-URL>,
    'view'             : <view-callable as string>,
    'resource'         : <resource-name as string>,
    'attr'             : <attribute on view callable, as string>,
    'method'           : <HTTP request method as byte string>,
    'media_type'       : <content-type as string>,
    'language'         : <language-string as string>,
    'charset'          : <charset-string as string>,
    'content_coding'   : <content-coding as comma separated values>,
    'cache_control'    : <response header value>,
    'rootloc'          : <path to root location for static documents>,
  },
  ...
]

views = {}

Dictionary of view-names to view-callables and its predicates, typically added via add_view() interface method.

viewlist = []

same as views.items() except that this list will maintain the order in which the views where added. The same order will be used while resolving the request to view-callable.

negotiator = None

pluggdapps.web.interface.IHTTPNegotiator plugin to handle HTTP negotiation.

onboot()

pluggapps.web.interfaces.IHTTPRouter.onboot() interface method. Deriving class must override this method and use add_view() to create router mapping.

add_view(name, pattern, **kwargs)

Add a router mapping rule.

name,

The name of the route. This attribute is required and it must be unique among all defined routes in a given web-application.

pattern,

The pattern of the route. This argument is required. If pattern doesn’t match the current URL, route matching continues.

For EG,

self.add_view( 'article', 'blog/{year}/{month}/{date}' )

Optional key-word arguments,

view,

A plugin name or plugin instance implementing IHTTPView interface, or just a plain python callable or a string that imports a callable object. What ever the case, please do go through the IHTTPView interface specification before authoring a view-callable.

resource,

A plugin name or plugin instance implementing IHTTPResource interface, or just a plain python callable. What ever the case, please do go through the IHTTPResource interface specification before authoring a resource-callable.

attr,

If view-callable is a method on view object then supply this argument with a valid method name.

method,

Request predicate. HTTP-method as byte string to be matched with incoming request.

media_type,

Request predicate. Media type/subtype string specifying the resource variant. If unspecified, will be automatically detected using heuristics.

language,

Request predicate. Language-range string specifying the resource variant. If unspecified, assumes webapp[‘language’] from configuration settings.

charset,

Request predicate. Charset string specifying the resource variant. If unspecified, assumes webapp[‘encoding’] from configuration settings.

content_coding,

Comma separated list of content coding that will be applied, in the same order as given, on the resource variant. Defaults to identity.

cache_control,

Cache-Control response header value to be used for the resource’s variant.

rootloc,

To add views for static files, use this attribute. Specifies the root location where static files are located. Note that when using this option, pattern argument must end with *path.

media_type, language, content_coding and charset kwargs, if supplied, will be used during content negotiation.

route(request)

pluggdapps.web.interfaces.IHTTPRouter.route() interface method.

Three phases of request resolution to view-callable,

• From configured list of views, filter out views that maps to same request-URL.
• From the previous list, filter the variants that match with request predicates.
• If content negotiation is enable, apply server-side negotiation algorithm to single out a resource variant.

If than one variant remains at the end of all three phases, then pick the first one in the list. And that is why the sequence in which add_view() is called for each view representation is important.

If resource attribute is configured on a view, it will be called with request plugin and context dictionary. Resource-callable can populate the context with relavant data that will subsequently be used by the view callable, view-template etc. Additionally, if a resource callable populates the context dictionary, it automatically generates the etag for data that was populated through c.etag dictionary. Populates context with special key etag and clears c.etag before sending the context to view-callable.

urlpath(request, name, **matchdict)

pluggdapps.web.interfaces.IHTTPRouter.route() interface method.

Generate url path for request using view-patterns. Return a string of URL-path, with query and anchore elements.

name,

Name of the view pattern to use for generating this url

matchdict,

A dictionary of variables in url-patterns and their corresponding value string. Every route definition will have variable (aka dynamic components in path segments) that will be matched with url. If matchdict contains the following keys,

_query, its value, which must be a dictionary similar to pluggdapps.web.interfaces.IHTTPRequest.getparams, will be interpreted as query parameters and encoded to query string.

_anchor, its value will be attached at the end of the url as “#<_anchor>”.

onfinish(request)

pluggdapps.web.interfaces.IHTTPRouter.onfinish() interface method.