cherrypy._cpdispatch – Mapping URI’s to handlers

CherryPy dispatchers.

A ‘dispatcher’ is the object which looks up the ‘page handler’ callable and collects config for the current request based on the path_info, other request attributes, and the application architecture. The core calls the dispatcher as early as possible, passing it a ‘path_info’ argument.

The default dispatcher discovers the page handler by matching path_info to a hierarchical arrangement of objects, starting at


class cherrypy._cpdispatch.PageHandler(callable, *args, **kwargs)

Callable which sets response.body.


The ordered args should be accessible from post dispatch hooks


The named kwargs should be accessible from post dispatch hooks

class cherrypy._cpdispatch.LateParamPageHandler(callable, *args, **kwargs)

When passing cherrypy.request.params to the page handler, we do not want to capture that dict too early; we want to give tools like the decoding tool a chance to modify the params dict in-between the lookup of the handler and the actual calling of the handler. This subclass takes that into account, and allows request.params to be ‘bound late’ (it’s more complicated than that, but that’s the effect).


page handler kwargs (with cherrypy.request.params copied in)

class cherrypy._cpdispatch.Dispatcher(dispatch_method_name=None, translate='x00x01x02x03x04x05x06x07x08tnx0bx0crx0ex0fx10x11x12x13x14x15x16x17x18x19x1ax1bx1cx1dx1ex1f _______________0123456789_______ABCDEFGHIJKLMNOPQRSTUVWXYZ______abcdefghijklmnopqrstuvwxyz____x7fx80x81x82x83x84x85x86x87x88x89x8ax8bx8cx8dx8ex8fx90x91x92x93x94x95x96x97x98x99x9ax9bx9cx9dx9ex9fxa0xa1xa2xa3xa4xa5xa6xa7xa8xa9xaaxabxacxadxaexafxb0xb1xb2xb3xb4xb5xb6xb7xb8xb9xbaxbbxbcxbdxbexbfxc0xc1xc2xc3xc4xc5xc6xc7xc8xc9xcaxcbxccxcdxcexcfxd0xd1xd2xd3xd4xd5xd6xd7xd8xd9xdaxdbxdcxddxdexdfxe0xe1xe2xe3xe4xe5xe6xe7xe8xe9xeaxebxecxedxeexefxf0xf1xf2xf3xf4xf5xf6xf7xf8xf9xfaxfbxfcxfdxfexff')

CherryPy Dispatcher which walks a tree of objects to find a handler.

The tree is rooted at, and each hierarchical component in the path_info argument is matched to a corresponding nested attribute of the root object. Matching handlers must have an ‘exposed’ attribute which evaluates to True. The special method name “index” matches a URI which ends in a slash (“/”). The special method name “default” may match a portion of the path_info (but only when no longer substring of the path_info matches some other object).

This is the default, built-in dispatcher for CherryPy.

dispatch_method_name = '_cp_dispatch'

The name of the dispatch method that nodes may optionally implement to provide their own dynamic dispatch algorithm.


Return the appropriate page handler, plus any virtual path.

This will return two objects. The first will be a callable, which can be used to generate page output. Any parameters from the query string or request body will be sent to that callable as keyword arguments.

The callable is found by traversing the application’s tree, starting from, and matching path components to successive objects in the tree. For example, the URL “/path/to/handler” might return

The second object returned will be a list of names which are ‘virtual path’ components: parts of the URL which are dynamic, and were not used when looking up the handler. These virtual path components are passed to the handler as positional arguments.

class cherrypy._cpdispatch.MethodDispatcher(dispatch_method_name=None, translate='x00x01x02x03x04x05x06x07x08tnx0bx0crx0ex0fx10x11x12x13x14x15x16x17x18x19x1ax1bx1cx1dx1ex1f _______________0123456789_______ABCDEFGHIJKLMNOPQRSTUVWXYZ______abcdefghijklmnopqrstuvwxyz____x7fx80x81x82x83x84x85x86x87x88x89x8ax8bx8cx8dx8ex8fx90x91x92x93x94x95x96x97x98x99x9ax9bx9cx9dx9ex9fxa0xa1xa2xa3xa4xa5xa6xa7xa8xa9xaaxabxacxadxaexafxb0xb1xb2xb3xb4xb5xb6xb7xb8xb9xbaxbbxbcxbdxbexbfxc0xc1xc2xc3xc4xc5xc6xc7xc8xc9xcaxcbxccxcdxcexcfxd0xd1xd2xd3xd4xd5xd6xd7xd8xd9xdaxdbxdcxddxdexdfxe0xe1xe2xe3xe4xe5xe6xe7xe8xe9xeaxebxecxedxeexefxf0xf1xf2xf3xf4xf5xf6xf7xf8xf9xfaxfbxfcxfdxfexff')

Additional dispatch based on cherrypy.request.method.upper().

Methods named GET, POST, etc will be called on an exposed class. The method names must be all caps; the appropriate Allow header will be output showing all capitalized method names as allowable HTTP verbs.

Note that the containing class must be exposed, not the methods.

class cherrypy._cpdispatch.RoutesDispatcher(full_result=False, **mapper_options)

A Routes based dispatcher for CherryPy.


Find the right page handler, and set request.config.

class cherrypy._cpdispatch.XMLRPCDispatcher
class cherrypy._cpdispatch.VirtualHost

Select a different handler based on the Host header.

This can be useful when running multiple sites within one CP server. It allows several domains to point to different parts of a single website structure. For example:

http://www.domain.example  ->  root
http://www.domain2.example  ->  root/domain2/
http://www.domain2.example:443  ->  root/secure

can be accomplished via the following config:

request.dispatch = cherrypy.dispatch.VirtualHost(
    **{'www.domain2.example': '/domain2',
       'www.domain2.example:443': '/secure',
The next dispatcher object in the dispatch chain. The VirtualHost dispatcher adds a prefix to the URL and calls another dispatcher. Defaults to cherrypy.dispatch.Dispatcher().
If True (the default), any “X-Forwarded-Host” request header will be used instead of the “Host” header. This is commonly added by HTTP servers (such as Apache) when proxying.
A dict of {host header value: virtual prefix} pairs. The incoming “Host” request header is looked up in this dict, and, if a match is found, the corresponding “virtual prefix” value will be prepended to the URL path before calling the next dispatcher. Note that you often need separate entries for “” and “”. In addition, “Host” headers may contain the port number.