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].
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.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).
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 '127.0.0.1' 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 ("")||"0.0.0.0"|
|"localhost"||"127.0.0.1" (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.
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.
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.