TurboGears Upgrade Guide
To upgrade to the latest released version of TurboGears, you should first upgrade setuptools and then upgrade TurboGears. To do so, download the ez_setup.py script. On Windows:
ez_setup.py -U setuptools
easy_install -Uf http://www.turbogears.org/download/index.html TurboGears
On Mac OS X and other *nix-like systems:
sudo python ez_setup.py --script-dir /usr/local/bin -U setuptools
sudo easy_install -Uf http://www.turbogears.org/download/index.html --script-dir /usr/local/bin TurboGears
Please also be aware of backwards compatibility issues. These are addressed in the remainder of the guide.
Updating from 0.9x to 0.9a5
Identity has changed to use PEP 8 (Python standard coding convention) style names. SQL migration scripts are available to help convert your database to the new names.
Additionally, your identity login screen must have a button that is named "login" or another name specified in the identity.form.submit configuration variable.
Updating from 0.9a1 to 0.9a2
TurboGears 0.9 introduced a new config file format that allowed you to do basically anything that can be done in Python. The modules looked mostly like INI files, but were actually Python modules being executed in a slightly altered namespace.
It turns out that this had issues with Python 2.3, and some other minor issues that arose because these files ended in .py, but were not truly importable Python modules.
For these reasons, TurboGears has switched back to the original CherryPy-style config file in 0.9a2. The configuration change that persists between TurboGears 0.8 and 0.9 is that configuration is now split between two files: a deployment config file (dev.cfg, prod.cfg) and a package config file: yourpackagename/config.cfg.
There are a few minor, manual steps required to shift to the old/new config format if you were using 0.9 prior to 0.9a2:
- Rename "devcfg.py" to "dev.cfg"
- Rename "prodcfg.py" to "prod.cfg"
- mkdir "yourpackage/config"
- Create an empty file called in "yourpackage/config" called __init__.py (to make yourpackage/config a proper Python package).
- Rename "yourpackage/config.py" to "yourpackage/config/app.cfg"
- Edit your start-[yourproject].py file
- Change the references to devcfg.py to dev.cfg
- Change the references to prodcfg.py to prod.cfg
- Change the references to yourpackage.config to yourpackage.config.app
- Edit dev.cfg and prod.cfg to add [global] at the top of the file
- Edit yourpackage/config/app.cfg:
- Add [global] at the top of the file
- Change any path("something") to [something] (note the removal of quotes)
- Change calls to absfile to use %(top_level_dir)s. This diff will give you an idea of the change:
-static_filter.dir = absfile("${package}", "static") +static_filter.dir = "%(top_level_dir)s/static"
Updating from 0.8 to 0.9
There are a number of changes that will need to be made to your project in order to upgrade to TurboGears 0.9.
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:
Now, you must now specify:
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:
- 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
-
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:
Or, if you really only care to have JSON output for a method, you can use the 'format' parameter, like this:
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 as 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.
Depreciated 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 for expose(template=..
Updating from 0.5 to 0.8
0.8 has a number of minor backwards incompatible changes. There are only two such changes that you'll likely need to take action on.
The primary one is the renaming of the turbogears* variables. You'll want to do project wide search/replace for these values.
| Search for | Replace with |
|---|---|
| turbogearshtml | tg_template |
| turbogearsfmt | tg_format |
| turbogearsflash | tg_flash |
| turbogearsjs | tg_js |
The other noticeable change that you'll come across is that turbogears-admin.py has been renamed to tg-admin. Note that in addition to the base name change, you no longer need to add the .py on the end.
Though they are less likely to pose problems for you, you may wish to check out the complete changelog for additional changes.
