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.
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.
Add the following lines to config/middleware.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 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:
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.
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.
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.
First, navigate to the directory above the project’s main directory. The main directory is the one that contains the setup.py, setup.cfg, and development.ini files.
/home/joe/demoapp $ cd ..
/home/joe $
Then run paster create on the project directory:
/home/joe $ paster create demoapp -t pylons
paster will issue prompts to allow the handling conflicts and updates to the existing project files. The options available are (hit the key in the parens to perform the operation):
(d)iff them, and show the changes between the project files and the ones
that have changed in Pylons
(b)ackup the file and copy the new version into its place. The backup file that
is created will have a ``.bak`` extension.
(y)es to overwrite the existing file with the new one. This approach is generally
not recommended as it does not allow the developer to view the content of the file
that will be replaced and it offers no opportunity for later recovery of the content.
The option can be made less intrepid by first viewing the diff to ascertain if any
changes will be lost in the overwriting.
(n)o to overwrite, retain the existing file. Safe if nothing has changed.
It’s recommended when upgrading your project that you always look at the diff first to see what has 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.
Powered by Pylons - Contact Administrators
Comments (7)
In the “Running paster create to upgrade” section, I’d add:
If you use “paster create” to update your project, you might want to leave base.py alone. “paster create” does not update your controllers. In previous versions of Pylons, a lot of things were pulled into your controller’s namespace automatically due to imports in base.py. This is no longer the case, and you need to import things in your controllers manually. Hence, upgrading base.py might cause your controllers to stop working. If you don’t object to the way things used to work, it’s safe to leave base.py alone.
“AttributeError: ‘module’ object has no attribute ‘url_for’”
If you use h.url_for in your controllers, it’s no longer available by default. This will bite you if you use “paster create” to update your project. To get around this problem, add “from routes import url_for” to your helpers.py.
The jsonify decorator used to set the Content-Type to text/javascript. It now uses application/json. If you’ve implemented your own jsonp support using the jsonify decorator, you’ll need to manually change your Content-Type back to “text/javascript; charset=utf-8”. If you leave out the charset part, WebOb might end up raising a weird exception.
There were actually quite a few changes to the helpers, so some porting will be necessary. For instance, I was a bit surprised to find out that stylesheet_link_tag was gone. It’s been renamed stylesheet_link.
Since I decided to keep my old base.py (since I like the automatic imports), I had to manually change how I imported render to “from pylons.templating import render_mako as render” in base.py. The old render function is still available, and it’s different from the new render function. I’m guessing this isn’t a big deal.
If you have code that sets response.status_code, you’ll need to update it to set response.status_int. Beware, if you don’t do this, you won’t see an error.
If you set response.status_int to a value like 400 in order to show an application-specific 400 error page, you may find that your page gets injected into the template used for other Pylons errors. To tell the middleware not to do this, add the following near where you set response.status_int:
request.environ[‘pylons.status_code_redirect’] = True
If you don’t use the Pylons-specific way of running nose (i.e. the way that involves setuptools and uses setup.cfg), you’ll need to add ”—with-pylons=mywebapp/test.ini” to your nosetests invocation.
Suggest an addition to the docs, or report errors. Note that we will delete documentation fixes as they're applied.
You must login before you can comment.