Add Respond exception.

1 files changed, 26 insertions, 0 deletions

diff --git a/repoze/bfg/exceptions.py b/repoze/bfg/exceptions.py
index afd617a2c..bc05fa699 100644
--- a/repoze/bfg/exceptions.py
+++ b/repoze/bfg/exceptions.py
@@ -22,3 +22,29 @@ class NotFound(Exception):
     into the WSGI environment under the ``repoze.bfg.message`` key,
     for availability to the Not Found view."""
 
+class Respond(Exception):
+    """\
+    Raise this exception during view execution to return a response
+    immediately without proceeeding any further through the codepath.
+    Use of this exception is effectively a 'goto': its target is the
+    exception handler within the :mod:`repoze.bfg' router that catches
+    the exception and returns a response immediately.  Note that
+    because this exception is caught by the router, it will not
+    propagate to any WSGI middleware.  Note that this exception is
+    typically only used by the framework itself and by authentication
+    plugins to the framework.
+
+    The exception must be initialized which a single argument, which
+    is a :term:`response` object.
+
+    An example:
+
+    .. code-block:: python
+       :linenos:
+
+       from webob.exc import HTTPFound
+       from repoze.bfg.exceptions import Respond
+       response = HTTPFound(location='http://example.com')
+       raise Respond(response)
+    """
+