What's New in Pyramid 1.9

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

Major Feature Additions

  • The file format used by all p* command line scripts such as pserve and pshell, as well as the pyramid.paster.bootstrap() function is now replaceable thanks to a new dependency on plaster.

    For now, Pyramid is still shipping with integrated support for the PasteDeploy INI format by depending on the plaster_pastedeploy binding library. This may change in the future so it is recommended for applications to start depending on the appropriate plaster binding for their needs.

    See https://github.com/Pylons/pyramid/pull/2985

  • Added an execution policy hook to the request pipeline. An execution policy has the ability to control creation and execution of the request objects before they enter the rest of the pipeline. This means for a single request environ the policy may create more than one request object.

    The execution policy can be replaced using the new pyramid.config.Configurator.set_execution_policy() config directive.

    The first library to use this feature is pyramid_retry.

    Pyramid's default execution policy will attempt to handle and render uncaught exceptions. This is a subtle, but fundamental, change indicating that an exception view may expect to be called outside of the default EXCVIEW tween. There are various predicates available to assist in defining valid exception views for various parts of the pipeline. For example, pyramid_tm defines the tm_active=True predicate which can be applied to exception views that require access to the default transaction. In general this means that exception views may be expected to cover more possible error conditions, including when exceptions occur from tweens that are placed OVER the EXCVIEW tween. If necessary, when provided a response object, you may inspect request.exception or request.exc_info to determine if the response was generated as the result of an exception. See https://github.com/Pylons/pyramid/pull/2964

  • CSRF support has been refactored out of sessions and into its own independent API in the pyramid.csrf module. It supports a pluggable pyramid.interfaces.ICSRFStoragePolicy which can be used to define your own mechanism for generating and validating CSRF tokens. By default, Pyramid continues to use the pyramid.csrf.LegacySessionCSRFStoragePolicy that uses the request.session.get_csrf_token and request.session.new_csrf_token APIs under the hood to preserve compatibility with older Pyramid applications. Two new policies are shipped as well, pyramid.csrf.SessionCSRFStoragePolicy and pyramid.csrf.CookieCSRFStoragePolicy which will store the CSRF tokens in the session and in a standalone cookie, respectively. The storage policy can be changed by using the new pyramid.config.Configurator.set_csrf_storage_policy() config directive.

    CSRF tokens should be used via the new pyramid.csrf.get_csrf_token(), pyramid.csrf.new_csrf_token() and pyramid.csrf.check_csrf_token() APIs in order to continue working if the storage policy is changed. Also, the pyramid.csrf.get_csrf_token() function is now injected into templates to be used conveniently in UI code.

    See https://github.com/Pylons/pyramid/pull/2854 and https://github.com/Pylons/pyramid/pull/3019

Minor Feature Additions

Deprecations

Backward Incompatibilities

  • request.exception and request.exc_info will only be set if the response was generated by the EXCVIEW tween. This is to avoid any confusion where a response was generated elsewhere in the pipeline and not in direct relation to the original exception. If anyone upstream wants to catch and render responses for exceptions they should set request.exception and request.exc_info themselves to indicate the exception that was squashed when generating the response.

    Similar behavior occurs with pyramid.request.Request.invoke_exception_view() in which the exception properties are set to reflect the exception if a response is successfully generated by the method.

    This is a very minor incompatibility. Most tweens right now would give priority to the raised exception and ignore request.exception. This change just improves and clarifies that bookkeeping by trying to be more clear about the relationship between the response and its squashed exception. See https://github.com/Pylons/pyramid/pull/3029 and https://github.com/Pylons/pyramid/pull/3031

Documentation Enhancements