- Added API docs for ``pyramid.httpexceptions.abort`` and

  ``pyramid.httpexceptions.redirect``.

- Added "HTTP Exceptions" section to Views narrative chapter including a
  description of ``pyramid.httpexceptions.abort``; adjusted redirect section
  to note ``pyramid.httpexceptions.redirect``.

- A default exception view for the context ``webob.exc.HTTPException`` (aka
  ``pyramid.httpexceptions.HTTPException``) is now registered by default.
  This means that an instance of any exception class imported from
  ``pyramid.httpexceptions`` (such as ``HTTPFound``) can now be raised from
  within view code; when raised, this exception view will render the
  exception to a response.

- New functions named ``pyramid.httpexceptions.abort`` and
  ``pyramid.httpexceptions.redirect`` perform the equivalent of their Pylons
  brethren when an HTTP exception handler is registered.  These functions
  take advantage of the newly registered exception view for
  ``webob.exc.HTTPException``.

- The Configurator now accepts an additional keyword argument named
  ``httpexception_view``.  By default, this argument is populated with a
  default exception view function that will be used when an HTTP exception is
  raised.  When ``None`` is passed for this value, an exception view for HTTP
  exceptions will not be registered.  Passing ``None`` returns the behavior
  of raising an HTTP exception to that of Pyramid 1.0 (the exception will
  propagate to middleware and to the WSGI server).

1 files changed, 179 insertions, 70 deletions

diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 5c9bd91af..465cd3c0d 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -51,14 +51,14 @@ the request object contains everything your application needs to know
 about the specific HTTP request being made.
 
 A view callable's ultimate responsibility is to create a :mod:`Pyramid`
-:term:`Response` object. This can be done by creating the response
-object in the view callable code and returning it directly, as we will
-be doing in this chapter. However, if a view callable does not return a
-response itself, it can be configured to use a :term:`renderer` that
-converts its return value into a :term:`Response` object. Using
-renderers is the common way that templates are used with view callables
-to generate markup.  See the :ref:`renderers_chapter` chapter for
-details.
+:term:`Response` object. This can be done by creating the response object in
+the view callable code and returning it directly, as we will be doing in this
+chapter. However, if a view callable does not return a response itself, it
+can be configured to use a :term:`renderer` that converts its return value
+into a :term:`Response` object. Using renderers is the common way that
+templates are used with view callables to generate markup: see the
+:ref:`renderers_chapter` chapter for details.  In some cases, a response may
+also be generated by raising an exception within a view callable.
 
 .. index::
    single: view calling convention
@@ -234,8 +234,8 @@ You don't need to always use :class:`~pyramid.response.Response` to represent
 a response.  :app:`Pyramid` provides a range of different "exception" classes
 which can act as response objects too.  For example, an instance of the class
 :class:`pyramid.httpexceptions.HTTPFound` is also a valid response object
-(see :ref:`http_redirect`).  A view can actually return any object that has
-the following attributes.
+(see :ref:`http_exceptions` and ref:`http_redirect`).  A view can actually
+return any object that has the following attributes.
 
 status
   The HTTP status code (including the name) for the response as a string.
@@ -255,46 +255,6 @@ app_iter
 These attributes form the structure of the "Pyramid Response interface".
 
 .. index::
-   single: view http redirect
-   single: http redirect (from a view)
-
-.. _http_redirect:
-
-Using a View Callable to Do an HTTP Redirect
---------------------------------------------
-
-You can issue an HTTP redirect from within a view by returning a particular
-kind of response.
-
-.. code-block:: python
-   :linenos:
-
-   from pyramid.httpexceptions import HTTPFound
-
-   def myview(request):
-       return HTTPFound(location='http://example.com')
-
-All exception types from the :mod:`pyramid.httpexceptions` module implement
-the :term:`Response` interface; any can be returned as the response from a
-view.  See :mod:`pyramid.httpexceptions` for the documentation for the
-``HTTPFound`` exception; it also includes other response types that imply
-other HTTP response codes, such as ``HTTPUnauthorized`` for ``401
-Unauthorized``.
-
-.. note::
-
-   Although exception types from the :mod:`pyramid.httpexceptions` module are
-   in fact bona fide Python :class:`Exception` types, the :app:`Pyramid` view
-   machinery expects them to be *returned* by a view callable rather than
-   *raised*.
-
-   It is possible, however, in Python 2.5 and above, to configure an
-   *exception view* to catch these exceptions, and return an appropriate
-   :class:`~pyramid.response.Response`. The simplest such view could just
-   catch and return the original exception. See :ref:`exception_views` for
-   more details.
-
-.. index::
    single: view exceptions
 
 .. _special_exceptions_in_callables:
@@ -304,13 +264,21 @@ Using Special Exceptions In View Callables
 
 Usually when a Python exception is raised within a view callable,
 :app:`Pyramid` allows the exception to propagate all the way out to the
-:term:`WSGI` server which invoked the application.
+:term:`WSGI` server which invoked the application.  It is usually caught and
+logged there.
 
-However, for convenience, two special exceptions exist which are always
-handled by :app:`Pyramid` itself.  These are
-:exc:`pyramid.exceptions.NotFound` and :exc:`pyramid.exceptions.Forbidden`.
-Both are exception classes which accept a single positional constructor
-argument: a ``message``.
+However, for convenience, a special set of exceptions exists.  When one of
+these exceptions is raised within a view callable, it will always cause
+:app:`Pyramid` to generate a response.  Two categories of special exceptions
+exist: internal exceptions and HTTP exceptions.
+
+Internal Exceptions
+~~~~~~~~~~~~~~~~~~~
+
+:exc:`pyramid.exceptions.NotFound` and :exc:`pyramid.exceptions.Forbidden`
+are exceptions often raised by Pyramid itself when it (respectively) cannot
+find a view to service a request or when authorization was forbidden by a
+security policy.  However, they can also be raised by application developers.
 
 If :exc:`~pyramid.exceptions.NotFound` is raised within view code, the result
 of the :term:`Not Found View` will be returned to the user agent which
@@ -320,22 +288,100 @@ If :exc:`~pyramid.exceptions.Forbidden` is raised within view code, the result
 of the :term:`Forbidden View` will be returned to the user agent which
 performed the request.
 
-In all cases, the message provided to the exception constructor is made
-available to the view which :app:`Pyramid` invokes as
+Both are exception classes which accept a single positional constructor
+argument: a ``message``.  In all cases, the message provided to the exception
+constructor is made available to the view which :app:`Pyramid` invokes as
 ``request.exception.args[0]``.
 
+An example:
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.exceptions import NotFound
+
+    def aview(request):
+        raise NotFound('not found!')
+
+Internal exceptions may not be *returned* in order to generate a response,
+they must always be *raised*.
+
+.. index::
+   single: HTTP exceptions
+
+.. _http_exceptions:
+
+HTTP Exceptions
+~~~~~~~~~~~~~~~
+
+All exception classes documented in the :mod:`pyramid.httpexceptions` module
+implement the :term:`Response` interface; an instance of any of these classes
+can be returned or raised from within a view.  The instance will be used as
+as the view's response.
+
+For example, the :class:`pyramid.httpexceptions.HTTPUnauthorized` exception
+can be raised.  This will cause a response to be generated with a ``401
+Unauthorized`` status:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.httpexceptions import HTTPUnauthorized
+
+   def aview(request):
+       raise HTTPUnauthorized()
+
+A shortcut for importing and raising an HTTP exception is the
+:func:`pyramid.httpexceptions.abort` function.  This function accepts an HTTP
+status code and raises the corresponding HTTP exception.  For example, to
+raise HTTPUnauthorized, instead of the above, you could do:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.httpexceptions import abort
+
+   def aview(request):
+       abort(401)
+
+This is the case because ``401`` is the HTTP status code for "HTTP
+Unauthorized".  Therefore, ``abort(401)`` is functionally equivalent to
+``raise HTTPUnauthorized()``.  Other exceptions in
+:mod:`pyramid.httpexceptions` can be raised via
+:func:`pyramid.httpexceptions.abort` as well, as long as the status code
+associated with the exception is provided to the function.
+
+An HTTP exception, instead of being raised, can alternately be *returned*
+(HTTP exceptions are also valid response objects):
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.httpexceptions import HTTPUnauthorized
+
+   def aview(request):
+       return HTTPUnauthorized()
+
+Note that :class:`pyramid.exceptions.NotFound` is *not* the same as
+:class:`pyramid.httpexceptions.HTTPNotFound`.  If the latter is raised, the
+:term:`Not Found view` will *not* be called automatically.  Likewise,
+:class:`pyramid.exceptions.Foribdden` is not the same exception as
+:class:`pyramid.httpexceptions.HTTPForbidden`.  If the latter is raised, the
+:term:`Forbidden view` will not be called automatically.
+
 .. index::
    single: exception views
 
 .. _exception_views:
 
-Exception Views
----------------
+Custom Exception Views
+----------------------
 
-The machinery which allows the special :exc:`~pyramid.exceptions.NotFound` and
-:exc:`~pyramid.exceptions.Forbidden` exceptions to be caught by specialized
-views as described in :ref:`special_exceptions_in_callables` can also be used
-by application developers to convert arbitrary exceptions to responses.
+The machinery which allows :exc:`~pyramid.exceptions.NotFound`,
+:exc:`~pyramid.exceptions.Forbidden` and HTTP exceptions to be caught by
+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 with :app:`Pyramid` view code, use the exception class or one of
@@ -359,6 +405,7 @@ raises a ``helloworld.exceptions.ValidationFailure`` exception:
 .. code-block:: python
    :linenos:
 
+   from pyramid.view import view_config
    from helloworld.exceptions import ValidationFailure
 
    @view_config(context=ValidationFailure)
@@ -380,12 +427,13 @@ exception view registration:
    :linenos:
 
    from pyramid.view import view_config
-   from pyramid.exceptions import NotFound
-   from pyramid.httpexceptions import HTTPNotFound
+   from helloworld.exceptions import ValidationFailure
 
-   @view_config(context=NotFound, route_name='home')
-   def notfound_view(request):
-       return HTTPNotFound()
+   @view_config(context=ValidationFailure, route_name='home')
+   def failed_validation(exc, request):
+       response =  Response('Failed validation: %s' % exc.msg)
+       response.status_int = 500
+       return response
 
 The above exception view names the ``route_name`` of ``home``, meaning that
 it will only be called when the route matched has a name of ``home``.  You
@@ -407,7 +455,68 @@ exception views which have a name will be ignored.
   can use an exception as ``context`` for a normal view.
 
 Exception views can be configured with any view registration mechanism:
-``@view_config`` decorator, ZCML, or imperative ``add_view`` styles.
+``@view_config`` decorator or imperative ``add_view`` styles.
+
+.. index::
+   single: view http redirect
+   single: http redirect (from a view)
+
+.. _http_redirect:
+
+Using a View Callable to Do an HTTP Redirect
+--------------------------------------------
+
+Two methods exist to redirect to another URL from within a view callable: a
+short form and a long form.  The short form should be preferred when
+possible.
+
+Short Form
+~~~~~~~~~~
+
+You can issue an HTTP redirect from within a view callable by using the
+:func:`pyramid.httpexceptions.redirect` function.  This function raises an
+:class:`pyramid.httpexceptions.HTTPFound` exception (a "302"), which is
+caught by an exception handler and turned into a response.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.httpexceptions import redirect
+
+   def myview(request):
+       redirect('http://example.com')
+
+Long Form
+~~~~~~~~~
+
+You can issue an HTTP redirect from within a view "by hand" instead of
+relying on the :func:`pyramid.httpexceptions.redirect` function to do it for
+you.
+
+To do so, you can *return* a :class:`pyramid.httpexceptions.HTTPFound`
+instance.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.httpexceptions import HTTPFound
+
+   def myview(request):
+       return HTTPFound(location='http://example.com')
+
+Or, alternately, you can *raise* an HTTPFound exception instead of returning
+one.
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.httpexceptions import HTTPFound
+
+   def myview(request):
+       raise HTTPFound(location='http://example.com')
+
+The above form of generating a response by raising HTTPFound is completely
+equivalent to ``redirect('http://example.com')``.
 
 .. index::
    single: unicode, views, and forms