Contents
If you are coming from TurboGears 1.0, you may want to read the TurboGears 1.1 Upgrade Guide first.
The major change in TurboGears 1.5 is that it is now based on CherryPy 3.1 instead of CherryPy 2.2. The change from version 2 to version 3 of CherryPy brings a big gain in performance and other advantages, but unfortunately also involves quite a lot pf changes in the configuration and the API.
The CherryPy documentation has detailed instructions on how to upgrade from CherryPy 2 to CherryPy 3. You should also read what’s new in CherryPy 3 to better understand and appretiate these changes.
The first thing you need to do is adapt your configuration files (usually called dev.cfg, test.cfg, prod.cfg, default.cfg and app.cfg, and located in the project directory and the config subpackage of the project package).
The main change is that instead of CherryPy filters, you now have to use CherryPy tools, and the config names reflect this change.
Replace your configuration settings in app.cfg as follows:
| replace these settings | with these settings |
|---|---|
| session_filter.on | tools.sessions.on |
| static_filter.on | tools.staticdir.on / tools.staticfile.on |
| static_filter.dir | tools.staticdir.dir |
| static_filter.file | tools.staticfile.filename |
| gzip_filter.on | tools.gzip_filter.on |
| gzip_filter.mime_types | tools.gzip_mime_types |
| base_url_filter | tools.proxy |
| safempfilter.on | tools.safe_multipart.on |
| log_debug_info_filter.on | nothing (does not exist any more) |
Note that you do not have to change the settings for toscawidgets and visit. Even though these are implemented as CherryPy tools now, they should be given without the tools. prefix.
In dev.cfg, prod.cfg, default.cfg, test.cfg (you may not have all of these, or named them differently) make the following changes:
| replace these settings | with these settings |
|---|---|
| autoreload.on = True | engine.autoreload_on = True |
| autoreload.package = ‘...’ | nothing (remove the setting) |
| server.environment = ‘development’ | nothing (remove the setting) |
| server.environment = ‘production’ | environment = ‘production’ |
| log_debug_info_filter.on | nothing (does not exist any more) |
In the [logging] section of dev.cfg, prod.cfg, default.cfg, test.cfg make the following change:
| replace these settings | with these settings |
|---|---|
[[[access]
level=’INFO’
qualname=’turbogears.access’
handlers=[‘access_out’]
propagate=0
|
[[[access]]]
level=’INFO’
qualname=’cherrpy.access’
handlers=[‘access_out’]
propagate=0
[[[error]]]
level=’INFO’
qualname=’cherrypy.error’
handlers=[‘debug_out’]
propagate=0
|
Some more things have change in the CherryPy API. Here are some of the major changes you may need to take care of:
- Replace request.path with request.path_info.
- Replace request.remote_addr with request.remote.ip.
- Replace request.simple_cookie and response.simple_cookie with request.cookie and response.cookie.
- Replace cherrypy.lib.cptools.serveFile with cherrypy.lib.static.serve_file.
- You cannot from cherrypy import session and then use session any more (as you still can do with request and response), but you have to import cherrypy and then use cherrypy.session instead of just session. See also our tip for visit based sessions.
- We had a recipe for custom error reporting with TurboGears 1.0 that used CherryPy filters. This does not work any more with CherryPy 3, since filters have been replaced by tools. See our new recipe for custom error reporting with TurboGears 1.5.
TurboGears still runs fine with the Kid templating engine, but you need to make some changes to tell TurboGears explicitely that you’re using Kid, because the standard templating engine for page and widget templates is now Genshi.
First, make sure you have set tg.defaultview = 'kid' in the app.cfg configuration file.
Second, for any of your TurboGears widgets with custom Kid templates, add a “kid:” prefix to the template attribute, or set the engine_name attribute to ‘kid’. Sometimes this may not be needed, since TurboGears 1.5 will usually find the proper engine, but better be explicit. This is particularly important if your widgets are combined with TurboGears widgets which now all use Genshi templates and assume their child widgets also use Genshi if not stated otherwise. You may want to read some more about widget template engines in TurboGears 1.5.
First, let us repeat that you don’t really need to replace Kid with Genshi, since Kid is still fully supported ind TurboGears 1.5. However, Kid is not maintained any more, and Genshi has better performance and has become the default templating engine in TurboGears 1.5. Also, Kid and Genshi are very similar (see Comparing Genshi to Kid), so replacing Kid with Genshi is usually not a big deal and therefore recommended by the TurboGears team.
If you want to replace Kid with Genshi, we recommend quickstarting a new project with TurboGears 1.5 to see how Genshi templating is supposed to work, particularly regarding the use of the master templates.
As you will see, one major change is that the default extension for Genshi files is just .html, while Kid templates used the special .kid extension. The .html new extension makes it easier to load the templates in a browser or HTML editor. Another important change is that xmlns:py="http://purl.org/kid/ns#" must be replaced by xmlns:py="http://genshi.edgewall.org/". The integration of the master template also works a bit differently. Genshi does this with the <xi:include href="master.html" /> directive using the standard xmlns:xi="http://www.w3.org/2001/XInclude" namespace, while Kid has been used with its py:extends mechanism.
The tg-admin command in TurboGears 1.5 has a subcommand kid2genshi that helps you with these bulk replacements and renames. Use it inside your project’s base directory. You can display all of its options with:
tg-admin kid2genshi --help
Please note that we don’t use a site template in TurboGears 1.5 any more, as we did in TurboGears 1.0. This site template was responsible for linking the CSS and JavaScript resources, and TurboGears 1.5 does this in the master template already. Again, please have a look at a newly quickstarted project to see how your Genshi master template should look like.
You may need to make some more smaller adaptations to your templates, see the Genshi documentation for details.
One particularly noteworthy difference is the following:
In Kid, py:attrs would accept a series of x=y statements as a string, like:
<a py:content="the page" py:attrs="href=thepage.html">link</a>
In Genshi, py:attrs must be given a dict:
<a py:content="the page" py:attrs="{'href':'thepage.html'}">link</a>
Moving from SQLObject to SQLAlchemy is a much greater task than moving from Kid to Genshi. Again, even though SQLAlchemy has become the default ORM in TurboGears 1.5, it still works fine with SQLObject, so if you have invested a lot of work into your SQLObject code, and do not experience database performance problems, or do not plan to extend the functionality of your project involving database issues, you should probably stick with SQLObject. Actually, some parts of the TurboGears toolbox (CatWalk and ModelDesigner) still have not been ported to SQLAlchemy and can only be used with SQLObject.
As with the move from Kid to Genshi, we recommend quickstarting a TurboGears 1.5 project (with the --identity option) and having a look how the SQLAlchemy model code for a TurboGears 1.5 project should look like.
Luckily, the SQLAlchemy documentation is very helpful.