Clone wiki

CherryPy / WhatsNewIn31

What's new in CherryPy 3.1

This document only describes new features in CherryPy 3.1. A detailed "How To Upgrade" document is at [wiki:UpgradeTo31 UpgradeTo31].

Web Site Process Bus

CherryPy 3 separated the socket code (server) from the site startup/shutdown code (engine), and 3.1 continues down that road. The "engine" object is now a complete site container, with "start", "stop", and "restart" methods. To take full advantage of this, you write your site startup code as plugins to the engine. Most of the builtin startup code has already been converted for you. For example, instead of telling cherrypy.server to start, you may now just start the engine.

Centralizing startup and shutdown behavior in this fashion has made the Autoreload feature much more stable, as well as introducing tools for daemonization, pid files, timers, and other plugins. It also allows platform-specific process-management code; for example, the Win32 bus uses native code for signaling and blocking.

You can read all about the Bus, and the builtin Plugins, at WebSiteProcessBus.


There's a new "cherryd" daemon script! This can save a *lot* of boilerplate in your app startup script.

Usage: cherryd [options]

  -h, --help            show this help message and exit
  -c CONFIG, --config=CONFIG
                        specify config file(s)
  -d                    run the server as a daemon
                        apply the given config environment
  -f                    start a fastcgi server instead of the default HTTP
  -i IMPORTS, --import=IMPORTS
                        specify modules to import
  -p PIDFILE, --pidfile=PIDFILE
                        store the process id in the given file

Request and Response creation

In 3.0, the Engine would create the Request and Response objects. In 3.1, the Application object has that responsibility via its get_serving and release_serving methods. This makes the request object overridable per-app, and also removes the dependency on the engine object.

Available Toolboxes

The set of toolboxes available to a given request must now be specified per Application. For example:

myapp = cherrypy.Application()
# This line is new.
myapp.toolboxes['template'] = TemplateTools()

In !CherryPy 3.0, toolboxes were per-engine and didn't need that last line.

WSGI Server

The wsgiserver module is now more extendable in a couple of ways. Most visibly, the thread pool is now a delegate, so you can replace the builtin one if you need fancy thread pooling (or none at all). The ability to dispatch to multiple apps has also been moved out into its own piece of middleware (WSGIPathInfoDispatcher), which is replaceable. It's also not loaded if you're only deploying one app, so you don't pay the performance penalty of multiple apps.

CherryPy now works with '''Google App Engine'''! The wsgiserver is now imported lazily-enough to avoid illegal imports of the socket module.

Custom 4xx and 5xx handlers

HTTP responses between 400 and 599 can now be generated by custom functions you provide. See help(cherrypy.request.[wiki:ErrorsAndExceptions#AnticipatedHTTPresponses error_page]) for more information.


There's a new reopen_files method on the !LogManager object. This helps graceful restarts.

You can also set the access file log format more easily now. There's a new 'log.access_log_format' config option--see the code for complete details on the available formats.

CherryPy 3.1 also changed its access log format slightly to be more secure and stable. Like Apache started doing in 2.0.46, non-printable and other special characters are escaped using \xhh sequences, where hh stands for the hexadecimal representation of the raw byte. Exceptions from this rule are " and \, which are escaped by prepending a backslash, and all whitespace characters, which are written in their C-style notation (\n, \t, etc). It's a lot like repr().

Virtual Hosts

There's a new VirtualHost WSGI middleware object in See its docstring for details.


There's a new subfolder in the cherrypy directory: scaffold. Use it as a base for creating new CherryPy applications. When you want to make a new app, copy and paste it to some other location (maybe site-packages) rename it to the name of your project, then tweak as desired. Even before any tweaking, it should serve a few demonstration pages. Change to its directory and run python --config=example.conf.

We hope to add little improvements to the scaffolding application as we go, to help enable good CherryPy code and avoid common pitfalls. So feel free to recommend some!