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¶
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.
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
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
EXCVIEWtween. There are various predicates available to assist in defining valid exception views for various parts of the pipeline. For example,
tm_active=Truepredicate 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
EXCVIEWtween. If necessary, when provided a
responseobject, you may inspect
request.exc_infoto 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.csrfmodule. It supports a pluggable
pyramid.interfaces.ICSRFStoragePolicywhich can be used to define your own mechanism for generating and validating CSRF tokens. By default, Pyramid continues to use the
pyramid.csrf.LegacySessionCSRFStoragePolicythat uses the
request.session.new_csrf_tokenAPIs under the hood to preserve compatibility with older Pyramid applications. Two new policies are shipped as well,
pyramid.csrf.CookieCSRFStoragePolicywhich will store the CSRF tokens in the session and in a standalone cookie, respectively. The storage policy can be changed by using the new
CSRF tokens should be used via the new
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.
Minor Feature Additions¶
open_urlconfig setting in the
pservesection of the config file. This url is used to open a web browser when
pserve --browseris invoked. When this setting is unavailable the
pservescript will attempt to guess the port the server is using from the
server:<server_name>section of the config file but there is no requirement that the server is being run in this format so it may fail. See https://github.com/Pylons/pyramid/pull/2984
pyramid.config.Configuratorcan now be used as a context manager which will automatically push/pop threadlocals (similar to
pyramid.config.Configurator.end()). It will also automatically perform a
pyramid.config.Configurator.commit()at the end and thus it is only recommended to be used at the top-level of your app. See https://github.com/Pylons/pyramid/pull/2874
The threadlocals are now available inside any function invoked via
pyramid.config.Configurator.include(). This means the only config-time code that cannot rely on threadlocals is code executed from non-actions inside the main. This can be alleviated by invoking
pyramid.config.Configurator.end()appropriately or using the new context manager feature of the configurator. See https://github.com/Pylons/pyramid/pull/2989
The threadlocals are now available inside exception views invoked via
pyramid.request.Request.invoke_exception_view()even when the
requestargument is overridden. See https://github.com/Pylons/pyramid/pull/3060
When unsupported predicates are supplied to
pyramid.config.Configurator.add_subscriber()a much more helpful error message is output with a guess as to which predicate was intended. See https://github.com/Pylons/pyramid/pull/3054
Normalize the permission results to a proper class hierarchy.
pyramid.security.ACLAllowedis now a subclass of
pyramid.security.ACLDeniedis now a subclass of
pyramid.security.Denied. See https://github.com/Pylons/pyramid/pull/3084
pyramid.encode.urlencode()to follow the stdlib's version and enable custom quoting functions. See https://github.com/Pylons/pyramid/pull/3088
Support _query=None and _anchor=None in
pyramid.request.Request.route_url()as well as
pyramid.request.Request.resource_url(). Previously this would cause an ? and a #, respectively, in the url with nothing after it. Now the unnecessary parts are dropped from the generated URL. See https://github.com/Pylons/pyramid/pull/3034
Pyramid currently depends on
plaster_pastedeployto simplify the transition to
plasterby maintaining integrated support for INI files. This dependency on
plaster_pastedeployshould be considered subject to Pyramid's deprecation policy and may be removed in the future. Applications should depend on the appropriate plaster binding to satisfy their needs.
Retrieving CSRF token from the session has been deprecated in favor of equivalent methods in the
pyramid.csrfmodule. The CSRF methods (
ISession.new_csrf_token) are no longer required on the
pyramid.interfaces.ISessioninterface except when using the default
request.exc_infowill 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.exc_infothemselves 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