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.
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 “tween” の登録.
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 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
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 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, 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 “tween” の登録 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, 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 Pyramid のユニークな点 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.