TurboGears Upgrade Guide

Upgrade Project Files and Configuration Files

One of the big changes in 0.9 is how configuration files work. Configuration files are now python modules, which provide a great deal of flexibility. The old configuration files will still work, but all ongoing development is going to be in the new format, and migration is relatively painless. The easiest way to add the new configuration files is to run the following command (in the base directory of your project):

tg-admin update

Running this command is going to try and upgrade (and overwrite!) existing files, so be careful! tg-admin will prompt you with 'Y/n/d/b' before overwriting anything. Y is yes (overwrite), n is no (don't overwrite), d will show you a diff of the new and old file, and b will make a backup of your existing file before overwriting. Briefly, files that are going to be updated are:

• controllers.py Some methods have been added for the new Identity feature, and turbogears.controllers.RootController is used instead of the deprecated version. It is probably easiest to say 'n' (don't overwrite). Later, if you like, you can create a new project (using 'tg-admin quickstart') to get a pure version of controllers.py and merge in these changes.
• model.py You can probably leave this alone (answer 'n'). The only change is to import some files for Identity, and you can copy this import from a newly quickstarted project later if you plan on using Identity.
• master.kid Changes to this file aren't critical, so 'n' is probably a safe choice. Again, there are Identity specific changes that you may want to merge in later.
• setup.py This one you should probably answer 'b' (backup). If you have made changes (which isn't likely), you can merge them in later.
• dev.cfg and prod.cfg The config files have been separated out into deployment config (held in these two files which you originally had) and an application config that would be the same regardless of where the application is deployed. You don't need to make this transition if you don't want to. You can safely press "n" to leave these files alone.

A new config file will be placed in <yourpackage>/config/app.cfg. Configuration items that are applicable to both development and production now go into app.cfg. The reason for this is that it allows your project to be conveniently packaged as an egg if you choose to do so, with the project specific configuration intact.

tg-admin update does not overwrite your old dev.cfg or prod.cfg. You can call <yourprojectname>-start.py to start up your project using the old config files, or you can use start-<yourprojectname>.py to start using the new configuration files. Migration to the new files should be straightforward, and is probably as simple as copying the database configurations from the old files to the new ones. Once you have fully migrated to 0.9, you should delete dev.cfg, prod.cfg, and yourprojectname-start.py.

Make Static File Paths Absolute

CherryPy 2.2 requires that paths to static files be absolute. While you might think this would prevent projects from being deployed on different machines, TurboGears provides a function 'absfile' to help maintain portability. If your package name is 'bigboy', in 0.8 you would say:

# <=0.8 usage only
[/static]
staticFilter.on = True
staticFilter.dir = "static"

Now, you must now specify:

# 0.9 usage
[/static]
staticFilter.on = True
staticFilter.dir = "%(top_level_dir)s/static"

top_level_dir is the directory where the top level of your project is located. You can also use package_dir which is the same directory the config file is located in.

tg-admin update should take care of the /static and /favicon.ico cases (in the new config files), but if you have any custom static files or folders, you will need to make a change to make sure that the file paths are absolute.

Methods Must Explicitly Allow JSON

In order to prevent accidentally exposing information that perhaps everyone shouldn't see, exposed methods no longer automatically provide JSON output when the url contains 'tg_format=json'. Instead, you must explicitly state when a method is going to provide JSON output. This can be done two different ways:

1. Enable JSON in app.cfg If you would like to have the same behavior as existed in v0.8 (i.e. JSON output is always exposed), you can globally enable it in your app.cfg with:

   tg.allow_json = True

2. Enable JSON only for specific methods If you would like to only let specific methods return JSON (which is probably smart from a security perspective), you can do so using the allow_json parameter in the @turbogears.expose decorator, like this:

   # This method can return html or json, depending on the url that is called
   @turbogears.expose(template=".templates.my_pretty_view", allow_json=True)
   def pretty(self):
       return {"msg":"I'm so pretty."}

   Or, if you really only care to have JSON output for a method, you can use the format parameter, like this:

   # This method only returns json;
   #'tg_format=json' isn't necessary in the url.
   @turbogears.expose(format="json")
   def modestly_hot(self):
       return {"msg":"I'm only sorta hot. I don't mess around."}

Changing from std. to tg. in your templates

The std object that appears in your template namespace that holds useful values and functions has been renamed tg. You should be able to do a search and replace in your template files to swap std. with tg..

Other Incompatibilities

There are a couple other changes that probably won't impact most projects, but will cause things to not work if you are using them.

• The server.webpath configuration variable will not only properly set outgoing URLs, but will also "fix" incoming URLs if TurboGears is running at some path underneath another webserver. If you were previously running a CherryPy filter to handle this, you no longer need to.
• Previously, if you were using a FormEncode Schema for validation for an exposed method, validation would fail if a value was missing but the method had a default value for that parameter. Now, if that value is missing, the method will get called with the default just as it is normally called in Python.

Deprecated Items

The following items will work in 0.9, but will be changing in the future. You should migrate away from any usage of these items as you are able to.

• For clarity's sake, turbogears.controllers.Root is now turbogears.controllers.RootController.
• Error handling has been greatly improved. Use of the validation_error method has been deprecated. It will still be called if it exists, but a DeprecationWarning will be displayed.
• turbogears.tests.util has been moved to turbogears.testutil.
• CherryPy has a list of names that are deprecated in order to comply with PEP-8.
• expose(html=...) is now deprecated in favor of expose(template=...).