Contents
The easiest way to upgrade TurboGears itself is to download the latest tgsetup.py 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
From the new project, copy the file <project>/<package>/commands.py to the corresponding location in your old project.
From the new project, copy the file <project>/start-<project>.py to the corresponding location in your old project, overwriting the existing start script.
Open the setup.py file in your old project with an editor and change the following (again substituting <package> with the actual package name):
Delete the following line:
scripts = ["start-<package>.py"],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:
For more information, please see the 1.0.4 changelog.
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.
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 model.py:
from sqlalchemy.orm import mapper, relation, create_session
(Leaving from sqlalchemy import * as is should also work.)
To controllers.py:
from sqlalchemy.exceptions import SQLError
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...
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 model.py generates tables called tg_user. (#805
If you have an old project with a model.py 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:
table="tg_user"
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.
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.
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:
Rename devcfg.py to dev.cfg.
Rename prodcfg.py to prod.cfg.
mkdir <yourpackage>/config.
Create an empty file 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 necessary change:
-static_filter.dir = absfile("${package}", "static") +static_filter.dir = "%(top_level_dir)s/static"
There are a number of changes that will need to be made to your project in order to upgrade to TurboGears 0.9.
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:
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.
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.
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:
# 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."}
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..
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 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.
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.