Pyramid

===================

Features
--------

- Add a ``_depth`` and ``_category`` arguments to all of the venusian
decorators. The ``_category`` argument can be used to affect which actions
are registered when performing a ``config.scan(..., category=...)`` with a
specific category. The ``_depth`` argument should be used when wrapping
the decorator in your own. This change affects ``pyramid.view.view_config``,
``pyramid.view.exception_view_config``,
``pyramid.view.forbidden_view_config``, ``pyramid.view.notfound_view_config``,
``pyramid.events.subscriber`` and ``pyramid.response.response_adapter``
decorators. See https://github.com/Pylons/pyramid/pull/3105 and
https://github.com/Pylons/pyramid/pull/3122

- Fix the ``pyramid.request.Request`` class name after using
``set_property`` or ``config.add_request_method`` such that the
``str(request.__class__)`` would appear as ``pyramid.request.Request``
instead of ``pyramid.util.Request``.
See https://github.com/Pylons/pyramid/pull/3129

- In ``cherrypy_server_runner``, prefer imports from the ``cheroot`` package
over the legacy imports from `cherrypy.wsgiserver`.
See https://github.com/Pylons/pyramid/pull/3235

- Add a context manager ``route_prefix_context`` to the
``pyramid.config.Configurator`` to allow for convenient setting of the
route_prefix for ``include`` and ``add_route`` calls inside the context.
See https://github.com/Pylons/pyramid/pull/3279

- Modify the builtin session implementations to support ``SameSite`` options
on cookies and set the default to ``'Lax'``. This affects
``pyramid.session.BaseCookieSessionFactory``,
``pyramid.session.SignedCookieSessionFactory``, and
``pyramid.session.UnencryptedCookieSessionFactoryConfig``.
See https://github.com/Pylons/pyramid/pull/3300

- Modify ``pyramid.authentication.AuthTktAuthenticationPolicy`` and
``pyramid.csrf.CookieCSRFStoragePolicy`` to support the ``SameSite`` option
on cookies and set the default to ``'Lax'``.
See https://github.com/Pylons/pyramid/pull/3319

- Added new ``pyramid.httpexceptions.HTTPPermanentRedirect``
exception/response object for a HTTP 308 redirect.
See https://github.com/Pylons/pyramid/pull/3302

- Within ``pshell``, allow the user-defined ``setup`` function to be a
generator, in which case it may wrap the command's lifecycle.
See https://github.com/Pylons/pyramid/pull/3318

- Within ``pshell``, variables defined by the ``[pshell]`` settings are
available within the user-defined ``setup`` function.
See https://github.com/Pylons/pyramid/pull/3318

- Add support for Python 3.7. Add testing on Python 3.8 with allowed failures.
See https://github.com/Pylons/pyramid/pull/3333

- Added the ``pyramid.config.Configurator.add_accept_view_order`` directive,
allowing users to specify media type preferences in ambiguous situations
such as when several views match. A default ordering is defined for media
types that prefers human-readable html/text responses over JSON.
See https://github.com/Pylons/pyramid/pull/3326

- Support a list of media types in the ``accept`` predicate used in
``pyramid.config.Configurator.add_route``.
See https://github.com/Pylons/pyramid/pull/3326

- Added ``pyramid.session.JSONSerializer``. See "Upcoming Changes to ISession
in Pyramid 2.0" in the "Sessions" chapter of the documentation for more
information about this feature.
See https://github.com/Pylons/pyramid/pull/3353

- Add a ``registry`` argument to ``pyramid.renderers.get_renderer``
to allow users to avoid threadlocals during renderer lookup.
See https://github.com/Pylons/pyramid/pull/3358

- Pyramid's test suite is no longer distributed with the universal wheel.
See https://github.com/Pylons/pyramid/pull/3387

- All Python code is now formatted automatically using ``black``.
See https://github.com/Pylons/pyramid/pull/3388

Bug Fixes
---------

- Set appropriate ``code`` and ``title`` attributes on the ``HTTPClientError``
and ``HTTPServerError`` exception classes. This prevents inadvertently
returning a 520 error code.
See https://github.com/Pylons/pyramid/pull/3280

- Replace ``webob.acceptparse.MIMEAccept`` from WebOb with
``webob.acceptparse.create_accept_header`` in the HTTP exception handling
code. The old ``MIMEAccept`` has been deprecated. The new methods follow the
RFC's more closely. See https://github.com/Pylons/pyramid/pull/3251

- Catch extra errors like ``AttributeError`` when unpickling "trusted"
session cookies with bad pickle data in them. This would occur when sharing
a secret between projects that shouldn't actually share session cookies,
like when reusing secrets between projects in development.
See https://github.com/Pylons/pyramid/pull/3325

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

- The ``pyramid.interfaces.ISession`` interface will move to require
JSON-serializable objects in Pyramid 2.0. See
"Upcoming Changes to ISession in Pyramid 2.0" in the "Sessions" chapter
of the documentation for more information about this change.
See https://github.com/Pylons/pyramid/pull/3353

- The ``pyramid.session.signed_serialize`` and
``pyramid.session.signed_deserialize`` functions will be removed in Pyramid
2.0, along with the removal of
``pyramid.session.UnencryptedCookieSessionFactoryConfig`` which was
deprecated in Pyramid 1.5. Please switch to using the
``SignedCookieSessionFactory``, copying the code, or another session
implementation if you're still using these features.
See https://github.com/Pylons/pyramid/pull/3353

- Media ranges are deprecated in the ``accept`` argument of
``pyramid.config.Configurator.add_route``. Use a list of explicit
media types to ``add_route`` to support multiple types.

- Media ranges are deprecated in the ``accept`` argument of
``pyramid.config.Configurator.add_view``. There is no replacement for
ranges to ``add_view``, but after much discussion the workflow is
fundamentally ambiguous in the face of various client-supplied values for
the ``Accept`` header.
See https://github.com/Pylons/pyramid/pull/3326

Backward Incompatibilities
--------------------------

- On Python 3.4+ the ``repoze.lru`` dependency is dropped. If you were using
this package directly in your apps you should make sure that you are
depending on it directly within your project.
See https://github.com/Pylons/pyramid/pull/3140

- Remove the ``permission`` argument from
``pyramid.config.Configurator.add_route``. This was an argument left over
from a feature removed in Pyramid 1.5 and has had no effect since then.
See https://github.com/Pylons/pyramid/pull/3299

- Modify the builtin session implementations to set ``SameSite='Lax'`` on
cookies. This affects ``pyramid.session.BaseCookieSessionFactory``,
``pyramid.session.SignedCookieSessionFactory``, and
``pyramid.session.UnencryptedCookieSessionFactoryConfig``.
See https://github.com/Pylons/pyramid/pull/3300

- Variables defined in the ``[pshell]`` section of the settings will no
longer override those set by the ``setup`` function.
See https://github.com/Pylons/pyramid/pull/3318

- ``pyramid.config.Configurator.add_notfound_view`` uses default redirect
class exception ``pyramid.httpexceptions.HTTPTemporaryRedirect`` instead
of previous ``pyramid.httpexceptions.HTTPFound``.
See https://github.com/Pylons/pyramid/pull/3328

- Removed ``pyramid.config.Configurator.set_request_property`` which had been
deprecated since Pyramid 1.5. Instead use
``pyramid.config.Configurator.add_request_method`` with ``reify=True`` or
``property=True``.
See https://github.com/Pylons/pyramid/pull/3368

- Removed the ``principal`` keyword argument from
``pyramid.security.remember`` which had been deprecated since Pyramid 1.6
and replaced by the ``userid`` argument.
See https://github.com/Pylons/pyramid/pull/3369

- Removed the ``pyramid.tests`` subpackage that used to contain the Pyramid
test suite. These changes also changed the format of the repository to move
the code into a ``src`` folder.
See https://github.com/Pylons/pyramid/pull/3387

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

- Ad support for Read The Docs Ethical Ads.
See https://github.com/Pylons/pyramid/pull/3360 and
https://docs.readthedocs.io/en/latest/advertising/ethical-advertising.html

- Add support for alembic to the pyramid-cookiecutter-alchemy cookiecutter
and update the wiki2 tutorial to explain how it works.
See https://github.com/Pylons/pyramid/pull/3307 and
https://github.com/Pylons/pyramid-cookiecutter-alchemy/pull/7

- Bump Sphinx to >= 1.7.4 in setup.py to support ``emphasize-lines`` in PDFs
and to pave the way for xelatex support. See
https://github.com/Pylons/pyramid/pull/3271,
https://github.com/Pylons/pyramid/issues/667, and
https://github.com/Pylons/pyramid/issues/2572

- Added extra tests to the quick tutorial.
See https://github.com/Pylons/pyramid/pull/3375

================

- No major changes from 1.9b1.

- Updated documentation links for ``docs.pylonsproject.org`` to use HTTPS.

==================

- Add an informative error message when unknown predicates are supplied. The
new message suggests alternatives based on the list of known predicates.
See https://github.com/Pylons/pyramid/pull/3054

- Added integrity attributes for JavaScripts in cookiecutters, scaffolds, and
resulting source files in tutorials.
See https://github.com/Pylons/pyramid/issues/2548

- Update RELEASING.txt for updating cookiecutters. Change cookiecutter URLs to
use shortcut.
See https://github.com/Pylons/pyramid/issues/3042

- Ensure the correct threadlocals are pushed during view execution when
invoked from ``request.invoke_exception_view``.
See https://github.com/Pylons/pyramid/pull/3060

- Fix a bug in which ``pyramid.security.ALL_PERMISSIONS`` failed to return
a valid iterator in its ``__iter__`` implementation.
See https://github.com/Pylons/pyramid/pull/3074

- Normalize the permission results to a proper class hierarchy.
``pyramid.security.ACLAllowed`` is now a subclass of
``pyramid.security.Allowed`` and ``pyramid.security.ACLDenied`` is now a
subclass of ``pyramid.security.Denied``.
See https://github.com/Pylons/pyramid/pull/3084

- Add a ``quote_via`` argument to ``pyramid.encode.urlencode`` to follow
the stdlib's version and enable custom quoting functions.
See https://github.com/Pylons/pyramid/pull/3088

- Support `_query=None` and `_anchor=None` in ``request.route_url`` as well
as ``query=None`` and ``anchor=None`` in ``request.resource_url``.
Previously this would cause an `?` and a ``, respectively, in the url
with nothing after it. Now the unnecessary parts are dropped from the
generated URL. See https://github.com/Pylons/pyramid/pull/3034

- Revamp the ``IRouter`` API used by ``IExecutionPolicy`` to force
pushing/popping the request threadlocals. The
``IRouter.make_request(environ)`` API has been replaced by
``IRouter.request_context(environ)`` which should be used as a context
manager. See https://github.com/Pylons/pyramid/pull/3086

==================

Backward Incompatibilities
--------------------------

- ``request.exception`` and ``request.exc_info`` will only be set if the
response was generated by the EXCVIEW tween. This is to avoid any confusion
where a response was generated elsewhere in the pipeline and not in
direct relation to the original exception. If anyone upstream wants to
catch and render responses for exceptions they should set
``request.exception`` and ``request.exc_info`` themselves to indicate
the exception that was squashed when generating the response.

Similar behavior occurs with ``request.invoke_exception_view`` in which
the exception properties are set to reflect the exception if a response
is successfully generated by the method.

This is a very minor incompatibility. Most tweens right now would give
priority to the raised exception and ignore ``request.exception``. This
change just improves and clarifies that bookkeeping by trying to be
more clear about the relationship between the response and its squashed
exception. See https://github.com/Pylons/pyramid/pull/3029 and
https://github.com/Pylons/pyramid/pull/3031

==================

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

================

- No major changes from 1.8b1.