Advanced¶

The special _cp_dispatch method¶

_cp_dispatch is a special method you declare in any of your controller to massage the remaining segments before CherryPy gets to process them. This offers you the capacity to remove, add or otherwise handle any segment you wish and, even, entirely change the remaining parts.

import cherrypy

class Band(object):
    def __init__(self):
        self.albums = Album()

    def _cp_dispatch(self, vpath):
        if len(vpath) == 1:
            cherrypy.request.params['name'] = vpath.pop()
            return self

        if len(vpath) == 3:
            cherrypy.request.params['artist'] = vpath.pop(0)  # /band name/
            vpath.pop(0) # /albums/
            cherrypy.request.params['title'] = vpath.pop(0) # /album title/
            return self.albums

        return vpath

    @cherrypy.expose
    def index(self, name):
        return 'About %s...' % name

class Album(object):
    @cherrypy.expose
    def index(self, artist, title):
        return 'About %s by %s...' % (title, artist)

if __name__ == '__main__':
    cherrypy.quickstart(Band())

Notice how the controller defines _cp_dispatch, it takes a single argument, the URL path info broken into its segments.

The method can inspect and manipulate the list of segments, removing any or adding new segments at any position. The new list of segments is then sent to the dispatcher which will use it to locate the appropriate resource.

In the above example, you should be able to go to the following URLs:

• http://localhost:8080/nirvana/
• http://localhost:8080/nirvana/albums/nevermind/

The /nirvana/ segment is associated to the band and the /nevermind/ segment relates to the album.

To achieve this, our _cp_dispatch method works on the idea that the default dispatcher matches URLs against page handler signatures and their position in the tree of handlers.

In this case, we take the dynamic segments in the URL (band and record names), we inject them into the request parameters and we remove them from the segment lists as if they had never been there in the first place.

In other words, _cp_dispatch makes it as if we were working on the following URLs:

• http://localhost:8080/?artist=nirvana
• http://localhost:8080/albums/?artist=nirvana&title=nevermind

The popargs decorator¶

cherrypy.popargs() is more straightforward as it gives a name to any segment that CherryPy wouldn’t be able to interpret otherwise. This makes the matching of segments with page handler signatures easier and helps CherryPy understand the structure of your URL.

import cherrypy

@cherrypy.popargs('name')
class Band(object):
    def __init__(self):
        self.albums = Album()

    @cherrypy.expose
    def index(self, name):
        return 'About %s...' % name

@cherrypy.popargs('title')
class Album(object):
    @cherrypy.expose
    def index(self, name, title):
        return 'About %s by %s...' % (title, name)

if __name__ == '__main__':
    cherrypy.quickstart(Band())

This works similarly to _cp_dispatch but, as said above, is more explicit and localized. It says:

• take the first segment and store it into a parameter name band
• take again the first segment (since we removed the previous first) and store it into a parameter named title

Note that the decorator accepts more than a single binding. For instance:

@cherrypy.popargs('title')
class Album(object):
    def __init__(self):
        self.tracks = Track()

@cherrypy.popargs('num', 'track')
class Track(object):
    @cherrypy.expose
    def index(self, name, title, num, track):
        ...

This would handle the following URL:

• http://localhost:8080/nirvana/albums/nevermind/track/06/polly

Notice finally how the whole stack of segments is passed to each page handler so that you have the full context.

The “normal” CherryPy response process¶

When you provide content from your page handler, CherryPy manages the conversation between the HTTP server and your code like this:

Notice that the HTTP server gathers all output first and then writes everything to the client at once: status, headers, and body. This works well for static or simple pages, since the entire response can be changed at any time, either in your application code, or by the CherryPy framework.

How “streaming output” works with CherryPy¶

When you set the config entry “response.stream” to True (and use “yield”), CherryPy manages the conversation between the HTTP server and your code like this:

When you stream, your application doesn’t immediately pass raw body content back to CherryPy or to the HTTP server. Instead, it passes back a generator. At that point, CherryPy finalizes the status and headers, before the generator has been consumed, or has produced any output. This is necessary to allow the HTTP server to send the headers and pieces of the body as they become available.

Once CherryPy has set the status and headers, it sends them to the HTTP server, which then writes them out to the client. From that point on, the CherryPy framework mostly steps out of the way, and the HTTP server essentially requests content directly from your application code (your page handler method).

Therefore, when streaming, if an error occurs within your page handler, CherryPy will not catch it–the HTTP server will catch it. Because the headers (and potentially some of the body) have already been written to the client, the server cannot know a safe means of handling the error, and will therefore simply close the connection (the current, builtin servers actually write out a short error message in the body, but this may be changed, and is not guaranteed behavior for all HTTP servers you might use with CherryPy).

In addition, you cannot manually modify the status or headers within your page handler if that handler method is a streaming generator, because the method will not be iterated over until after the headers have been written to the client. This includes raising exceptions like HTTPError, NotFound, InternalRedirect and HTTPRedirect. To use a streaming generator while modifying headers, you would have to return a generator that is separate from (or embedded in) your page handler. For example:

class Root:
    @cherrypy.expose
    def thing(self):
        cherrypy.response.headers['Content-Type'] = 'text/plain'
        if not authorized():
            raise cherrypy.NotFound()
        def content():
            yield "Hello, "
            yield "world"
        return content()
    thing._cp_config = {'response.stream': True}

Streaming generators are sexy, but they play havoc with HTTP. CherryPy allows you to stream output for specific situations: pages which take many minutes to produce, or pages which need a portion of their content immediately output to the client. Because of the issues outlined above, it is usually better to flatten (buffer) content rather than stream content. Do otherwise only when the benefits of streaming outweigh the risks.

Timeout Monitor¶

In addition, CherryPy includes a cherrypy.engine.timeout_monitor which monitors all active requests in a separate thread; periodically, it calls check_timeout on them all. It is subscribed by default. To turn it off:

[global]
engine.timeout_monitor.on: False

or:

cherrypy.engine.timeout_monitor.unsubscribe()

You can also change the interval (in seconds) at which the timeout monitor runs:

[global]
engine.timeout_monitor.frequency: 60 * 60

The default is once per minute. The above example changes that to once per hour.

Windows Console Events¶

Microsoft Windows uses console events to communicate some signals, like Ctrl-C. When deploying CherryPy on Windows platforms, you should obtain the Python for Windows Extensions; once you have them installed, CherryPy will handle Ctrl-C and other console events (CTRL_C_EVENT, CTRL_LOGOFF_EVENT, CTRL_BREAK_EVENT, CTRL_SHUTDOWN_EVENT, and CTRL_CLOSE_EVENT) automatically, shutting down the bus in preparation for process exit.

Make your CherryPy application a WSGI application¶

A WSGI application can be obtained from your application as follows:

import cherrypy
wsgiapp = cherrypy.Application(StringGenerator(), '/', config=myconf)

Simply use the wsgiapp instance in any WSGI-aware server.

Host a foreign WSGI application in CherryPy¶

Assuming you have a WSGI-aware application, you can host it in your CherryPy server using the cherrypy.tree.graft facility.

def raw_wsgi_app(environ, start_response):
    status = '200 OK'
    response_headers = [('Content-type','text/plain')]
    start_response(status, response_headers)
    return ['Hello world!']

cherrypy.tree.graft(raw_wsgi_app, '/')

No need for the WSGI interface?¶

The default CherryPy HTTP server supports the WSGI interfaces defined in PEP 333 and PEP 3333. However, if your application is a pure CherryPy application, you can switch to a HTTP server that by-passes the WSGI layer altogether. It will provide a slight performance increase.

import cherrypy

class Root(object):
    @cherrypy.expose
    def index(self):
        return "Hello World!"

if __name__ == '__main__':
    from cherrypy._cpnative_server import CPHTTPServer
    cherrypy.server.httpserver = CPHTTPServer(cherrypy.server)

    cherrypy.quickstart(Root(), '/')