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 is 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
Displaying “Tweens” for more info.
Scaffolding Changes¶
- All scaffolds now use the
pyramid_tm
package rather than therepoze.tm2
middleware to manage transaction management. - The ZODB scaffold now uses the
pyramid_zodbconn
package rather than therepoze.zodbconn
package to provide ZODB integration. - All scaffolds now use the
pyramid_debugtoolbar
package rather than theWebError
package to provide interactive debugging features. - Projects created via a scaffold no longer depend on the
WebError
package at all; configuration in theproduction.ini
file which used to require itserror_catcher
middleware has been removed. Configuring error catching / email sending is now the domain of thepyramid_exclog
package (see http://docs.pylonsproject.org/projects/pyramid_exclog/dev/). - All scaffolds now send the
cache_max_age
parameter to theadd_static_view
method.
Minor Feature Additions¶
- The
[pshell]
section in an ini configuration file now treats asetup
key as a dotted name that points to a callable that is passed the bootstrap environment. It can mutate the environment as necessary during apaster 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 inpermission=
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 aspyramid.config.Configurator.add_response_adapter()
but it’s declarative. - The
pyramid.events.BeforeRender
event now has an attribute namedrendering_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 beNone
until an exception is caught by the Pyramid router, after which it will be the result ofsys.exc_info()
. pyramid.testing.DummyRequest
now implements theadd_finished_callback
andadd_response_callback
methods implemented bypyramid.request.Request
.- New methods of the
pyramid.config.Configurator
class:set_authentication_policy()
andset_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
andauthorization_policy
) to override the same settings obtained via thepyramid.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()
, andstatic_path()
. - New functions in the
pyramid.url
module:current_route_path()
andstatic_path()
. - The
pyramid.request.Request.static_url()
API (and its brethrenpyramid.request.Request.static_path()
,pyramid.url.static_url()
, andpyramid.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
, andSessionAuthenticationPolicy
constructors now accept an additional keyword argument nameddebug
. By default, this keyword argument isFalse
. When it isTrue
, debug information will be sent to the Pyramid debug logger (usually on stderr) when theauthenticated_userid
oreffective_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 viaconfig.add_view(aview, match_param='action=edit')
will be called only when therequest.matchdict
has a value inside it namedaction
with a value ofedit
. - Support an
onerror
keyword argument topyramid.config.Configurator.scan`()
. This argument is passed tovenusian.Scanner.scan()
to influence error behavior when an exception is raised during scanning. - The
request_method
predicate argument topyramid.config.Configurator.add_view()
andpyramid.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
, andpyramid.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 renamedresource_*
prefixed functions. - Undeprecated
pyramid.view.bfg_view
, which was deprecated in Pyramid 1.0. This is a low-cost alias topyramid.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 prefixpyramid.
. 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 singlecallable
argument. A sequence of callables used to be permitted. If you are passing more than onecallable
topyramid.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 autommitting 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
, andcurrent_route_url
functions in thepyramid.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 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
, andcurrent_route_url
methods of thepyramid.request.Request
rather than the function variants imported frompyramid.url
. - The ZODB wiki tutorial now uses the
pyramid_zodbconn
package rather than therepoze.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 topyramid.config.Configurator.scan()
. - The
zope.configuration
package is no longer a dependency.