Upgrading

1.0 -> 1.0.1

No changes are necessary, however to take advantage of MarkupSafe’s faster HTML escaping, the default filter in environment.py that Mako is configured with should be changed from:

from webhelpers.html import escape
To::
from markupsafe import escape

MarkupSafe utilizes a C extension where available for faster escaping which can help on larger pages with substantial variable substitutions.

0.9.7 -> 1.0

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 any project prior to 0.9.7, you should first follow the applicable docs to upgrade to 0.9.7 before proceeding.

To upgrade to 1.0, first upgrade your project to 0.10. This is a Pylons release that is fully backwards-compatible with 0.9.7. However under 0.10 a variety of warnings will be issued about the various things that need to be changed before upgrading to 1.0.

Tip

Since Pylons 0.10 is only out as a beta at this point, upgrade using the actual URL, for example:

$ easy_install -U http://pylonshq.com/download/0.10/Pylons-0.10.tar.gz

Beyond the warnings issued, you should also read the following list and ensure these changes have been applied.

Pylons changes from 0.9.7 to 1.0:

  • The config object created in environment.py is now passed around explicitly. There are also some other minor updates as follows.

    Update config/environment.py to initialize and return the config:

    # Add to the imports:
    from pylons.configuration import PylonsConfig
    
    # Add under 'def load_environment':
    config = PylonsConfig()
    
    # Replace the make_map / app globals line with
    config['routes.map'] = make_map(config)
    config['pylons.app_globals'] = app_globals.Globals(config)
    
    # Optionally, if removing the CacheMiddleware and using the
    # cache in the new 1.0 style, add under the previous lines:
    import pylons
    pylons.cache._push_object(config['pylons.app_globals'].cache)
    
    
    # Add at the end of the load_environment function:
    return config
    

    Update config/middleware.py to use the returned config:

    # modify the load_environment call:
    config = load_environment(global_conf, app_conf)
    
    # update the middleware calls
    
    # The Pylons WSGI app
    app = PylonsApp(config=config)
    
    # Routing/Session/Cache Middleware
    app = RoutesMiddleware(app, config['routes.map'])
    app = SessionMiddleware(app, config)
    
    # CUSTOM MIDDLEWARE HERE (filtered by error handling middlewares)
    
    # Add right before 'return app':
    app.config = config
    

    Note

    The CacheMiddleware is no longer setup by default through middleware, its now setup under app_globals inside its instantiation in lib/app_globals.py.

    Update config/routing.py to accept the config:

    # Replace the def line with
    def make_map(config):
    

    Update lib/app_globals.py to accept the config:

    # Replace the __init__ line with
    def __init__(self, config):
    
    # Optionally, if you decided to remove the CacheMiddleware
    # Add these imports
    from beaker.cache import CacheManager
    from beaker.util import parse_cache_config_options
    
    # and add this line in __init__:
    self.cache = CacheManager(**parse_cache_config_options(config))
    

    Update tests/__init__.py as needed:

    from unittest import TestCase
    
    from paste.deploy import loadapp
    from paste.script.appinstall import SetupCommand
    from pylons import url
    from routes.util import URLGenerator
    from webtest import TestApp
    
    import pylons.test
    
    __all__ = ['environ', 'url', 'TestController']
    
    # Invoke websetup with the current config file
    SetupCommand('setup-app').run([pylons.test.pylonsapp.config['__file__']])
    
    environ = {}
    
    class TestController(TestCase):
    
        def __init__(self, *args, **kwargs):
            wsgiapp = pylons.test.pylonsapp
            config = wsgiapp.config
            self.app = TestApp(wsgiapp)
            url._push_object(URLGenerator(config['routes.map'], environ))
            TestCase.__init__(self, *args, **kwargs)
    

    Note

    Change the use of url_for in your tests to use url, which is imported from tests/__init__.py in your unit tests.

    Finally, update websetup.py to avoid the duplicate app creation that previously could occur during the unit tests:

    # Add to the imports
    import pylons.test
    
    # Add under the 'def setup_app':
    
    # Don't reload the app if it was loaded under the testing environment
    if not pylons.test.pylonsapp:
        load_environment(conf.global_conf, conf.local_conf)
    
  • Change all instances of redirect_to(...) -> redirect(url(...))

    redirect_to processed arguments in a slightly ‘magical’ manner in that some of them went to the url_for while sometimes... not. redirect() issues a redirect and nothing more, so to generate a url, the url instance should be used (import: from pylons import url).

  • Ensure that all use of g is switched to using the new name, app_globals

  • Change all instances of url_for to url.

    Note that url does not retain the current route memory like url_for did by default. To get a route generated using the current route, call url.current.

    For example:

    # Rather than url_for() for the current route
    url.current()
    

    url can be imported from pylons.

  • Change config import statement if needed

    Previously, the config object could be imported as if it was a module:

    import pylons.config
    

    The config object is now an object in pylons/__init__.py so the import needs to be changed to:

    from pylons import config
    
  • Routes is now explicit by default

    This won’t affect those already using url as it ignores route memory. This change does mean that some routes which relied on a default controller of ‘content’ and a default action of ‘index’ will not work.

    To restore the old behavior, in config/routing.py, set the mapper to explicit:

    map.explicit = True
    
  • By default, the tmpl_context (a.k.a ‘c’), is no longer a AttribSafeContextObj. This means accessing attributes that don’t exist will raise an AttributeError.

    To use the attribute-safe tmpl_context, add this line to the config/environment.py:

    config['pylons.strict_tmpl_context'] = False