Skip to content
This repository
branch: feature.metavi…
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 311 lines (232 sloc) 13.461 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.

System Message: ERROR/3 (<string>, line 4); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 4); backlink

Unknown interpreted text role "app".

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.

System Message: ERROR/3 (<string>, line 18); backlink

Unknown interpreted text role "ref".

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.

System Message: ERROR/3 (<string>, line 25); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 25); backlink

Unknown interpreted text role "ref".

Tweens

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.

System Message: ERROR/3 (<string>, line 33); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 33); backlink

Unknown interpreted text role "term".

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

System Message: ERROR/3 (<string>, line 40); backlink

Unknown interpreted text role "meth".

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

System Message: ERROR/3 (<string>, line 44); backlink

Unknown interpreted text role "ref".

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.

System Message: ERROR/3 (<string>, line 46); backlink

Unknown interpreted text role "ref".

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 http://docs.pylonsproject.org/projects/pyramid_exclog/dev/).
  • 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 :ref:`writing_a_script`.

    System Message: ERROR/3 (<string>, line 74); backlink

    Unknown interpreted text role "ref".

  • A new configuration setting named pyramid.includes is now available. It is described in :ref:`including_packages`.

    System Message: ERROR/3 (<string>, line 80); backlink

    Unknown interpreted text role "ref".

  • Added a :data:`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.

    System Message: ERROR/3 (<string>, line 83); backlink

    Unknown interpreted text role "data".

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

    System Message: ERROR/3 (<string>, line 89); backlink

    Unknown interpreted text role "class".

    System Message: ERROR/3 (<string>, line 89); backlink

    Unknown interpreted text role "meth".

  • The :class:`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.

    System Message: ERROR/3 (<string>, line 94); backlink

    Unknown interpreted text role "class".

  • 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().

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

    System Message: ERROR/3 (<string>, line 108); backlink

    Unknown interpreted text role "class".

    System Message: ERROR/3 (<string>, line 108); backlink

    Unknown interpreted text role "class".

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

    System Message: ERROR/3 (<string>, line 112); backlink

    Unknown interpreted text role "class".

    System Message: ERROR/3 (<string>, line 112); backlink

    Unknown interpreted text role "meth".

    System Message: ERROR/3 (<string>, line 112); backlink

    Unknown interpreted text role "meth".

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

    System Message: ERROR/3 (<string>, line 118); backlink

    Unknown interpreted text role "meth".

  • Pyramid no longer eagerly commits some default configuration statements at :term:`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 :meth:`pyramid.config.Configurator.include` method.

    System Message: ERROR/3 (<string>, line 122); backlink

    Unknown interpreted text role "term".

    System Message: ERROR/3 (<string>, line 122); backlink

    Unknown interpreted text role "meth".

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

  • New request methods: :meth:`~pyramid.request.Request.current_route_url`, :meth:`~pyramid.request.Request.current_route_path`, and :meth:`~pyramid.request.Request.static_path`.

    System Message: ERROR/3 (<string>, line 131); backlink

    Unknown interpreted text role "meth".

    System Message: ERROR/3 (<string>, line 131); backlink

    Unknown interpreted text role "meth".

    System Message: ERROR/3 (<string>, line 131); backlink

    Unknown interpreted text role "meth".

  • New functions in the :mod:`pyramid.url` module: :func:`~pyramid.url.current_route_path` and :func:`~pyramid.url.static_path`.

    System Message: ERROR/3 (<string>, line 135); backlink

    Unknown interpreted text role "mod".

    System Message: ERROR/3 (<string>, line 135); backlink

    Unknown interpreted text role "func".

    System Message: ERROR/3 (<string>, line 135); backlink

    Unknown interpreted text role "func".

  • The :meth:`pyramid.request.Request.static_url` API (and its brethren :meth:`pyramid.request.Request.static_path`, :func:`pyramid.url.static_url`, and :func:`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.

    System Message: ERROR/3 (<string>, line 139); backlink

    Unknown interpreted text role "meth".

    System Message: ERROR/3 (<string>, line 139); backlink

    Unknown interpreted text role "meth".

    System Message: ERROR/3 (<string>, line 139); backlink

    Unknown interpreted text role "func".

    System Message: ERROR/3 (<string>, line 139); backlink

    Unknown interpreted text role "func".

  • The :class:`~pyramid.authentication.RemoteUserAuthenticationPolicy`, :class:`~pyramid.authentication.AuthTktAuthenticationPolicy`, and :class:`~pyramid.authentication.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.

    System Message: ERROR/3 (<string>, line 147); backlink

    Unknown interpreted text role "class".

    System Message: ERROR/3 (<string>, line 147); backlink

    Unknown interpreted text role "class".

    System Message: ERROR/3 (<string>, line 147); backlink

    Unknown interpreted text role "class".

  • 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 :meth:`pyramid.config.Configurator.scan``. This argument is passed to :meth:`venusian.Scanner.scan` to influence error behavior when an exception is raised during scanning.

    System Message: ERROR/3 (<string>, line 162); backlink

    Unknown interpreted text role "meth".

    System Message: ERROR/3 (<string>, line 162); backlink

    Unknown interpreted text role "meth".

  • The request_method predicate argument to :meth:`pyramid.config.Configurator.add_view` and :meth:`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.

    System Message: ERROR/3 (<string>, line 167); backlink

    Unknown interpreted text role "meth".

    System Message: ERROR/3 (<string>, line 167); backlink

    Unknown interpreted text role "meth".

  • 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 :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.

    System Message: ERROR/3 (<string>, line 189); backlink

    Unknown interpreted text role "term".

  • The :term:`deployment settings` dictionary now raises a deprecation warning when you attempt to access its values via __getattr__ instead of via __getitem__.

    System Message: ERROR/3 (<string>, line 196); backlink

    Unknown interpreted text role "term".

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.

    System Message: ERROR/3 (<string>, line 203); backlink

    Unknown interpreted text role "term".

  • 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.

    System Message: ERROR/3 (<string>, line 207); backlink

    Unknown interpreted text role "meth".

    System Message: ERROR/3 (<string>, line 207); backlink

    Unknown interpreted text role "meth".

  • 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:

    System Message: ERROR/3 (<string>, line 213); backlink

    Unknown interpreted text role "term".

    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:

    System Message: ERROR/3 (<string>, line 234); backlink

    Unknown interpreted text role "func".

      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.

    System Message: ERROR/3 (<string>, line 249); backlink

    Unknown interpreted text role "meth".

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 :mod:`pyramid.url` package have now been changed to use eponymous methods of the request instead.

    System Message: ERROR/3 (<string>, line 268); backlink

    Unknown interpreted text role "mod".

  • Added a section entitled :ref:`route_prefix` to the "URL Dispatch" narrative documentation chapter.

    System Message: ERROR/3 (<string>, line 273); backlink

    Unknown interpreted text role "ref".

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

    System Message: ERROR/3 (<string>, line 276); backlink

    Unknown interpreted text role "mod".

  • Added a :ref:`registering_tweens` section to the "Hooks" narrative chapter.

    System Message: ERROR/3 (<string>, line 278); backlink

    Unknown interpreted text role "ref".

  • Added a :ref:`displaying_tweens` section to the "Command-Line Pyramid" narrative chapter.

    System Message: ERROR/3 (<string>, line 280); backlink

    Unknown interpreted text role "ref".

  • Added documentation for :ref:`explicit_tween_config` and :ref:`including_packages` to the "Environment Variables and .ini Files Settings" chapter.

    System Message: ERROR/3 (<string>, line 283); backlink

    Unknown interpreted text role "ref".

    System Message: ERROR/3 (<string>, line 283); backlink

    Unknown interpreted text role "ref".

  • Added a :ref:`logging_chapter` chapter to the narrative docs.

    System Message: ERROR/3 (<string>, line 287); backlink

    Unknown interpreted text role "ref".

  • 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.

    System Message: ERROR/3 (<string>, line 289); backlink

    Unknown interpreted text role "class".

  • The ZODB wiki tutorial now uses the pyramid_zodbconn package rather than the repoze.zodbconn package to provide ZODB integration.

  • Added :ref:`what_makes_pyramid_unique` to the Introduction narrative chapter.

    System Message: ERROR/3 (<string>, line 297); backlink

    Unknown interpreted text role "ref".

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`.

    System Message: ERROR/3 (<string>, line 307); backlink

    Unknown interpreted text role "meth".

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

Something went wrong with that request. Please try again.