Merge upstream master

1 files changed, 57 insertions, 7 deletions

diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst
index 02ae14aa5..7c847de50 100644
--- a/docs/narr/subrequest.rst
+++ b/docs/narr/subrequest.rst
@@ -17,7 +17,7 @@ application.
 Here's an example application which uses a subrequest:
 
 .. code-block:: python
-  :linenos:
+   :linenos:
 
    from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
@@ -61,8 +61,8 @@ adapter when found and invoked via
 object:
 
 .. code-block:: python
-  :linenos:
-  :emphasize-lines: 11
+   :linenos:
+   :emphasize-lines: 11
 
    from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
@@ -106,8 +106,8 @@ exception, the exception will be raised to the caller of
 :term:`exception view` configured:
 
 .. code-block:: python
-  :linenos:
-  :emphasize-lines: 11-16
+   :linenos:
+   :emphasize-lines: 11-16
 
    from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
@@ -175,8 +175,8 @@ We can cause the subrequest to be run through the tween stack by passing
 :meth:`~pyramid.request.Request.invoke_subrequest`, like this:
 
 .. code-block:: python
-  :linenos:
-  :emphasize-lines: 7
+   :linenos:
+   :emphasize-lines: 7
 
    from wsgiref.simple_server import make_server
    from pyramid.config import Configurator
@@ -279,3 +279,53 @@ within a tween, because tweens already, by definition, have access to a
 function that will cause a subrequest (they are passed a ``handle`` function).
 It's fine to invoke :meth:`~pyramid.request.Request.invoke_subrequest` from
 within an event handler, however.
+
+
+.. index::
+   pair: subrequest; exception view
+
+Invoking an Exception View
+--------------------------
+
+.. versionadded:: 1.7
+
+:app:`Pyramid` apps may define :term:`exception views <exception view>` which
+can handle any raised exceptions that escape from your code while processing
+a request. By default an unhandled exception will be caught by the ``EXCVIEW``
+:term:`tween`, which will then lookup an exception view that can handle the
+exception type, generating an appropriate error response.
+
+In :app:`Pyramid` 1.7 the :meth:`pyramid.request.Request.invoke_exception_view`
+was introduced, allowing a user to invoke an exception view while manually
+handling an exception. This can be useful in a few different circumstances:
+
+- Manually handling an exception losing the current call stack or flow.
+
+- Handling exceptions outside of the context of the ``EXCVIEW`` tween. The
+  tween only covers certain parts of the request processing pipeline (See
+  :ref:`router_chapter`). There are also some corner cases where an exception
+  can be raised that will still bubble up to middleware, and possibly to the
+  web server in which case a generic ``500 Internal Server Error`` will be
+  returned to the client.
+
+Below is an example usage of
+:meth:`pyramid.request.Request.invoke_exception_view`:
+
+.. code-block:: python
+   :linenos:
+
+   def foo(request):
+       try:
+           some_func_that_errors()
+           return response
+       except Exception:
+           response = request.invoke_exception_view()
+           if response is not None:
+               return response
+           else:
+               # there is no exception view for this exception, simply
+               # re-raise and let someone else handle it
+               raise
+
+Please note that in most cases you do not need to write code like this, and you
+may rely on the ``EXCVIEW`` tween to handle this for you.