Navigation

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

Views can now return custom objects which will be serialized to JSON by a
JSON renderer by defining a __json__ method on the object's class. This
method should return values natively serializable by json.dumps (such
as ints, lists, dictionaries, strings, and so forth). See
Serializing Custom Objects for more information. The JSON
renderer now also allows for the definition of custom type adapters to
convert unknown objects to JSON serializations, in case you can't add a
__json__ method to returned objects.

The Mako renderer now supports using a def name in an asset spec. When the
def name is present in the asset spec, the system will render the template
named def within the template instead of rendering the entire template. An
example asset spec which names a def is
package:path/to/template#defname.mako. This will render the def named
defname inside the template.mako template instead of rendering the
entire template. The old way of returning a tuple in the form
('defname',{}) from the view is supported for backward compatibility.

The Chameleon ZPT renderer now supports using a macro name in an asset
spec. When the macro name is present in the asset spec, the system will
render the macro listed as a define-macro and return the result instead
of rendering the entire template. An example asset spec:
package:path/to/template#macroname.pt. This will render the macro
defined as macroname within the template.pt template instead of the
entire template.

As of this release, the request_method view/route predicate, when used,
will also imply that HEAD is implied when you use GET. For
example, using @view_config(request_method='GET') is equivalent to
using @view_config(request_method=('GET','HEAD')). Using
@view_config(request_method=('GET','POST') is equivalent to using
@view_config(request_method=('GET','HEAD','POST'). This is because
HEAD is a variant of GET that omits the body, and WebOb has special support
to return an empty body when a HEAD is used.

pyramid.config.Configurator.add_request_method() has been introduced
to support extending request objects with arbitrary callables. This method
expands on the now documentation-deprecated
pyramid.config.Configurator.set_request_property() by supporting
methods as well as properties. This method also causes less code to be
executed at request construction time than
set_request_property().

When there is a predicate mismatch exception (seen when no view matches for
a given request due to predicates not working), the exception now contains
a textual description of the predicate which didn't match.

An pyramid.config.Configurator.add_permission() directive method was
added to the Configurator. This directive registers a free-standing
permission introspectable into the Pyramid introspection system.
Frameworks built atop Pyramid can thus use the permissions
introspectable category data to build a comprehensive list of permissions
supported by a running system. Before this method was added, permissions
were already registered in this introspectable category as a side effect of
naming them in an pyramid.config.Configurator.add_view() call, this
method just makes it possible to arrange for a permission to be put into
the permissions introspectable category without naming it along with an
associated view. Here's an example of usage of add_permission:

config=Configurator()config.add_permission('view')

The pyramid.session.UnencryptedCookieSessionFactoryConfig() function
now accepts signed_serialize and signed_deserialize hooks which may
be used to influence how the sessions are marshalled (by default this is
done with HMAC+pickle).

Added the pyramid.testing.testConfig() context manager, which can be
used to generate a configurator in a test, e.g. withtesting.testConfig(...):.

A new pyramid.session.check_csrf_token() convenience API function was
added.

A check_csrf view predicate was added. For example, you can now do
config.add_view(someview,check_csrf=True). When the predicate is
checked, if the csrf_token value in request.params matches the csrf
token in the request's session, the view will be permitted to execute.
Otherwise, it will not be permitted to execute.

Add Base.metadata.bind=engine to alchemy scaffold, so that tables
defined imperatively will work.

New physical_path view predicate. If specified, this value should be a
string or a tuple representing the physical traversal path of the context
found via traversal for this predicate to match as true. For example:
physical_path='/' or physical_path='/a/b/c' or physical_path=('','a','b','c'). It's useful when you want to always potentially show a
view when some object is traversed to, but you can't be sure about what kind
of object it will be, so you can't use the context predicate.

Allow a _depth argument to pyramid.view.view_config, which will
permit limited composition reuse of the decorator by other software that
wants to provide custom decorators that are much like view_config.

Allow an iterable of decorators to be passed to
pyramid.config.Configurator.add_view(). This allows views to be wrapped
by more than one decorator without requiring combining the decorators
yourself.

Make it possible to use variable arguments on all p* commands
(pserve, pshell, pviews, etc) in the form a=1b=2 so you can
fill in values in parameterized .ini file, e.g. pshelletc/development.inihttp_port=8080.

In order to allow people to ignore unused arguments to subscriber callables
and to normalize the relationship between event subscribers and subscriber
predicates, we now allow both subscribers and subscriber predicates to accept
only a single event argument even if they've been subscribed for
notifications that involve multiple interfaces.

The Pyramid router no longer adds the values bfg.routes.route or
bfg.routes.matchdict to the request's WSGI environment dictionary.
These values were docs-deprecated in repoze.bfg 1.0 (effectively seven
minor releases ago). If your code depended on these values, use
request.matched_route and request.matchdict instead.

It is no longer possible to pass an environ dictionary directly to
pyramid.traversal.ResourceTreeTraverser.__call__ (aka
ModelGraphTraverser.__call__). Instead, you must pass a request
object. Passing an environment instead of a request has generated a
deprecation warning since Pyramid 1.1.

Pyramid will no longer work properly if you use the
webob.request.LegacyRequest as a request factory. Instances of the
LegacyRequest class have a request.path_info which return a string.
This Pyramid release assumes that request.path_info will
unconditionally be Unicode.

The pyramid.configuration module was removed. It had been deprecated
since Pyramid 1.0 and printed a deprecation warning upon its use. Use
pyramid.config instead.

The pyramid.paster.PyramidTemplate API was removed. It had been
deprecated since Pyramid 1.1 and issued a warning on import. If your code
depended on this, adjust your code to import
pyramid.scaffolds.PyramidTemplate instead.

The pyramid.settings.get_settings() API was removed. It had been
printing a deprecation warning since Pyramid 1.0. If your code depended on
this API, use pyramid.threadlocal.get_current_registry().settings
instead or use the settings attribute of the registry available from
the request (request.registry.settings).

These APIs from the pyramid.testing module were removed. They have
been printing deprecation warnings since Pyramid 1.0:

In Pyramid 1.3 and previous, the __call__ method of a Response object
returned by a view was invoked before any finished callbacks were executed.
As of this release, the __call__ method of a Response object is invoked
after finished callbacks are executed. This is in support of the
pyramid.request.Request.invoke_subrequest() feature.

The pyramid.config.Configurator.set_request_property() directive has
been documentation-deprecated. The method remains usable but the more
featureful pyramid.config.Configurator.add_request_method() should be
used in its place (it has all of the same capabilities but can also extend
the request object with methods).

pyramid.authentication.AuthTktAuthenticationPolicy will emit a
deprecation warning if an application is using the policy without explicitly
passing a hashalg argument. This is because the default is "md5" which is
considered theoretically subject to collision attacks. If you really want
"md5" then you must specify it explicitly to get rid of the warning.

Added an Upgrading Pyramid chapter to the narrative documentation.
It describes how to cope with deprecations and removals of Pyramid APIs and
how to show Pyramid-generated deprecation warnings while running tests and
while running a server.