- 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.

3 files changed, 24 insertions, 18 deletions

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