Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tag: 1.2a2
Fetching contributors…

Cannot retrieve contributors at this time

257 lines (193 sloc) 11.278 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.

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 is a little like :term:`WSGI` 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 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 middleware has been removed. Configuring error catching / email sending is now the domain of the pyramid_exclog package (see

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.

Documentation Enhancements

  • Narrative and API documentation which used the route_url, route_path, resource_url, static_url, and current_route_url functions in the :mod:`pyramid.url` package have now been changed to use eponymous methods of the request instead.
  • Added a section entitled :ref:`route_prefix` to the "URL Dispatch" narrative documentation chapter.
  • Added a new module to the API docs: :mod:`pyramid.tweens`.
  • Added a :ref:`registering_tweens` section to the "Hooks" narrative chapter.
  • Added a :ref:`displaying_tweens` section to the "Command-Line Pyramid" narrative chapter.
  • Added documentation for :ref:`explicit_tween_config` and :ref:`including_packages` to the "Environment Variables and .ini Files Settings" chapter.
  • Added a :ref:`logging_chapter` chapter to the narrative docs.
  • All tutorials now use - The route_url, route_path, resource_url, static_url, and current_route_url methods of the :class:`pyramid.request.Request` rather than the function variants imported from pyramid.url.
  • The ZODB wiki tutorial now uses the pyramid_zodbconn package rather than the repoze.zodbconn package to provide ZODB integration.

Dependency Changes

  • Pyramid now relies on PasteScript >= 1.7.4. This version contains a feature important for allowing flexible logging configuration.
Jump to Line
Something went wrong with that request. Please try again.