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

  wrapper for ``pyramid.Config.configurator.add_view`` which provides easy
  append_slash support.  It should be preferred over calling ``add_view``
  directly with ``context=HTTPNotFound`` as was previously recommended.

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

- The older deprecated ``set_notfound_view`` Configurator method is now an
  alias for the new ``add_notfound_view`` Configurator 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
  ``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.

- The API documentation for ``pyramid.view.append_slash_notfound_view`` and
  ``pyramid.view.AppendSlashNotFoundViewFactory`` was removed.  These names
  still exist and are still importable, but they are no longer APIs.  Use
  ``pyramid.config.Configurator.add_notfound_view(append_slash=True)`` or
  ``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 AppendSlashNotFoundViewFactory used request.path to match routes.  This
  was wrong because request.path contains the script name, and this would
  cause it to fail in circumstances where the script name was not empty.  It
  should have used request.path_info, and now does.

- Updated the "Registering a Not Found View" section of the "Hooks" chapter,
  replacing explanations of registering a view using ``add_view`` or
  ``view_config`` with ones using ``add_notfound_view`` or
  ``notfound_view_config``.

- Updated the "Redirecting to Slash-Appended Routes" section of the "URL
  Dispatch" chapter, replacing explanations of registering a view using
  ``add_view`` or ``view_config`` with ones using ``add_notfound_view`` or
  ``notfound_view_config``

1 files changed, 68 insertions, 13 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index eaccc14a3..cbc40ceee 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -19,24 +19,66 @@ found view`, which is a :term:`view callable`. A default notfound view
 exists.  The default not found view can be overridden through application
 configuration.
 
-The :term:`not found view` callable is a view callable like any other.  The
-:term:`view configuration` which causes it to be a "not found" view consists
-only of naming the :exc:`pyramid.httpexceptions.HTTPNotFound` class as the
-``context`` of the view configuration.
-
 If your application uses :term:`imperative configuration`, you can replace
-the Not Found view by using the :meth:`pyramid.config.Configurator.add_view`
-method to register an "exception view":
+the Not Found view by using the
+:meth:`pyramid.config.Configurator.add_notfound_view` method:
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.httpexceptions import HTTPNotFound
-   from helloworld.views import notfound_view
-   config.add_view(notfound_view, context=HTTPNotFound)
+   from helloworld.views import notfound
+   config.add_notfound_view(notfound)
+
+Replace ``helloworld.views.notfound`` with a reference to the :term:`view
+callable` you want to use to represent the Not Found view.  The :term:`not
+found view` callable is a view callable like any other.
+
+If your application instead uses :class:`pyramid.view.view_config` decorators
+and a :term:`scan`, you can replace the Not Found view by using the
+:class:`pyramid.view.notfound_view_config` decorator:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import notfound_view_config
+
+   notfound_view_config()
+   def notfound(request):
+       return Response('Not Found, dude', status='404 Not Found')
+
+   def main(globals, **settings):
+      config = Configurator()
+      config.scan()
+
+This does exactly what the imperative example above showed.
 
-Replace ``helloworld.views.notfound_view`` with a reference to the
-:term:`view callable` you want to use to represent the Not Found view.
+Your application can define *multiple* not found views if necessary.  Both
+:meth:`pyramid.config.Configurator.add_notfound_view` and
+:class:`pyramid.view.notfound_view_config` take most of the same arguments as
+:class:`pyramid.config.Configurator.add_view` and
+:class:`pyramid.view.view_config`, respectively.  This means that not found
+views can carry predicates limiting their applicability.  For example:
+
+.. code-block:: python
+   :linenos:
+
+   from pyramid.view import notfound_view_config
+
+   notfound_view_config(request_method='GET')
+   def notfound_get(request):
+       return Response('Not Found during GET, dude', status='404 Not Found')
+
+   notfound_view_config(request_method='POST')
+   def notfound_post(request):
+       return Response('Not Found during POST, dude', status='404 Not Found')
+
+   def main(globals, **settings):
+      config = Configurator()
+      config.scan()
+
+The ``notfound_get`` view will be called when a view could not be found and
+the request method was ``GET``.  The ``notfound_post`` view will be called
+when a view could not be found and the request method was ``POST``.
 
 Like any other view, the notfound view must accept at least a ``request``
 parameter, or both ``context`` and ``request``.  The ``request`` is the
@@ -45,6 +87,11 @@ used in the call signature) will be the instance of the
 :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that caused the view to
 be called.
 
+Both :meth:`pyramid.config.Configurator.add_notfound_view` and
+:class:`pyramid.view.notfound_view_config` can be used to automatically
+redirect requests to slash-appended routes. See
+:ref:`redirecting_to_slash_appended_routes` for examples.
+
 Here's some sample code that implements a minimal NotFound view callable:
 
 .. code-block:: python
@@ -52,7 +99,7 @@ Here's some sample code that implements a minimal NotFound view callable:
 
    from pyramid.httpexceptions import HTTPNotFound
 
-   def notfound_view(request):
+   def notfound(request):
        return HTTPNotFound()
 
 .. note::
@@ -66,6 +113,14 @@ Here's some sample code that implements a minimal NotFound view callable:
    ``pyramid.debug_notfound`` environment setting is true than it is when it
    is false.
 
+.. note::
+
+   Both :meth:`pyramid.config.Configurator.add_notfound_view` and
+   :class:`pyramid.view.notfound_view_config` are new as of Pyramid 1.3.
+   Older Pyramid documentation instructed users to use ``add_view`` instead,
+   with a ``context`` of ``HTTPNotFound``.  This still works; the convenience
+   method and decorator are just wrappers around this functionality.
+
 .. warning::
 
    When a NotFound view callable accepts an argument list as