1.9a1 (2017-05-01)
==================

Major Features
--------------

- The file format used by all ``p*`` command line scripts such as ``pserve``
  and ``pshell``, as well as the ``pyramid.paster.bootstrap`` function
  is now replaceable thanks to a new dependency on
  `plaster <http://docs.pylonsproject.org/projects/plaster/en/latest/>`_.

  For now, Pyramid is still shipping with integrated support for the
  PasteDeploy INI format by depending on the
  `plaster_pastedeploy <https://github.com/Pylons/plaster_pastedeploy`_
  binding library. This may change in the future.

  See https://github.com/Pylons/pyramid/pull/2985

- Added an execution policy hook to the request pipeline. An execution
  policy has the ability to control creation and execution of the request
  objects before they enter the rest of the pipeline. This means for a single
  request environ the policy may create more than one request object.

  The first library to use this feature is
  `pyramid_retry
  <http://docs.pylonsproject.org/projects/pyramid-retry/en/latest/>`_.

  See https://github.com/Pylons/pyramid/pull/2964

- CSRF support has been refactored out of sessions and into its own
  independent API in the ``pyramid.csrf`` module. It supports a pluggable
  ``pyramid.interfaces.ICSRFStoragePolicy`` which can be used to define your
  own mechanism for generating and validating CSRF tokens. By default,
  Pyramid continues to use the ``pyramid.csrf.LegacySessionCSRFStoragePolicy``
  that uses the ``request.session.get_csrf_token`` and
  ``request.session.new_csrf_token`` APIs under the hood to preserve
  compatibility. Two new policies are shipped as well,
  ``pyramid.csrf.SessionCSRFStoragePolicy`` and
  ``pyramid.csrf.CookieCSRFStoragePolicy`` which will store the CSRF tokens
  in the session and in a standalone cookie, respectively. The storage policy
  can be changed by using the new
  ``pyramid.config.Configurator.set_csrf_storage_policy`` config directive.

  CSRF tokens should be used via the new ``pyramid.csrf.get_csrf_token``,
  ``pyramid.csrf.new_csrf_token`` and ``pyramid.csrf.check_csrf_token`` APIs
  in order to continue working if the storage policy is changed. Also, the
  ``pyramid.csrf.get_csrf_token`` function is injected into templates to be
  used conveniently in UI code.

  See https://github.com/Pylons/pyramid/pull/2854 and
  https://github.com/Pylons/pyramid/pull/3019

Minor Features
--------------

- Support an ``open_url`` config setting in the ``pserve`` section of the
  config file. This url is used to open a web browser when ``pserve --browser``
  is invoked. When this setting is unavailable the ``pserve`` script will
  attempt to guess the port the server is using from the
  ``server:<server_name>`` section of the config file but there is no
  requirement that the server is being run in this format so it may fail.
  See https://github.com/Pylons/pyramid/pull/2984

- The ``pyramid.config.Configurator`` can now be used as a context manager
  which will automatically push/pop threadlocals (similar to
  ``config.begin()`` and ``config.end()``). It will also automatically perform
  a ``config.commit()`` and thus it is only recommended to be used at the
  top-level of your app. See https://github.com/Pylons/pyramid/pull/2874

- The threadlocals are now available inside any function invoked via
  ``config.include``. This means the only config-time code that cannot rely
  on threadlocals is code executed from non-actions inside the main. This
  can be alleviated by invoking ``config.begin()`` and ``config.end()``
  appropriately or using the new context manager feature of the configurator.
  See https://github.com/Pylons/pyramid/pull/2989

Bug Fixes
---------

- HTTPException's accepts a detail kwarg that may be used to pass additional
  details to the exception. You may now pass objects so long as they have a
  valid __str__ method. See https://github.com/Pylons/pyramid/pull/2951

- Fix a reference cycle causing memory leaks in which the registry
  would keep a ``Configurator`` instance alive even after the configurator
  was discarded. Another fix was also added for the ``global_registries``
  object in which the registry was stored in a closure preventing it from
  being deallocated. See https://github.com/Pylons/pyramid/pull/2967

- Fix a bug directly invoking ``pyramid.scripts.pserve.main`` with the
  ``--reload`` option in which ``sys.argv`` is always used in the subprocess
  instead of the supplied ``argv``.
  See https://github.com/Pylons/pyramid/pull/2962

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

- Pyramid currently depends on ``plaster_pastedeploy`` to simplify the
  transition to ``plaster`` by maintaining integrated support for INI files.
  This dependency on ``plaster_pastedeploy`` should be considered subject to
  Pyramid's deprecation policy and may be removed in the future.
  Applications should depend on the appropriate plaster binding to satisfy
  their needs.

- Retrieving CSRF token from the session has been deprecated in favor of
  equivalent methods in the ``pyramid.csrf`` module. The CSRF methods
  (``ISession.get_csrf_token`` and ``ISession.new_csrf_token``) are no longer
  required on the ``ISession`` interface except when using the default
  ``pyramid.csrf.LegacySessionCSRFStoragePolicy``.

  Also, ``pyramid.session.check_csrf_token`` is now located at
  ``pyramid.csrf.check_csrf_token``.

  See https://github.com/Pylons/pyramid/pull/2854 and
  https://github.com/Pylons/pyramid/pull/3019

Documentation Changes
---------------------

- Added the execution policy to the routing diagram in the Request Processing
  chapter. See https://github.com/Pylons/pyramid/pull/2993