What's New In Pyramid 1.5
=========================

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

Major Backwards Incompatibilities
---------------------------------

- 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: No such renderer factory .pt

  Or::

     ValueError: No such renderer factory .mako

  Or::

     ValueError: No such renderer factory .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.

  To re-add support for Chameleon and/or Mako template renderers into your
  existing projects, follow the below steps.

  If you depend on Mako templates:

  * 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.py develop``::

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

  * Within the portion of your application which instantiates a Pyramid 
    :class:`~pyramid.config.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.py develop``::

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

  * Within the portion of your application which instantiates a Pyramid 
    :class:`~pyramid.config.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::

        class ATest(unittest.TestCase):
            def setUp(self):
                self.config = pyramid.testing.setUp()
                self.config.include('pyramid_mako')

            def test_it(self):
                result = pyramid.renderers.render('mypkg:templates/home.mako', {})

  Or::

        class ATest(unittest.TestCase):
            def setUp(self):
                self.config = pyramid.testing.setUp()
                self.config.include('pyramid_chameleon')

            def test_it(self):
                result = pyramid.renderers.render('mypkg:templates/home.pt', {})

- 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.

Feature Additions
-----------------

The feature additions in Pyramid 1.5 follow.

- Python 3.4 compatibility.

- Add ``pdistreport`` script, which prints the Python version in use, the
  Pyramid version in use, and the version number and location of all Python
  distributions currently installed.

- Add the ability to invert the result of any view, route, or subscriber
  predicate value using the ``not_`` class.  For example:

  .. code-block:: python

     from pyramid.config import not_

     @view_config(route_name='myroute', request_method=not_('POST'))
     def myview(request): ...

  The above example will ensure that the view is called if the request method
  is not POST, at least if no other view is more specific.

  The :class:`pyramid.config.not_` class can be used against any value that is
  a predicate value passed in any of these contexts:

  - :meth:`pyramid.config.Configurator.add_view`

  - :meth:`pyramid.config.Configurator.add_route`

  - :meth:`pyramid.config.Configurator.add_subscriber`

  - :meth:`pyramid.view.view_config`

  - :meth:`pyramid.events.subscriber`

- 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:

  .. code-block:: python

     class IResource(Interface):

         ...

     @view_config(context=IResource)
     def get(context, request):

         ...

     @view_config(context=IResource, request_method='POST')
     def post(context, request):

         ...

     @view_config(context=IResource, request_method='DELETE')
     def delete(context, request):

         ...

     @implementer(IResource)
     class MyResource:

         ...

     @view_config(context=MyResource, request_method='POST')
     def override_post(context, request):

         ...

  Previously the override_post view registration would hide the get
  and delete views in the context of MyResource -- leading to a
  predicate mismatch error when trying to use GET or DELETE
  methods. Now the views are found and no predicate mismatch is
  raised.
  See https://github.com/Pylons/pyramid/pull/786 and
  https://github.com/Pylons/pyramid/pull/1004 and
  https://github.com/Pylons/pyramid/pull/1046

- ``scripts/prequest.py`` (aka the ``prequest`` console script): added support
  for submitting ``PUT`` and ``PATCH`` requests.  See
  https://github.com/Pylons/pyramid/pull/1033.  add support for submitting
  ``OPTIONS`` and ``PROPFIND`` requests, and allow users to specify basic
  authentication credentials in the request via a ``--login`` argument to the
  script.  See https://github.com/Pylons/pyramid/pull/1039.

- The :meth:`pyramid.config.Configurator.add_route` method now supports being
  called with an external URL as pattern. See
  https://github.com/Pylons/pyramid/issues/611 and the documentation section
  :ref:`external_route_narr`.

- :class:`pyramid.authorization.ACLAuthorizationPolicy` supports ``__acl__`` as
  a callable. This removes the ambiguity between the potential
  ``AttributeError`` that would be raised on the ``context`` when the property
  was not defined and the ``AttributeError`` that could be raised from any
  user-defined code within a dynamic property. It is recommended to define a
  dynamic ACL as a callable to avoid this ambiguity. See
  https://github.com/Pylons/pyramid/issues/735.

- Allow a protocol-relative URL (e.g. ``//example.com/images``) to be passed to
  :meth:`pyramid.config.Configurator.add_static_view`. This allows
  externally-hosted static URLs to be generated based on the current protocol.

- The :class:`pyramid.authentication.AuthTktAuthenticationPolicy` class has two
  new options to configure its domain usage:

  * ``parent_domain``: if set the authentication cookie is set on
    the parent domain. This is useful if you have multiple sites sharing the
    same domain.

  * ``domain``: if provided the cookie is always set for this domain, bypassing
    all usual logic.

  See https://github.com/Pylons/pyramid/pull/1028,
  https://github.com/Pylons/pyramid/pull/1072 and
  https://github.com/Pylons/pyramid/pull/1078.

- The :class:`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.

- Make it possible to use variable arguments via
  :func:`pyramid.paster.get_appsettings`. This also allowed the generated
  ``initialize_db`` script from the ``alchemy`` scaffold to grow support for
  options in the form ``a=1 b=2`` so you can fill in values in a parameterized
  ``.ini`` file, e.g.  ``initialize_myapp_db etc/development.ini a=1 b=2``.
  See https://github.com/Pylons/pyramid/pull/911

- 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 :meth:`~pyramid.request.Request.resource_url` and
  :meth:`~pyuramid.request.Request.resource_path`.  See
  :ref:`generating_hybrid_urls`.

- A new http exception superclass named
  :class:`~pyramid.httpexceptions.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
  :class:`~pyramid.httpexceptions.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

- Add ``localizer`` and ``locale_name`` properties (reified) to
  :class:`pyramid.request.Request`.  See
  https://github.com/Pylons/pyramid/issues/508.  Note that the
  :func:`pyramid.i18n.get_localizer` and :func:`pyramid.i18n.get_locale_name`
  functions now simply look up these properties on the request.

- 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``.

- The ``alchemy`` scaffold tests now provide better coverage.  See
  https://github.com/Pylons/pyramid/pull/1029

- Users can now provide dotted Python names to as the ``factory`` argument
  the Configurator methods named 
  :meth:`~pyramid.config.Configurator.add_view_predicate`, 
  :meth:`~pyramid.config.Configurator.add_route_predicate` and 
  :meth:`~pyramid.config.Configurator.add_subscriber_predicate`.  Instead of 
  passing the predicate factory directly, you can pass a dotted name which 
  refers to the factory.

- :func:`pyramid.path.package_name` no longer thows an exception when resolving 
  the package name for namespace packages that have no ``__file__`` attribute.

- An authorization API has been added as a method of the request:
  :meth:`pyramid.request.Request.has_permission`.  It is a method-based
  alternative to the :func:`pyramid.security.has_permission` API and works
  exactly the same.  The older API is now deprecated.

- Property API attributes have been added to the request for easier access to
  authentication data: :attr:`pyramid.request.Request.authenticated_userid`,
  :attr:`pyramid.request.Request.unauthenticated_userid`, and
  :attr:`pyramid.request.Request.effective_principals`.  These are analogues,
  respectively, of :func:`pyramid.security.authenticated_userid`,
  :func:`pyramid.security.unauthenticated_userid`, and
  :func:`pyramid.security.effective_principals`.  They operate exactly the
  same, except they are attributes of the request instead of functions
  accepting a request.  They are properties, so they cannot be assigned to.
  The older function-based APIs are now deprecated.

- Pyramid's console scripts (``pserve``, ``pviews``, etc) can now be run
  directly, allowing custom arguments to be sent to the python interpreter
  at runtime. For example::

      python -3 -m pyramid.scripts.pserve development.ini

- Added a specific subclass of :class:`pyramid.httpexceptions.HTTPBadRequest`
  named :class:`pyramid.exceptions.BadCSRFToken` which will now be raised in
  response to failures in the ``check_csrf_token`` view predicate.  See
  https://github.com/Pylons/pyramid/pull/1149

- 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.


Other Backwards Incompatibilities
---------------------------------

- Modified the :meth:`~pyramid.request.Reuqest.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 :meth:`~pyramid.request.Request.route_url` and
  :meth:`~pyramid.request.Request.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 :ref:`i18n_chapter`.

- 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 :meth:`~pyramid.request.Request.resource_url`
  or :meth:`~pyramid.request.Request.resource_path`.  Previously the virtual
  root path would not have trailing slashes stripped, which would influence URL
  generation.

- The :class:`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 
  :func:`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 
  :func:`pyramid.renderers.render`.

- Removed the ``bfg2pyramid`` fixer script.

- The :class:`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 :class:`pyramid.static.static_view` with the
  ``use_subpath=True`` argument.

- Removed the ``pyramid.view.is_response`` function that had been deprecated
  since Pyramid 1.1.  Use the :meth:`pyramid.request.Request.is_response`
  method instead.

- Removed the ability to pass the following arguments to
  :meth:`pyramid.config.Configurator.add_route`: ``view``, ``view_context``.
  ``view_for``, ``view_permission``, ``view_renderer``, and ``view_attr``.
  Using these arguments had been deprecated since Pyramid 1.1.  Instead of
  passing view-related arguments to ``add_route``, use a separate call to
  :meth:`pyramid.config.Configurator.add_view` to associate a view with a route
  using its ``route_name`` argument.  Note that this impacts the
  :meth:`pyramid.config.Configurator.add_static_view` function too, because
  it delegates to``add_route``.

- Removed the ability to influence and query a :class:`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 
  :class:`pyramid.config.Configurator` constructor and the 
  coresponding argument to :meth:`~pyramid.config.Configurator.setup_registry` 
  has been removed.  The ``set_renderer_globals_factory`` method of
  :class:`~pyramid.config.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.

- The key/values in the ``_query`` parameter of
  :meth:`pyramid.request.Request.route_url` and the ``query`` parameter of
  :meth:`pyramid.request.Request.resource_url` (and their variants), used to
  encode a value of ``None`` as the string ``'None'``, leaving the resulting
  query string to be ``a=b&key=None``. The value is now dropped in this
  situation, leaving a query string of ``a=b&key=``.  See
  https://github.com/Pylons/pyramid/issues/1119

Deprecations
------------

- 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.

- The :meth:`pyramid.config.Configurator.set_request_property` method now issues
  a deprecation warning when used.  It had been docs-deprecated in 1.4
  but did not issue a deprecation warning when used.

- :func:`pyramid.security.has_permission` is now deprecated in favor of using
  :meth:`pyramid.request.Request.has_permission`.

- The :func:`pyramid.security.authenticated_userid`,
  :func:`pyramid.security.unauthenticated_userid`, and
  :func:`pyramid.security.effective_principals` functions have been
  deprecated. Use :attr:`pyramid.request.Request.authenticated_userid`,
  :attr:`pyramid.request.Request.unauthenticated_userid` and
  :attr:`pyramid.request.Request.effective_principals` instead.

- 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

Documentation Enhancements
--------------------------

- A new documentation chapter named :ref:`quick_tour` was added.  It describes
  starting out with Pyramid from a high level.

- Added a :ref:`quick_tutorial` to go with the Quick Tour

- Many other enhancements.

Scaffolding Enhancements
------------------------

- All scaffolds have a new HTML + CSS theme.

- Updated docs and scaffolds to keep in step with new 2.0 release of
  ``Lingua``.  This included removing all ``setup.cfg`` files from scaffolds
  and documentation environments.

Dependency Changes
------------------

- Pyramid no longer depends upon ``Mako`` or ``Chameleon``.

- Pyramid now depends on WebOb>=1.3 (it uses ``webob.cookies.CookieProfile``
  from 1.3+).