Upgrading your project is slightly different depending on which versions you're upgrading from and to. It's recommended that upgrades be done in minor revision steps, as deprecation warnings are added between revisions to help in the upgrade process.

For example, if you're running 0.9.4, first upgrade to 0.9.5, then 0.9.6, then finally 0.9.7 when desired. The change to 0.9.7 can be done in two steps unlike the older upgrades which should follow the process documented here after the 0.9.7 upgrade.

Upgrading from 0.9.6 -> 0.9.7

Pylons 0.9.7 changes several implicit behaviors of 0.9.6, as well as toggling some new options of Routes, and using automatic HTML escaping in Mako. These changes can be done in waves, and do not need to be completed all at once for a 0.9.6 project to run under 0.9.7.

Minimal Steps to run a 0.9.6 project under 0.9.7

Add the following lines to config/environment.py:

# Add these imports to the top
from beaker.middleware import CacheMiddleware, SessionMiddleware
from routes.middleware import RoutesMiddleware

# Add these below the 'CUSTOM MIDDLEWARE HERE' line, or if you removed
# that, add them immediately after the PylonsApp initialization
app = RoutesMiddleware(app, config['routes.map'])
app = SessionMiddleware(app, config)
app = CacheMiddleware(app, config)

The default behavior of the 'c' object has changed in 0.9.7, to the 'strict_c' behavior which will throw an exception if an attribute is accessed of 'c' that doesn't exist. The pre-0.9.7 behavior can be restored by adding the following to config/environment.py:

1 2	# After config.init_app: config['pylons.strict_c'] = False

Action arguments are no longer attached to 'c' by default as well, to restore the old implicit behavior add the following line to config/environment.py:

1 2	# After config.init_app: config['pylons.c_attach_args'] = True

The Rails helpers from WebHelpers are no longer automatically imported in the webhelpers package. To use them 'lib/helpers.py' should be changed to import them:

1	from webhelpers.rails import *

Your Pylons 0.9.6 project should now run without issue in Pylons 0.9.7. Note that some deprecation warnings will likely be thrown reminding you to upgrade other parts.

Moving to use the new features of 0.9.7

To use the complete set of new features in 0.9.7, such as the automatic HTML escaping, new webhelpers, and new error middleware, follow the What's new in Pylons 0.9.7 overview to determine how to change the other files in your project to use the new features.

Moving from a pre-0.9.6 to 0.9.6

Pylons projects should be updated using the paster command create. In addition to creating new projects, paster create when run over an existing project will provide several ways to update the project template to the latest version.

Using this tool properly can make upgrading a fairly minor task. For the purpose of this document, the project being upgraded will be called 'demoapp' and all commands will use that name.

Running paster create to upgrade

You'll first need to cd to the directory above your projects main directory. The main directory is the one that contains your setup.py, setup.cfg, and development.ini files.

1 2
/home/joe/demoapp $ cd .. /home/joe $

Then run paster create on the project directory:

1
/home/joe $ paster create demoapp -t pylons

paster will prompt you on how to handle conflicts and updates to the existing project files. The options let you (hit the key in the parens to perform the operation):

(d)iff them, and show you the changes between your projects file and the one: that has changed in Pylons
(b)ackup the file, and copy the new version into its place. The old one will: end in .bak
(y)es to overwrite the existing file with the new one. Not recommended since: you will then have no way to see your existing one, unless you have seen the diff first and know there is no changes you're losing.
(n)o to overwrite, and just keep your existing file. Also safe if you know: that nothing has changed.

It's recommended when upgrading your project that you always look at the diff first to see whats changed. Then either overwrite your existing one if you are not going to lose changes you want, or backup yours and write the new one in. You can then manually compare and add your changes back in.