- New API: ``pyramid.config.Configurator.add_forbidden_view``. This is a

  wrapper for ``pyramid.Config.configurator.add_view`` which does the right
  thing about permissions.  It should be preferred over calling ``add_view``
  directly with ``context=HTTPForbidden`` as was previously recommended.

- New API: ``pyramid.view.forbidden_view_config``.  This is a decorator
  constructor like ``pyramid.view.view_config`` that calls
  ``pyramid.config.Configurator.add_forbidden_view`` when scanned.  It should
  be preferred over using ``pyramid.view.view_config`` with
  ``context=HTTPForbidden`` as was previously recommended.

- Updated the "Creating a Not Forbidden View" section of the "Hooks" chapter,
  replacing explanations of registering a view using ``add_view`` or
  ``view_config`` with ones using ``add_forbidden_view`` or
  ``forbidden_view_config``.

- Updated all tutorials to use ``pyramid.view.forbidden_view_config`` rather
  than ``pyramid.view.view_config`` with an HTTPForbidden context.

10 files changed, 111 insertions, 54 deletions

diff --git a/docs/api/config.rst b/docs/api/config.rst
index bf5fdbb7c..cd58e74d3 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -25,6 +25,7 @@
     .. automethod:: add_static_view(name, path, cache_max_age=3600, permission=NO_PERMISSION_REQUIRED)
     .. automethod:: add_view
     .. automethod:: add_notfound_view
+    .. automethod:: add_forbidden_view
 
   :methodcategory:`Adding an Event Subscriber`
 
diff --git a/docs/api/view.rst b/docs/api/view.rst
index cb269e48e..21d2bb90d 100644
--- a/docs/api/view.rst
+++ b/docs/api/view.rst
@@ -22,6 +22,9 @@
   .. autoclass:: notfound_view_config
      :members:
 
+  .. autoclass:: forbidden_view_config
+     :members:
+
   .. autoclass:: static
      :members:
      :inherited-members:
diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index cbc40ceee..b7f052b00 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -145,23 +145,40 @@ the view which generates it can be overridden as necessary.
 
 The :term:`forbidden view` callable is a view callable like any other.  The
 :term:`view configuration` which causes it to be a "forbidden" view consists
-only of naming the :exc:`pyramid.httpexceptions.HTTPForbidden` class as the
-``context`` of the view configuration.
+of using the meth:`pyramid.config.Configurator.add_forbidden_view` API or the
+:class:`pyramid.view.forbidden_view_config` decorator.
 
-You can replace the forbidden view by using the
-:meth:`pyramid.config.Configurator.add_view` method to register an "exception
-view":
+For example, you can add a forbidden view by using the
+:meth:`pyramid.config.Configurator.add_forbidden_view` method to register a
+forbidden view:
 
 .. code-block:: python
    :linenos:
 
    from helloworld.views import forbidden_view
    from pyramid.httpexceptions import HTTPForbidden
-   config.add_view(forbidden_view, context=HTTPForbidden)
+   config.add_forbidden_view(forbidden_view)
 
 Replace ``helloworld.views.forbidden_view`` with a reference to the Python
 :term:`view callable` you want to use to represent the Forbidden view.
 
+If instead you prefer to use decorators and a :term:`scan`, you can use the
+:class:`pyramid.view.forbidden_view_config` decorator to mark a view callable
+as a forbidden view:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import forbidden_view_config
+
+   forbidden_view_config()
+   def forbidden(request):
+       return Response('forbidden')
+
+   def main(globals, **settings):
+      config = Configurator()
+      config.scan()
+
 Like any other view, the forbidden view must accept at least a ``request``
 parameter, or both ``context`` and ``request``.  The ``context`` (available
 as ``request.context`` if you're using the request-only view argument
diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst
index 8f583ece7..c1be2cc72 100644
--- a/docs/tutorials/wiki/authorization.rst
+++ b/docs/tutorials/wiki/authorization.rst
@@ -132,14 +132,14 @@ We'll add these views to the existing ``views.py`` file we have in our
 project.  Here's what the ``login`` view callable will look like:
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 83-111
+   :lines: 86-113
    :linenos:
    :language: python
 
 Here's what the ``logout`` view callable will look like:
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 113-117
+   :lines: 115-119
    :linenos:
    :language: python
 
@@ -149,18 +149,18 @@ different :term:`view configuration` for the ``login`` view callable.
 
 The first view configuration decorator configures the ``login`` view callable
 so it will be invoked when someone visits ``/login`` (when the context is a
-Wiki and the view name is ``login``).  The second decorator (with context of
-``pyramid.httpexceptions.HTTPForbidden``) specifies a :term:`forbidden view`.
-This configures our login view to be presented to the user when
-:app:`Pyramid` detects that a view invocation can not be authorized.  Because
-we've configured a forbidden view, the ``login`` view callable will be
-invoked whenever one of our users tries to execute a view callable that they
-are not allowed to invoke as determined by the :term:`authorization policy`
-in use.  In our application, for example, this means that if a user has not
-logged in, and he tries to add or edit a Wiki page, he will be shown the
-login form.  Before being allowed to continue on to the add or edit form, he
-will have to provide credentials that give him permission to add or edit via
-this login form.
+Wiki and the view name is ``login``).  The second decorator, named
+``forbidden_view_config`` specifies a :term:`forbidden view`.  This
+configures our login view to be presented to the user when :app:`Pyramid`
+detects that a view invocation can not be authorized.  Because we've
+configured a forbidden view, the ``login`` view callable will be invoked
+whenever one of our users tries to execute a view callable that they are not
+allowed to invoke as determined by the :term:`authorization policy` in use.
+In our application, for example, this means that if a user has not logged in,
+and he tries to add or edit a Wiki page, he will be shown the login form.
+Before being allowed to continue on to the add or edit form, he will have to
+provide credentials that give him permission to add or edit via this login
+form.
 
 Note that we're relying on some additional imports within the bodies of these
 views (e.g. ``remember`` and ``forget``).  We'll see a rendering of the
diff --git a/docs/tutorials/wiki/src/authorization/tutorial/views.py b/docs/tutorials/wiki/src/authorization/tutorial/views.py
index 2f0502c17..fcbe6fe25 100644
--- a/docs/tutorials/wiki/src/authorization/tutorial/views.py
+++ b/docs/tutorials/wiki/src/authorization/tutorial/views.py
@@ -3,7 +3,10 @@ import re
 
 from pyramid.httpexceptions import HTTPFound
 
-from pyramid.view import view_config
+from pyramid.view import (
+    view_config,
+    forbidden_view_config,
+    )
 
 from pyramid.security import (
     authenticated_userid,
@@ -82,8 +85,7 @@ def edit_page(context, request):
 
 @view_config(context='.models.Wiki', name='login',
              renderer='templates/login.pt')
-@view_config(context='pyramid.httpexceptions.HTTPForbidden',
-             renderer='templates/login.pt')
+@forbidden_view_config(renderer='templates/login.pt')
 def login(request):
     login_url = request.resource_url(request.context, 'login')
     referrer = request.url
diff --git a/docs/tutorials/wiki/src/tests/tutorial/views.py b/docs/tutorials/wiki/src/tests/tutorial/views.py
index 2f0502c17..fcbe6fe25 100644
--- a/docs/tutorials/wiki/src/tests/tutorial/views.py
+++ b/docs/tutorials/wiki/src/tests/tutorial/views.py
@@ -3,7 +3,10 @@ import re
 
 from pyramid.httpexceptions import HTTPFound
 
-from pyramid.view import view_config
+from pyramid.view import (
+    view_config,
+    forbidden_view_config,
+    )
 
 from pyramid.security import (
     authenticated_userid,
@@ -82,8 +85,7 @@ def edit_page(context, request):
 
 @view_config(context='.models.Wiki', name='login',
              renderer='templates/login.pt')
-@view_config(context='pyramid.httpexceptions.HTTPForbidden',
-             renderer='templates/login.pt')
+@forbidden_view_config(renderer='templates/login.pt')
 def login(request):
     login_url = request.resource_url(request.context, 'login')
     referrer = request.url
diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst
index b1d0bf37c..900bf0975 100644
--- a/docs/tutorials/wiki2/authorization.rst
+++ b/docs/tutorials/wiki2/authorization.rst
@@ -159,33 +159,35 @@ logged in user and redirect back to the front page.
 The ``login`` view callable will look something like this:
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 87-113
+   :lines: 89-115
    :linenos:
    :language: python
 
 The ``logout`` view callable will look something like this:
 
 .. literalinclude:: src/authorization/tutorial/views.py
-   :lines: 115-119
+   :lines: 117-121
    :linenos:
    :language: python
 
-The ``login`` view callable is decorated with two ``@view_config``
-decorators, one which associates it with the ``login`` route, the other which
-associates it with the ``HTTPForbidden`` context.  The one which associates
-it with the ``login`` route makes it visible when we visit ``/login``.  The
-one which associates it with the ``HTTPForbidden`` context makes it the
-:term:`forbidden view`.  The forbidden view is displayed whenever Pyramid or
-your application raises an HTTPForbidden exception.  In this case, we'll be
-relying on the forbidden view to show the login form whenver someone attempts
-to execute an action which they're not yet authorized to perform.
+The ``login`` view callable is decorated with two decorators, a
+``@view_config`` decorators, which associates it with the ``login`` route,
+the other a ``@forbidden_view_config`` decorator which turns it in to an
+:term:`exception view` when Pyramid raises a
+:class:`pyramid.httpexceptions.HTTPForbidden` exception.  The one which
+associates it with the ``login`` route makes it visible when we visit
+``/login``.  The other one makes it a :term:`forbidden view`.  The forbidden
+view is displayed whenever Pyramid or your application raises an
+HTTPForbidden exception.  In this case, we'll be relying on the forbidden
+view to show the login form whenver someone attempts to execute an action
+which they're not yet authorized to perform.
 
 The ``logout`` view callable is decorated with a ``@view_config`` decorator
 which associates it with the ``logout`` route.  This makes it visible when we
 visit ``/login``.
 
 We'll need to import some stuff to service the needs of these two functions:
-the ``HTTPForbidden`` exception, a number of values from the
+the ``pyramid.view.forbidden_view_config`` class, a number of values from the
 ``pyramid.security`` module, and a value from our newly added
 ``tutorial.security`` package.
 
diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/views.py b/docs/tutorials/wiki2/src/authorization/tutorial/views.py
index 087e6076b..1453cd2e6 100644
--- a/docs/tutorials/wiki2/src/authorization/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/authorization/tutorial/views.py
@@ -4,10 +4,12 @@ from docutils.core import publish_parts
 from pyramid.httpexceptions import (
     HTTPFound,
     HTTPNotFound,
-    HTTPForbidden,
     )
 
-from pyramid.view import view_config
+from pyramid.view import (
+    view_config,
+    forbidden_view_config,
+    )
 
 from pyramid.security import (
     remember,
@@ -85,7 +87,7 @@ def edit_page(request):
         )
 
 @view_config(route_name='login', renderer='templates/login.pt')
-@view_config(context=HTTPForbidden, renderer='templates/login.pt')
+@forbidden_view_config(renderer='templates/login.pt')
 def login(request):
     login_url = request.route_url('login')
     referrer = request.url
diff --git a/docs/tutorials/wiki2/src/tests/tutorial/views.py b/docs/tutorials/wiki2/src/tests/tutorial/views.py
index 375f1f5a5..465d98ae1 100644
--- a/docs/tutorials/wiki2/src/tests/tutorial/views.py
+++ b/docs/tutorials/wiki2/src/tests/tutorial/views.py
@@ -4,10 +4,12 @@ from docutils.core import publish_parts
 from pyramid.httpexceptions import (
     HTTPFound,
     HTTPNotFound,
-    HTTPForbidden,
     )
 
-from pyramid.view import view_config
+from pyramid.view import (
+    view_config,
+    forbidden_view_config,
+    )
 
 from pyramid.security import (
     remember,
@@ -88,7 +90,7 @@ def edit_page(request):
         )
 
 @view_config(route_name='login', renderer='templates/login.pt')
-@view_config(context=HTTPForbidden, renderer='templates/login.pt')
+@forbidden_view_config(renderer='templates/login.pt')
 def login(request):
     login_url = request.route_url('login')
     referrer = request.url
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index 7f6c3d7cb..101caed94 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -211,8 +211,10 @@ added, as well, but the configurator method should be preferred as it
 provides conflict detection and consistency in the lifetime of the
 properties.
 
-Not Found View Helpers
-~~~~~~~~~~~~~~~~~~~~~~
+Not Found and Forbidden View Helpers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Not Found helpers:
 
 - New API: :meth:`pyramid.config.Configurator.add_notfound_view`.  This is a
   wrapper for :meth:`pyramid.Config.configurator.add_view` which provides
@@ -227,6 +229,20 @@ Not Found View Helpers
   should be preferred over using ``pyramid.view.view_config`` with
   ``context=HTTPNotFound`` as was previously recommended.
 
+Forbidden helpers:
+
+- New API: :meth:`pyramid.config.Configurator.add_forbidden_view`.  This is a
+  wrapper for :meth:`pyramid.Config.configurator.add_view` which does the
+  right thing about permissions.  It should be preferred over calling
+  ``add_view`` directly with ``context=HTTPForbidden`` as was previously
+  recommended.
+
+- New API: :class:`pyramid.view.forbidden_view_config`.  This is a decorator
+  constructor like :class:`pyramid.view.view_config` that calls
+  :meth:`pyramid.config.Configurator.add_forbidden_view` when scanned.  It
+  should be preferred over using ``pyramid.view.view_config`` with
+  ``context=HTTPForbidden`` as was previously recommended.
+
 Minor Feature Additions
 -----------------------
 
@@ -431,14 +447,16 @@ Backwards Incompatibilities
   Pyramid.
 
 - The older deprecated ``set_notfound_view`` Configurator method is now an
-  alias for the new :meth:`pyramid.config.Configurator.add_notfound_view`
-  method.  This has the following impact: the ``context`` sent to views with
-  a ``(context, request)`` call signature registered via the deprecated
-  ``add_notfound_view`` / ``set_notfound_view`` will now be the HTTPNotFound
-  exception object instead of the actual resource context found.  Use
+  alias for the new ``add_notfound_view`` Configurator method.  Likewise, the
+  older deprecated ``set_forbidden_view`` is now an alias for the new
+  ``add_forbidden_view`` Configurator method. This has the following impact:
+  the ``context`` sent to views with a ``(context, request)`` call signature
+  registered via the ``set_notfound_view`` or ``set_forbidden_view`` will now
+  be an exception object instead of the actual resource context found.  Use
   ``request.context`` to get the actual resource context.  It's also
   recommended to disuse ``set_notfound_view`` in favor of
-  ``add_notfound_view``, despite the aliasing.
+  ``add_notfound_view``, and disuse ``set_forbidden_view`` in favor of
+  ``add_forbidden_view`` despite the aliasing.
 
 Deprecations
 ------------
@@ -450,8 +468,9 @@ Deprecations
   ``pyramid.view.notfound_view_config(append_slash=True)`` to get the same
   behavior.
 
-- The ``set_forbidden_view`` method of the Configurator was removed from the
-  documentation.  It has been deprecated since Pyramid 1.1.
+- The ``set_forbidden_view`` and ``set_notfound_view`` methods of the
+  Configurator were removed from the documentation.  They have been
+  deprecated since Pyramid 1.1.
 
 Documentation Enhancements
 --------------------------
@@ -485,6 +504,10 @@ Documentation Enhancements
   Rationale: it provides the correct info for the Python 2.5 version of GAE
   only, and this version of Pyramid does not support Python 2.5.
 
+- Updated the :ref:`changing_the_forbidden_view` section, replacing
+  explanations of registering a view using ``add_view`` or ``view_config``
+  with ones using ``add_forbidden_view`` or ``forbidden_view_config``.
+
 - Updated the :ref:`changing_the_notfound_view` section, replacing
   explanations of registering a view using ``add_view`` or ``view_config``
   with ones using ``add_notfound_view`` or ``notfound_view_config``.
@@ -493,6 +516,9 @@ Documentation Enhancements
   explanations of registering a view using ``add_view`` or ``view_config``
   with ones using ``add_notfound_view`` or ``notfound_view_config``
 
+- Updated all tutorials to use ``pyramid.view.forbidden_view_config`` rather
+  than ``pyramid.view.view_config`` with an HTTPForbidden context.
+
 Dependency Changes
 ------------------