Navigation

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

Pyramid no longer depends on or configures the Mako and Chameleon templating
system renderers by default. Disincluding these templating systems by
default means that the Pyramid core has fewer dependencies and can run on
future platforms without immediate concern for the compatibility of its
templating add-ons. It also makes maintenance slightly more effective, as
different people can maintain the templating system add-ons that they
understand and care about without needing commit access to the Pyramid core,
and it allows users who just don't want to see any packages they don't use
come along for the ride when they install Pyramid.

This means that upon upgrading to Pyramid 1.5a2+, projects that use either
of these templating systems will see a traceback that ends something like
this when their application attempts to render a Chameleon or Mako template:

ValueError:Nosuchrendererfactory.pt

Or:

ValueError:Nosuchrendererfactory.mako

Or:

ValueError:Nosuchrendererfactory.mak

Support for Mako templating has been moved into an add-on package named
pyramid_mako, and support for Chameleon templating has been moved into
an add-on package named pyramid_chameleon. These packages are drop-in
replacements for the old built-in support for these templating langauges.
All you have to do is install them and make them active in your configuration
to register renderer factories for .pt and/or .mako (or .mak) to
make your application work again.

Make sure the pyramid_mako package is installed. One way to do this
is by adding pyramid_mako to the install_requires section of your
package's setup.py file and afterwards rerunning setup.pydevelop:

setup(#...install_requires=['pyramid_mako',# new dependency'pyramid',#...],)

Within the portion of your application which instantiates a Pyramid
Configurator (often the main() function in
your project's __init__.py file), tell Pyramid to include the
pyramid_mako includeme:

config=Configurator(.....)config.include('pyramid_mako')

If you depend on Chameleon templates:

Make sure the pyramid_chameleon package is installed. One way to do
this is by adding pyramid_chameleon to the install_requires section
of your package's setup.py file and afterwards rerunning
setup.pydevelop:

setup(#...install_requires=['pyramid_chameleon',# new dependency'pyramid',#...],)

Within the portion of your application which instantiates a Pyramid
Configurator (often the main() function in
your project's __init__.py file), tell Pyramid to include the
pyramid_chameleon includeme:

config=Configurator(.....)config.include('pyramid_chameleon')

Note that it's also fine to install these packages into older Pyramids for
forward compatibility purposes. Even if you don't upgrade to Pyramid 1.5
immediately, performing the above steps in a Pyramid 1.4 installation is
perfectly fine, won't cause any difference, and will give you forward
compatibility when you eventually do upgrade to Pyramid 1.5.

With the removal of Mako and Chameleon support from the core, some
unit tests that use the pyramid.renderers.render* methods may begin to
fail. If any of your unit tests are invoking either
pyramid.renderers.render() or pyramid.renderers.render_to_response()
with either Mako or Chameleon templates then the
pyramid.config.Configurator instance in effect during
the unit test should be also be updated to include the addons, as shown
above. For example:

If you're using the Pyramid debug toolbar, when you upgrade Pyramid to
1.5a2+, you'll also need to upgrade the pyramid_debugtoolbar package to
at least version 1.0.8, as older toolbar versions are not compatible with
Pyramid 1.5a2+ due to the removal of Mako support from the core. It's
fine to use this newer version of the toolbar code with older Pyramids too.

View lookup will now search for valid views based on the inheritance
hierarchy of the context. It tries to find views based on the most specific
context first, and upon predicate failure, will move up the inheritance chain
to test views found by the super-type of the context. In the past, only the
most specific type containing views would be checked and if no matching view
could be found then a PredicateMismatch would be raised. Now predicate
mismatches don't hide valid views registered on super-types. Here's an
example that now works:

The pyramid.authentication.AuthTktPolicy now supports IPv6
addresses when using the include_ip=True option. This is possibly
incompatible with alternative auth_tkt implementations, as the
specification does not define how to properly handle IPv6. See
https://github.com/Pylons/pyramid/issues/831.

The request.session.check_csrf_token() method and the check_csrf view
predicate now take into account the value of the HTTP header named
X-CSRF-Token (as well as the csrf_token form parameter, which they
always did). The header is tried when the form parameter does not exist.

You can now generate "hybrid" urldispatch/traversal URLs more easily by using
the new route_name, route_kw and route_remainder_name arguments
to resource_url() and
resource_path(). See
Generating Hybrid URLs.

A new http exception superclass named
HTTPSuccessful was added. You can use this
class as the context of an exception view to catch all 200-series
"exceptions" (e.g. "raise HTTPOk"). This also allows you to catch only the
HTTPOk exception itself; previously this was
impossible because a number of other exceptions (such as HTTPNoContent)
inherited from HTTPOk, but now they do not.

It is now possible to escape double braces in Pyramid scaffolds (unescaped,
these represent replacement values). You can use \{\{a\}\} to
represent a "bare" {{a}}. See
https://github.com/Pylons/pyramid/pull/862

The pserve command now takes a -v (or --verbose) flag and a
-q (or --quiet) flag. Output from running pserve can be
controlled using these flags. -v can be specified multiple times to
increase verbosity. -q sets verbosity to 0 unconditionally. The
default verbosity level is 1.

Added a new SignedCookieSessionFactory which is very similar to the
UnencryptedCookieSessionFactoryConfig but with a clearer focus on
signing content. The custom serializer arguments to this function should
only focus on serializing, unlike its predecessor which required the
serializer to also perform signing.
See https://github.com/Pylons/pyramid/pull/1142 . Note
that cookies generated using SignedCookieSessionFactory are not
compatible with cookies generated using UnencryptedCookieSessionFactory,
so existing user session data will be destroyed if you switch to it.

Added a new BaseCookieSessionFactory which acts as a generic cookie
factory that can be used by framework implementors to create their own
session implementations. It provides a reusable API which focuses strictly
on providing a dictionary-like object that properly handles renewals,
timeouts, and conformance with the ISession API.
See https://github.com/Pylons/pyramid/pull/1142

We no longer eagerly clear request.exception and request.exc_info in
the exception view tween. This makes it possible to inspect exception
information within a finished callback. See
https://github.com/Pylons/pyramid/issues/1223.

Modified the current_route_url() method. The
method previously returned the URL without the query string by default, it
now does attach the query string unless it is overriden.

The route_url() and
route_path() APIs no longer quote / to
%2F when a replacement value contains a /. This was pointless, as
WSGI servers always unquote the slash anyway, and Pyramid never sees the
quoted value.

It is no longer possible to set a locale_name attribute of the request,
nor is it possible to set a localizer attribute of the request. These
are now "reified" properties that look up a locale name and localizer
respectively using the machinery described in Internationalization and Localization.

If you send an X-Vhm-Root header with a value that ends with any number
of slashes, the trailing slashes will be removed before the URL
is generated when you use resource_url()
or resource_path(). Previously the virtual
root path would not have trailing slashes stripped, which would influence URL
generation.

The pyramid.interfaces.IResourceURL interface has now grown two new
attributes: virtual_path_tuple and physical_path_tuple. These should
be the tuple form of the resource's path (physical and virtual).

Removed the request.response_* varying attributes (such
as``request.response_headers``) . These attributes had been deprecated
since Pyramid 1.1, and as per the deprecation policy, have now been removed.

request.response will no longer be mutated when using the
pyramid.renderers.render() API. Almost all renderers mutate the
request.response response object (for example, the JSON renderer sets
request.response.content_type to application/json), but this is
only necessary when the renderer is generating a response; it was a bug
when it was done as a side effect of calling
pyramid.renderers.render().

Removed the bfg2pyramid fixer script.

The pyramid.events.NewResponse event is now sent after response
callbacks are executed. It previously executed before response callbacks
were executed. Rationale: it's more useful to be able to inspect the response
after response callbacks have done their jobs instead of before.

Removed the class named pyramid.view.static that had been deprecated
since Pyramid 1.1. Instead use pyramid.static.static_view with the
use_subpath=True argument.

Removed the ability to influence and query a pyramid.request.Request
object as if it were a dictionary. Previously it was possible to use methods
like __getitem__, get, items, and other dictlike methods to
access values in the WSGI environment. This behavior had been deprecated
since Pyramid 1.1. Use methods of request.environ (a real dictionary)
instead.

Removed ancient backwards compatibily hack in
pyramid.traversal.DefaultRootFactory which populated the __dict__ of
the factory with the matchdict values for compatibility with BFG 0.9.

The renderer_globals_factory argument to the
pyramid.config.Configurator constructor and the
coresponding argument to setup_registry()
has been removed. The set_renderer_globals_factory method of
Configurator has also been removed. The (internal)
pyramid.interfaces.IRendererGlobals interface was also removed. These
arguments, methods and interfaces had been deprecated since 1.1. Use a
BeforeRender event subscriber as documented in the "Hooks" chapter of the
Pyramid narrative documentation instead of providing renderer globals values
to the configurator.

Returning a ("defname",dict) tuple from a view which has a Mako renderer
is now deprecated. Instead you should use the renderer spelling
foo#defname.mak in the view configuration definition and return a dict
only.

Deprecate the pyramid.interfaces.ITemplateRenderer interface. It was
ill-defined and became unused when Mako and Chameleon template bindings were
split into their own packages.

The pyramid.session.UnencryptedCookieSessionFactoryConfig API has been
deprecated and is superseded by the
pyramid.session.SignedCookieSessionFactory. Note that while the cookies
generated by the UnencryptedCookieSessionFactoryConfig
are compatible with cookies generated by old releases, cookies generated by
the SignedCookieSessionFactory are not. See
https://github.com/Pylons/pyramid/pull/1142