Merge remote-tracking branch 'refs/remotes/Pylons/master'

1 files changed, 526 insertions, 0 deletions

diff --git a/docs/whatsnew-1.5.rst b/docs/whatsnew-1.5.rst
new file mode 100644
index 000000000..a477ce5ec
--- /dev/null
+++ b/docs/whatsnew-1.5.rst
@@ -0,0 +1,526 @@
+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+).