Fetching contributors…
Cannot retrieve contributors at this time
311 lines (232 sloc) 13.2 KB

What's New in Pyramid 1.2

This article explains the new features in :app:`Pyramid` version 1.2 as compared to its predecessor, :app:`Pyramid` 1.1. It also documents backwards incompatibilities between the two versions and deprecations added to Pyramid 1.2, as well as software dependency changes and notable documentation additions.

Major Feature Additions

The major feature additions in Pyramid 1.2 follow.

Debug Toolbar

The scaffolding packages that come with Pyramid now include a debug toolbar component which can be used to interactively debug an application. See :ref:`debug_toolbar` for more information.

route_prefix Argument to include

The :meth:`pyramid.config.Configurator.include` method now accepts a route_prefix argument. This argument allows you to compose URL dispatch applications together from disparate packages. See :ref:`route_prefix` for more information.


A :term:`tween` is used to wrap the Pyramid router's primary request handling function. This is a feature that can be used by Pyramid framework extensions, to provide, for example, view timing support and can provide a convenient place to hang bookkeeping code. Tweens are a little like :term:`WSGI` :term:`middleware`, but have access to Pyramid functionality such as renderers and a full-featured request object.

To support this feature, a new configurator directive exists named :meth:`pyramid.config.Configurator.add_tween`. This directive adds a "tween".

Tweens are further described in :ref:`registering_tweens`.

A new paster command now exists: paster ptweens. This command prints the current tween configuration for an application. See the section entitled :ref:`displaying_tweens` for more info.

Scaffolding Changes

  • All scaffolds now use the pyramid_tm package rather than the repoze.tm2 :term:`middleware` to manage transaction management.
  • The ZODB scaffold now uses the pyramid_zodbconn package rather than the repoze.zodbconn package to provide ZODB integration.
  • All scaffolds now use the pyramid_debugtoolbar package rather than the WebError package to provide interactive debugging features.
  • Projects created via a scaffold no longer depend on the WebError package at all; configuration in the production.ini file which used to require its error_catcher :term:`middleware` has been removed. Configuring error catching / email sending is now the domain of the pyramid_exclog package (see
  • All scaffolds now send the cache_max_age parameter to the add_static_view method.

Minor Feature Additions


  • All Pyramid-related :term:`deployment settings` (e.g. debug_all, debug_notfound) are now meant to be prefixed with the prefix pyramid.. For example: debug_all -> pyramid.debug_all. The old non-prefixed settings will continue to work indefinitely but supplying them may print a deprecation warning. All scaffolds and tutorials have been changed to use prefixed settings.
  • The :term:`deployment settings` dictionary now raises a deprecation warning when you attempt to access its values via __getattr__ instead of via __getitem__.

Backwards Incompatibilities

  • If a string is passed as the debug_logger parameter to a :term:`Configurator`, that string is considered to be the name of a global Python logger rather than a dotted name to an instance of a logger.

  • The :meth:`pyramid.config.Configurator.include` method now accepts only a single callable argument. A sequence of callables used to be permitted. If you are passing more than one callable to :meth:`pyramid.config.Configurator.include`, it will break. You now must now instead make a separate call to the method for each callable.

  • It may be necessary to more strictly order configuration route and view statements when using an "autocommitting" :term:`Configurator`. In the past, it was possible to add a view which named a route name before adding a route with that name when you used an autocommitting configurator. For example:

    config = Configurator(autocommit=True)
    config.add_view('my.pkg.someview', route_name='foo')
    config.add_route('foo', '/foo')

    The above will raise an exception when the view attempts to add itself. Now you must add the route before adding the view:

    config = Configurator(autocommit=True)
    config.add_route('foo', '/foo')
    config.add_view('my.pkg.someview', route_name='foo')

    This won't effect "normal" users, only people who have legacy BFG codebases that used an autommitting configurator and possibly tests that use the configurator API (the configurator returned by :func:`pyramid.testing.setUp` is an autocommitting configurator). The right way to get around this is to use a default non-autocommitting configurator, which does not have these directive ordering requirements:

      config = Configurator()
      config.add_view('my.pkg.someview', route_name='foo')
      config.add_route('foo', '/foo')
    The above will work fine.
  • The :meth:`pyramid.config.Configurator.add_route` directive no longer returns a route object. This change was required to make route vs. view configuration processing work properly.

Behavior Differences

  • An ETag header is no longer set when serving a static file. A Last-Modified header is set instead.
  • Static file serving no longer supports the wsgi.file_wrapper extension.
  • Instead of returning a 403 Forbidden error when a static file is served that cannot be accessed by the Pyramid process' user due to file permissions, an IOError (or similar) will be raised.

Documentation Enhancements

Dependency Changes

  • Pyramid now relies on PasteScript >= 1.7.4. This version contains a feature important for allowing flexible logging configuration.
  • Pyramid now requires Venusian 1.0a1 or better to support the onerror keyword argument to :meth:`pyramid.config.Configurator.scan`.
  • The zope.configuration package is no longer a dependency.