- New public interface: ``repoze.bfg.exceptions.IExceptionResponse``.

  This interface is provided by all internal exception classes (such
  as ``repoze.bfg.exceptions.NotFound`` and
  ``repoze.bfg.exceptions.Forbidden``), instances of which are both
  exception objects and can behave as WSGI response objects.  This
  interface is made public so that exception classes which are also
  valid WSGI response factories can be configured to implement them
  or exception instances which are also or response instances can be
  configured to provide them.

- New API class: ``repoze.bfg.view.AppendSlashNotFoundViewFactory`` (undoes 
  previous custom_notfound_view on request passsed to 
  append_slash_notfound_view).

- Previously, two default view functions were registered at
  Configurator setup (one for ``repoze.bfg.exceptions.NotFound`` named
  ``default_notfound_view`` and one for
  ``repoze.bfg.exceptions.Forbidden`` named
  ``default_forbidden_view``) to render internal exception responses.
  Those default view functions have been removed, replaced with a
  generic default view function which is registered at Configurator
  setup for the ``repoze.bfg.interfaces.IExceptionResponse`` interface
  that simply returns the exception instance; the ``NotFound` and
  ``Forbidden`` classes are now still exception factories but they are
  also response factories which generate instances that implement the
  new ``repoze.bfg.interfaces.IExceptionResponse`` interface.

1 files changed, 34 insertions, 14 deletions

diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index f0a7b87f7..07f63b9d6 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -235,21 +235,41 @@ Minor Feature Additions
 - The :func:`repoze.bfg.configuration.Configurator.add_route` API now
   returns the route object that was added.
 
-- There can only be one Not Found view in any :mod:`repoze.bfg`
-  application.  If you use
+- New API class:
+  :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory`.
+
+  There can only be one :term:`Not Found view` in any :mod:`repoze.bfg
+  application.  Even if you use
   :func:`repoze.bfg.view.append_slash_notfound_view` as the Not Found
-  view, it still must generate a 404 response when it cannot redirect
-  to a slash-appended URL; this not found response will be visible to
-  site users.  As of this release, if you wish to use a custom
-  notfound view callable when
-  :func:`repoze.bfg.view.append_slash_notfound_view` does not redirect
-  to a slash-appended URL, use a wrapper function as the
-  :exc:`repoze.bfg.exceptions.NotFound` exception view; have this
-  wrapper attach a view callable which returns a response to the
-  request object named ``custom_notfound_view`` before calling
-  :func:`repoze.bfg.view.append_slash_notfound_view`.  See
-  :func:`repoze.bfg.view.append_slash_notfound_view` for more
-  information.
+  view, :mod:`repoze.bfg` still must generate a ``404 Not Found``
+  response when it cannot redirect to a slash-appended URL; this not
+  found response will be visible to site users.
+
+  If you don't care what this 404 response looks like, and only you
+  need redirections to slash-appended route URLs, you may use the
+  :func:`repoze.bfg.view.append_slash_notfound_view` object as the Not
+  Found view.  However, if you wish to use a *custom* notfound view
+  callable when a URL cannot be redirected to a slash-appended URL,
+  you may wish to use an instance of the
+  :class:`repoze.bfg.view.AppendSlashNotFoundViewFactory` class as the
+  Not Found view, supplying a :term:`view callable` to be used as the
+  custom notfound view as the first argument to its constructor.  For
+  instance:
+
+  .. code-block:: python
+
+       from repoze.bfg.exceptions import NotFound
+       from repoze.bfg.view import AppendSlashNotFoundViewFactory
+
+       def notfound_view(context, request):
+           return HTTPNotFound('It aint there, stop trying!')
+
+       custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
+       config.add_view(custom_append_slash, context=NotFound)
+
+  The ``notfound_view`` supplied must adhere to the two-argument view
+  callable calling convention of ``(context, request)`` (``context``
+  will be the exception object).
 
 Backwards Incompatibilities
 ---------------------------