Clone wiki

CherryPy / UpgradeTo31


How to upgrade to CherryPy 3.1

This page discusses changes between CherryPy 3.0 (December 2006) and 3.1 (June 2008) which might require you to modify your code when you upgrade. Bugfixes aren't listed here. See also [wiki:WhatsNewIn31 WhatsNewIn31].

Engine changes

The Engine continues to develop into a full-fledged site container/application server. Instead of an ad-hoc object it is now a [wiki:WebSiteProcessBus Web Site Process Bus], which operates on a publish/subscribe model. Therefore, some of the legacy interface has been replaced.

  • engine.on_start_engine_list.append(callback) is now engine.subscribe('start', callback).
  • engine.on_stop_engine_list.append(callback) is now engine.subscribe('stop', callback).
  • engine.on_start_thread_list.append(callback) is now engine.subscribe('start_thread', callback).
  • engine.on_stop_thread_list.append(callback) is now engine.subscribe('stop_thread', callback).

Use engine.unsubscribe(channel, callback) to remove any callback. In particular, if you're using your own WSGI server or gateway, you need to unsubscribe cherrypy.server via cherrypy.server.unsubscribe(). You can also turn off the autoreloader now via cherrypy.engine.autoreload.unsubscribe() (or, use the same config settings as before; those still work).

The start method of cherrypy.engine doesn't block by default anymore. Add cherrypy.engine.block() after engine.start to block the main thread.


In an effort to make both applications built with CherryPy and CherryPy itself less confusing, server.socket_host is no longer allowed to be blank or None. In addition, you should prefer '' to 'localhost', since the latter is ambiguous (the server may believe it refers to an IPv4 address, but the browser to an IPv6 address):

'''Old socket_host value''''''New socket_host value'''
emtpy string ("")""
"localhost""" (IPv4) or "::1" (IPv6)


In order to fix some bugs, the API for some wsgiserver classes (HTTPRequest, HTTPConnection) had to change. It's best just to review the source code if you have custom subclasses of these objects.

Request class

The unused 'exc' argument to Request.handle_error has been dropped. If you have a custom subclass of Request which overrides the 'respond' or 'handle_error' methods, remove the 'exc' argument from both caller and callee.

Custom 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.