What's New in Pyramid 1.2

This article explains the new features in Pyramid version 1.2 as compared to its predecessor, 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 The Debug Toolbar for more information.

route_prefix Argument to include

The 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 Using a Route Prefix to Compose Applications for more information.

Tweens

A 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 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 pyramid.config.Configurator.add_tween(). This directive adds a "tween".

Tweens are further described in Registering Tweens.

A new paster command now exists: paster ptweens. This command prints the current tween configuration for an application. See the section entitled ptweens: 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 https://docs.pylonsproject.org/projects/pyramid_exclog/en/latest/).

  • All scaffolds now send the cache_max_age parameter to the add_static_view method.

Minor Feature Additions

  • The [pshell] section in an ini configuration file now treats a setup key as a dotted name that points to a callable that is passed the bootstrap environment. It can mutate the environment as necessary during a paster pshell session. This feature is described in Writing a Script.

  • A new configuration setting named pyramid.includes is now available. It is described in Including Packages.

  • Added a pyramid.security.NO_PERMISSION_REQUIRED constant for use in permission= statements to view configuration. This constant has a value of the string __no_permission_required__. This string value was previously referred to in documentation; now the documentation uses the constant.

  • Added a decorator-based way to configure a response adapter: pyramid.response.response_adapter. This decorator has the same use as pyramid.config.Configurator.add_response_adapter() but it's declarative.

  • The pyramid.events.BeforeRender event now has an attribute named rendering_val. This can be used to introspect the value returned by a view in a BeforeRender subscriber.

  • The Pyramid debug logger now uses the standard logging configuration (usually set up by Paste as part of startup). This means that output from e.g. debug_notfound, debug_authorization, etc. will go to the normal logging channels. The logger name of the debug logger will be the package name of the caller of the Configurator's constructor.

  • A new attribute is available on request objects: exc_info. Its value will be None until an exception is caught by the Pyramid router, after which it will be the result of sys.exc_info().

  • pyramid.testing.DummyRequest now implements the add_finished_callback and add_response_callback methods implemented by pyramid.request.Request.

  • New methods of the pyramid.config.Configurator class: set_authentication_policy() and set_authorization_policy(). These are meant to be consumed mostly by add-on authors who wish to offer packages which register security policies.

  • New Configurator method: pyramid.config.Configurator.set_root_factory(), which can set the root factory after the Configurator has been constructed.

  • Pyramid no longer eagerly commits some default configuration statements at Configurator construction time, which permits values passed in as constructor arguments (e.g. authentication_policy and authorization_policy) to override the same settings obtained via the pyramid.config.Configurator.include() method.

  • Better Mako rendering exceptions; the template line which caused the error is now shown when a Mako rendering raises an exception.

  • New request methods: current_route_url(), current_route_path(), and static_path().

  • New functions in the pyramid.url module: current_route_path() and static_path().

  • The pyramid.request.Request.static_url() API (and its brethren pyramid.request.Request.static_path(), pyramid.url.static_url(), and pyramid.url.static_path()) now accept an absolute filename as a "path" argument. This will generate a URL to an asset as long as the filename is in a directory which was previously registered as a static view. Previously, trying to generate a URL to an asset using an absolute file path would raise a ValueError.

  • The RemoteUserAuthenticationPolicy, AuthTktAuthenticationPolicy, and SessionAuthenticationPolicy constructors now accept an additional keyword argument named debug. By default, this keyword argument is False. When it is True, debug information will be sent to the Pyramid debug logger (usually on stderr) when the authenticated_userid or effective_principals method is called on any of these policies. The output produced can be useful when trying to diagnose authentication-related problems.

  • New view predicate: match_param. Example: a view added via config.add_view(aview, match_param='action=edit') will be called only when the request.matchdict has a value inside it named action with a value of edit.

  • Support an onerror keyword argument to pyramid.config.Configurator.scan(). This argument is passed to venusian.Scanner.scan() to influence error behavior when an exception is raised during scanning.

  • The request_method predicate argument to pyramid.config.Configurator.add_view() and pyramid.config.Configurator.add_route() is now permitted to be a tuple of HTTP method names. Previously it was restricted to being a string representing a single HTTP method name.

  • Undeprecated pyramid.traversal.find_model, pyramid.traversal.model_path, pyramid.traversal.model_path_tuple, and pyramid.url.model_url, which were all deprecated in Pyramid 1.0. There's just not much cost to keeping them around forever as aliases to their renamed resource_* prefixed functions.

  • Undeprecated pyramid.view.bfg_view, which was deprecated in Pyramid 1.0. This is a low-cost alias to pyramid.view.view_config which we'll just keep around forever.

  • Route pattern replacement marker names can now begin with an underscore. See https://github.com/Pylons/pyramid/issues/276.

Deprecations

  • All Pyramid-related 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 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 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 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 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" 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 autocommitting configurator and possibly tests that use the configurator API (the configurator returned by 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 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

  • Narrative and API documentation which used the route_url, route_path, resource_url, static_url, and current_route_url functions in the pyramid.url package have now been changed to use eponymous methods of the request instead.

  • Added a section entitled Using a Route Prefix to Compose Applications to the "URL Dispatch" narrative documentation chapter.

  • Added a new module to the API docs: pyramid.tweens.

  • Added a Registering Tweens section to the "Hooks" narrative chapter.

  • Added a ptweens: Displaying "Tweens" section to the "Command-Line Pyramid" narrative chapter.

  • Added documentation for Explicit Tween Configuration and Including Packages to the "Environment Variables and .ini Files Settings" chapter.

  • Added a Logging 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 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.

  • Added What makes Pyramid unique to the Introduction narrative chapter.

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 pyramid.config.Configurator.scan().

  • The zope.configuration package is no longer a dependency.