Merge branch 'master' of github.com:Pylons/pyramid

7 files changed, 106 insertions, 18 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index 6d0a2a5a3..b22b31bf9 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -1654,7 +1654,8 @@ the user-defined :term:`view callable`:
   Enforce the ``permission`` defined on the view. This element is a no-op if no
   permission is defined. Note there will always be a permission defined if a
   default permission was assigned via
-  :meth:`pyramid.config.Configurator.set_default_permission`.
+  :meth:`pyramid.config.Configurator.set_default_permission` unless the
+  view is an :term:`exception view`.
 
   This element will also output useful debugging information when
   ``pyramid.debug_authorization`` is enabled.
@@ -1664,7 +1665,8 @@ the user-defined :term:`view callable`:
   Used to check the CSRF token provided in the request. This element is a
   no-op if ``require_csrf`` view option is not ``True``. Note there will
   always be a ``require_csrf`` option if a default value was assigned via
-  :meth:`pyramid.config.Configurator.set_default_csrf_options`.
+  :meth:`pyramid.config.Configurator.set_default_csrf_options` unless
+  the view is an :term:`exception view`.
 
 ``owrapped_view``
 
@@ -1710,6 +1712,8 @@ around monitoring and security. In order to register a custom :term:`view
 deriver`, you should create a callable that conforms to the
 :class:`pyramid.interfaces.IViewDeriver` interface, and then register it with
 your application using :meth:`pyramid.config.Configurator.add_view_deriver`.
+The callable should accept the ``view`` to be wrapped and the ``info`` object
+which is an instance of :class:`pyramid.interfaces.IViewDeriverInfo`.
 For example, below is a callable that can provide timing information for the
 view pipeline:
 
@@ -1760,6 +1764,21 @@ View derivers are unique in that they have access to most of the options
 passed to :meth:`pyramid.config.Configurator.add_view` in order to decide what
 to do, and they have a chance to affect every view in the application.
 
+.. _exception_view_derivers:
+
+Exception Views and View Derivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A :term:`view deriver` has the opportunity to wrap any view, including
+an :term:`exception view`. In general this is fine, but certain view derivers
+may wish to avoid doing certain things when handling exceptions. For example,
+the ``csrf_view`` and ``secured_view`` built-in view derivers will not perform
+security checks on exception views unless explicitly told to do so.
+
+You can check for ``info.exception_only`` on the
+:class:`pyramid.interfaces.IViewDeriverInfo` object when wrapping the view
+to determine whether you are wrapping an exception view or a normal view.
+
 Ordering View Derivers
 ~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 677c27e4a..570cb2285 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -191,6 +191,29 @@ After installing Python as described previously in :ref:`for-mac-os-x-users` or
 
       $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
+.. index::
+   single: $VENV/bin/pip vs. source bin/activate
+
+.. _venv-bin-pip-vs-source-bin-activate:
+
+.. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then
+   ``pip``?
+
+   ``$VENV/bin/pip`` clearly specifies that ``pip`` is run from within the
+   virtual environment and not at the system level.
+
+   ``activate`` drops turds into the user's shell environment, leaving them
+   vulnerable to executing commands in the wrong context. ``deactivate`` might
+   not correctly restore previous shell environment variables.
+
+   Although using ``source bin/activate``, then ``pip``, requires fewer key
+   strokes to issue commands once invoked, there are other things to consider.
+   Michael F. Lamb (datagrok) presents a summary in `Virtualenv's bin/activate
+   is Doing It Wrong <https://gist.github.com/datagrok/2199506>`_.
+
+   Ultimately we prefer to keep things clear and simple, so we use
+   ``$VENV/bin/pip``.
+
 
 .. index::
    single: installing on Windows
@@ -227,6 +250,9 @@ After installing Python as described previously in
 
       c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
+.. note:: See the note above for :ref:`Why use $VENV/bin/pip instead of source
+   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.
+
 
 What Gets Installed
 -------------------
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index a1319e45f..5b24201a9 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -157,6 +157,12 @@ The following session factories exist at the time of this writing.
 ======================= ======= =============================
 Session Factory         Backend   Description
 ======================= ======= =============================
+pyramid_nacl_session_   PyNaCl_ Defines an encrypting,
+                                pickle-based cookie
+                                serializer, using PyNaCl to
+                                generate the symmetric
+                                encryption for the cookie
+                                state.
 pyramid_redis_sessions_ Redis_  Server-side session library
                                 for Pyramid, using Redis for
                                 storage.
@@ -165,6 +171,9 @@ pyramid_beaker_         Beaker_ Session factory for Pyramid
                                 sessioning system.
 ======================= ======= =============================
 
+.. _pyramid_nacl_session: https://pypi.python.org/pypi/pyramid_nacl_session
+.. _PyNaCl: https://pynacl.readthedocs.io/en/latest/secret/
+
 .. _pyramid_redis_sessions: https://pypi.python.org/pypi/pyramid_redis_sessions
 .. _Redis: http://redis.io/
 
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index cd5b8feb0..7cb8e0306 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -34,7 +34,7 @@ determine the set of circumstances which must be true for the view callable to
 be invoked.
 
 A view configuration statement is made about information present in the
-:term:`context` resource and the :term:`request`.
+:term:`context` resource (or exception) and the :term:`request`.
 
 View configuration is performed in one of two ways:
 
@@ -306,9 +306,26 @@ configured view.
   represented class or if the :term:`context` resource provides the represented
   interface; it is otherwise false.
 
+  It is possible to pass an exception class as the context if your context may
+  subclass an exception. In this case *two* views will be registered. One
+  will match normal incoming requests, and the other will match as an
+  :term:`exception view` which only occurs when an exception is raised during
+  the normal request processing pipeline.
+
   If ``context`` is not supplied, the value ``None``, which matches any
   resource, is used.
 
+``exception_only``
+
+  When this value is ``True``, the ``context`` argument must be a subclass of
+  ``Exception``. This flag indicates that only an :term:`exception view` should
+  be created, and that this view should not match if the traversal
+  :term:`context` matches the ``context`` argument. If the ``context`` is a
+  subclass of ``Exception`` and this value is ``False`` (the default), then a
+  view will be registered to match the traversal :term:`context` as well.
+
+  .. versionadded:: 1.8
+
 ``route_name``
   If ``route_name`` is supplied, the view callable will be invoked only when
   the named route has matched.
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 770d27919..ab139ea19 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -262,10 +262,16 @@ specialized views as described in :ref:`special_exceptions_in_callables` can
 also be used by application developers to convert arbitrary exceptions to
 responses.
 
-To register a view that should be called whenever a particular exception is
-raised from within :app:`Pyramid` view code, use the exception class (or one of
-its superclasses) as the :term:`context` of a view configuration which points
-at a view callable for which you'd like to generate a response.
+To register an :term:`exception view` that should be called whenever a
+particular exception is raised from within :app:`Pyramid` view code, use
+:meth:`pyramid.config.Configurator.add_exception_view` to register a view
+configuration which matches the exception (or a subclass of the exception) and
+points at a view callable for which you'd like to generate a response. The
+exception will be passed as the ``context`` argument to any
+:term:`view predicate` registered with the view, as well as to the view itself.
+For convenience a new decorator exists,
+:class:`pyramid.views.exception_view_config`, which may be used to easily
+register exception views.
 
 For example, given the following exception class in a module named
 ``helloworld.exceptions``:
@@ -277,17 +283,16 @@ For example, given the following exception class in a module named
        def __init__(self, msg):
            self.msg = msg
 
-
 You can wire a view callable to be called whenever any of your *other* code
 raises a ``helloworld.exceptions.ValidationFailure`` exception:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.view import view_config
+   from pyramid.view import exception_view_config
    from helloworld.exceptions import ValidationFailure
 
-   @view_config(context=ValidationFailure)
+   @exception_view_config(ValidationFailure)
    def failed_validation(exc, request):
        response =  Response('Failed validation: %s' % exc.msg)
        response.status_int = 500
@@ -308,7 +313,7 @@ view registration:
    from pyramid.view import view_config
    from helloworld.exceptions import ValidationFailure
 
-   @view_config(context=ValidationFailure, route_name='home')
+   @exception_view_config(ValidationFailure, route_name='home')
    def failed_validation(exc, request):
        response =  Response('Failed validation: %s' % exc.msg)
        response.status_int = 500
@@ -327,14 +332,21 @@ which have a name will be ignored.
 
 .. note::
 
-  Normal (i.e., non-exception) views registered against a context resource type
-  which inherits from :exc:`Exception` will work normally.  When an exception
-  view configuration is processed, *two* views are registered.  One as a
-  "normal" view, the other as an "exception" view.  This means that you can use
-  an exception as ``context`` for a normal view.
+  In most cases, you should register an :term:`exception view` by using
+  :meth:`pyramid.config.Configurator.add_exception_view`. However, it is
+  possible to register "normal" (i.e., non-exception) views against a context
+  resource type which inherits from :exc:`Exception` (i.e.,
+  ``config.add_view(context=Exception)``).  When the view configuration is
+  processed, *two* views are registered.  One as a "normal" view, the other
+  as an :term:`exception view`.  This means that you can use an exception as
+  ``context`` for a normal view.
+
+  The view derivers that wrap these two views may behave differently.
+  See :ref:`exception_view_derivers` for more information about this.
 
 Exception views can be configured with any view registration mechanism:
-``@view_config`` decorator or imperative ``add_view`` styles.
+``@exception_view_config`` decorator or imperative ``add_exception_view``
+styles.
 
 .. note::
 
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index b2dec77e9..39b4cafb3 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -59,7 +59,9 @@ show only UNIX commands.
 
 .. seealso:: See also:
     :ref:`Quick Tutorial section on Requirements <qtut_requirements>`,
-    :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`, and
+    :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`,
+    :ref:`Why use $VENV/bin/pip instead of source bin/activate, then pip
+    <venv-bin-pip-vs-source-bin-activate>`, and
     :ref:`Installing Pyramid on a Windows System <installing_windows>`.
 
 
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 1de9a8acf..afa8ed104 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -179,6 +179,9 @@ time of its release.
     # Windows
     c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
 
+.. seealso:: See also :ref:`Why use $VENV/bin/pip instead of source
+   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.
+
 
 .. _install-pyramid: