Table Of Contents

Previous topic

Installation Troubleshooting

Next topic

Downloading and installing a TurboGears beta version

TurboGears 1.0 Upgrade Guide


The easiest way to upgrade TurboGears itself is to download the latest and run it! This will update all of the parts of the TurboGears installation that need updating.

Backwards incompatible changes in new TurboGears versions might make it necessary to update your existing TurboGears applications, so that they work correctly with the new TurboGears version. These necessary changes are addressed in the remainder of this guide.

Updating from 1.0.8 to 1.0.9

Here is a list of changes in the 1.0.8 release which might affect existing applications. For a detailed list of changes, see the 1.0.9 changelog.

No incompatible changes are known to exist in 1.0.9.

Updating from 1.0.7 to 1.0.8

Here is a list of changes in the 1.0.8 release which might affect existing applications. For a detailed list of changes, see the 1.0.8 changelog.

XHTML Content Type

In TG 1.0.7 XHTML templates were delivered with a content type of "application/xhtml+xml". In TG 1.0.8 this was changed back to "text/html" due to compatibility issues with the Internet Explorer.

Widget Forms

Hidden form fields in widget forms are now always put in an invisible div elements since they must be contained in a block-level element to be valid (X)HTML. This might effect your CSS selectors.

Updating from 1.0.6 to 1.0.7

Here is a list of changes in the 1.0.7 release which might affect existing applications. For a detailed list of changes, see the. 1.0.7 changelog.

Identity exceptions

The standard controller method Root.login handling the URl given by identity.failure_url (/login) now returns the proper HTTP status code "401 Unauthorized" instead of "403 Forbidden". Please note that this change is reverted in TG 1.1 so that in case of an IdentityFailure exception the 401 status is only returned if HTTP Basic Authentication is enabled, in which case a WWW-Authenticate header is sent along with the 401 response. otherwise a 403 response code is sent again.

These changes might especially affect any AJAX error callbacks in your JavaScript code, e.g. when using the MochiKit loadJSONDoc function.

XHTML Content Type

In TG < 1.0.7 XHTML templates were delivered with a content type of "text/html", while TG 1.0.7 uses "application/xhtml+xml". Please note that this change was reverted in TG 1.0.8 due to compatibility issues with the Internet Explorer.

Updating from 1.0.5 to 1.0.6

Here is a list of changes in the 1.0.6 release which might affect existing applications. For a detailed list of changes, see the 1.0.6 changelog.

Paginate decorator parameter changes

What has changed:
The allow_limit_override parameter to the paginate decorator has been deprecated in favor of the new parameters max_limit.
How to update:
Change allow_limit=True parameter in your paginate decorators to max_limit=None and allow_limit_override=False to max_limit=0.
Trac ticket:
See ticket #1908 for more information.

Updating from 1.0.4 to 1.0.5

Here is a list of changes in 1.0.5 which might affect existing applications. For a detailed list of changes, see the 1.0.5 changelog.

JSON response encoding

What has changed:
The default encoding of JSON responses used to be ASCII with non-ascii values escaped. It is now UTF-8.
How to update:
If your application relies on the old behavior, you can set json.ensure_ascii=True in your application’s configuration.
Trac ticket:
See ticket #1480 for more information.

JSON response content type

What has changed:
The default content type for JSON was changed from text/javascript to application/json.
How to update:
Check the JSON response handling callbacks in your JavaScript code whether they check for a response content type of text/javascript explicitly and change them to check for application/json instead or both.
Trac ticket:
See ticket #1842 for more information.

Package name in configuration

What has changed:
app.cfg in new quickstarted projects now sets the package name. This makes it easier for the i18n framework to find the locales.
How to update:
Add package = "<yourpackage>" to your application’s app.cfg file and substitute <yourpackage> with the package name of your application.
Trac ticket:
See ticket #1631 for more information.

Updating from 1.0.3 to 1.0.4

Release 1.0.4 is only a minor release, so there are no incompatible changes.

There is however a change that affects only the start script of newly quickstarted projects, old projects will still work as they are with 1.0.4. If you still want to update an old project to the new behavior, do the following.

  1. Quickstart a new project with the same name and settings as your old project somewhere in a temporary directory. Substitute <project> and <package> with your actual project resp. package name below.

  2. From the new project, copy the file <project>/<package>/ to the corresponding location in your old project.

  3. From the new project, copy the file <project>/start-<project>.py to the corresponding location in your old project, overwriting the existing start script.

  4. Open the file in your old project with an editor and change the following (again substituting <package> with the actual package name):

    1. Delete the following line:

      scripts = ["start-<package>.py"],
    2. Add the following to the end of the parameters of the setup() call:

      entry_points = {
          'console_scripts': [
              'start-<package> = <package>.commands:start',

Other things you should do when upgrading:

  1. Update your file to align with the boiler plate code in the new project. If you are using SQLAlchemy, you should now import and use metadata and mapper from turbogears.database instead of sqlalchemy.orm (you have to use this mapper at least for the TurboGears identity tables).
  2. Take over possibly missing logger configuration from the config files <project>/dev.cfg and <project>/test.cfg.

For more information, please see the 1.0.4 changelog.

Updating from 1.0.1 to 1.0.2

A new setting identity.saprovider.model.visit resp. identity.soprovider.model.visit has been added to the config. You may want to include this in the app.cfg file of your existing projects to make sure the identity provider picks up the class from your model file. Otherwise it will use a default class which may not match the one in your model file.

Upgrading from SQLAlchemy 0.3 to 0.4

When your project uses SQLAlchemy and you want to upgrade from version 0.3.x to 0.4.x, you need to change a few import statements. There are no TurboGears specific changes.

Add the following line to

from sqlalchemy.orm import mapper, relation, create_session

(Leaving from sqlalchemy import * as is should also work.)


from sqlalchemy.exceptions import SQLError

Updating from 0.9a6+ to 1.0.x

These instructions cover updating existing TurboGears projects that were started with TurboGears versions 0.9a6-1.0b2 to work with TurboGears version 1.0.x, up to and including the latest release 1.0.4.

To be done...

Updating from 0.9a5 to 0.9a6

  • i18n.runTemplateFilter in the config file has been renamed i18n.run_template_filter (#796)

  • For people using FastData (experimental): get_add_url, get_edit_url and get_delete_url all are passed the row instead of the ID now, allowing you to use something other than the ID if desired.

  • In widgets, if you were using a dictionary as params be aware that now the dictionary is not updated at construction or display/render time but simply replaced with the new one. If you were using it to provide default attributes for your widget, take a look at how the TableForm does that.

  • QUICKSTART: quickstart projects that used identity would generate a table called user, which is invalid for some databases. The new quickstart generates tables called tg_user. (#805

    If you have an old project with a generated by a previous version, change the table name of the User object to tg_user by adding the following in the class definition:

    class sqlmeta:

    for SQLObject models. The SQLAlchemy model structure has changed several times since then, so you should probably just generate a new project and copy the identity classes from there.

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/app.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:

  1. Rename to dev.cfg.

  2. Rename to prod.cfg.

  3. mkdir <yourpackage>/config.

  4. Create an empty file in <yourpackage>/config called (to make yourpackage/config a proper Python package).

  5. Rename <yourpackage>/ to “<yourpackage>/config/app.cfg”.

  6. Edit your start-<yourproject>.py file:

    1. Change the references to to dev.cfg.
    2. Change the references to to prod.cfg.
    3. Change the references to <yourpackage>.config to <yourpackage>
  7. Edit dev.cfg and prod.cfg to add [global] at the top of the file.

  8. Edit <yourpackage>/config/app.cfg:

    1. Add [global] at the top of the file

    2. Change any path("something") to [something] (note the removal of quotes)

    3. Change calls to absfile to use %(top_level_dir)s. This diff will give you an idea of the necessary 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:

  • 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 and merge in these changes.
  • 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.
  • 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> 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

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
staticFilter.on = True
staticFilter.dir = "static"

Now, you must now specify:

# 0.9 usage
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.
    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=...).

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