TurboGears 1.1 Upgrade Guide

Ugrading from 1.0 to 1.1

Installation

TurboGears 1.1 uses Genshi as the default templating language, so Kid and the TurboKid buffet templating plug-in are not installed by default when you install TurboGears. If your project uses Kid as the templating language or TG widgets, you will need to install the TurboKid package to run it. Be sure to add the "TurboKid" requirement to the install_requires list in the setup() call of your application’s setup.py file.

If your application uses SQLObject, make also sure that the requirement is listed in the setup.py file. Later 1.0 versions of TurboGears added this requirement automatically when you quickstarted a project using SQLObject, but you should double-check.

Finally, add the correct version to the "TurboGears" requirement:

setup(
    ...
    install_requires=[
        "TurboGears >= 1.1",
        # if your project uses kid templates or TG widgets
        "TurboKid",
        # if your project uses SQLObject
        "SQLObject >= 0.10.1",
        # additional project dependencies
        ...
    ],
    ...
)

Unit Tests

You should edit your test.cfg file and add some more information. The old test.cfg file contained only a dburi, the new file now contains a proper config file structure with a main section and some logging info. The easiest way to handle this is to quickstart a project with the same parameters as the one you want to upgrade and to copy paste the new elements from the resulting test.cfg file.

Then, as a first step after installing TurboGears 1.1 and upgrading your project’s requirements you should fix your application’s unit test using the test migration document. Once all your tests run again, ideally, your work should be finished.

Config Files

If you want to continue using Kid templates by default, make sure you have tg.defaultview = "kid" set (not commented out) in app.cfg.

If your are using SQLite edit your dev.cfg and prod.cfg and make sure the dburi is of the form: "sqlite:///file_name_and_path".

At least the SQLOject dburi is known in some cases to have only two forward slashes where three are needed.

If you are using identity, check that the VisitIdentity class is set via identity.saprovider.model.visit resp. identity.soprovider.model.visit. This setting was introduced in TG 1.0.2 only. Note that the default name for the VisitIdentity table is now visit_identity, not tg_visit_identity. The :doc:`/tg` prefix is now only used for the user and group tables, because the names “user” and “group” are keywords in SQL.

Controller

The deprecated html parameter of the @expose() decorator has gone. Instead of @expose(html='mytemplate') you now need to write @expose(template='mytemplate') or simply @expose('mytemplate').

SQLAlchemy

TurboGears now uses a “plain” SQLAlchemy mapper for mapping database tables to classes, both internally and in quickstarted models. But don’t worry, you can continue to use the old “session aware” mapper from SQLAlchemy if you find this more convenient. It is still provided as database.mapper by TurboGears. The only problem with this is that it has been deprececated in SQLAlchemy 0.5.5, and you will see deprecation warnings. As a solution, an emulation of this mapper is now provided by TurboGears as database.session_mapper and you may want to use this instead of database.mapper. When SQLAlchemy will not provide a session aware mapper any more, database.mapper will be the same as database.session_mapper. The emulated mapper provides the same functionality as the one in SQLAlchemy and there are only minor differences. For instance, both Class.query and Class.query() was possible with the session aware mapper provided by SQLAlchemy, the latter is not possible any more. You should search your application for such code and change query() to query in such cases.

See also the more detailed upgrade hints for SQLAlchemy.

Internationalization

If you still use Kid and i18n and you use translation systems in the form of:

<?python
from turbogears.i18n import translate
?>
<html xmlns:py="http://purl.org/kid/ns#">
    <translate py:match="item.attrib.has_key('lang')" py:replace="translate(item, 'lang')"/>
    <body lang="">
        Welcome
        <p>Welcome</p>
        <p lang="en">Welcome</p>
        <p lang="fi">Welcome</p>
    </body>
</html>

You will now need to import the translate function from the turbogears.i18n.kidutils module as this function is no more exposed in the turbogears.i18n module directly. An example could be:

<?python
from turbogears.i18n.kidutils import translate
?>
<html xmlns:py="http://purl.org/kid/ns#">
    <translate py:match="item.attrib.has_key('lang')" py:replace="translate(item, 'lang')"/>
    <body lang="">
        Welcome
        <p>Welcome</p>
        <p lang="en">Welcome</p>
        <p lang="fi">Welcome</p>
    </body>
</html>

Warning

If you intend to use internationalization for the first time please do not use this outdated and obsolete technique and just use the i18n.run_template_filter configuration parameter to activate auto translation in kid and Genshi templates. Read the internationalization documentation for more information. The recipe above is only shown so that really old sites that used it are not left in the dark wondering why the technique does not work anymore.

turbogears.feed

If you use FeedController from the turbogears.feed package you will get a deprecation warning. The turbogears.feed has been superseded by the external TurboFeeds package and will be removed in future versions of TurboGears.

You can either suppress the deprecation warning or upgrade to TurboFeeds. See the documentation for the warnings standard library module for the first option and the TurboFeeds website for the second.