Features

--------

- There can only be one Not Found view in any ``repoze.bfg``
  application.  If you use
  ``repoze.bfg.view.append_slash_notfound_view`` as the Not Found
  view, it still must generate a NotFound 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 ``append_slash_notfound_view`` does not redirect to a
  slash-appended URL, use a wrapper function as the
  ``repoze.bfg.exceptions.NotFound`` view; have this wrapper attach a
  view callable which returns a response to the request object named
  ``custom_notfound_view`` before calling
  ``append_slash_notfound_view``.  For example::

       from webob.exc import HTTPNotFound
       from repoze.bfg.exceptions import NotFound
       from repoze.bfg.view import append_slash_notfound_view

       def notfound_view(exc, request):
           def fallback_notfound_view(exc, request):
               return HTTPNotFound('It aint there, stop trying!')
           request.fallback_notfound_view = fallback_notfound_view
           return append_slash_notfound_view(exc, request)

       config.add_view(notfound_view, context=NotFound)

  ``custom_notfound_view`` must adhere to the two-argument view
  callable calling convention of ``(context, request)`` (``context``
  will be the exception object).

  If ``custom_notfound_view`` is not found on the request object, a
  default notfound response will be generated when the
  ``append_slash_notfound_view`` doesn't redirect to a slash-appended
  URL.

Documentation
--------------

- Expanded the "Cleaning Up After a Request" section of the URL
  Dispatch narrative chapter.

- Expanded the "Redirecting to Slash-Appended Routes" section of the
  URL Dispatch narrative chapter.

1 files changed, 45 insertions, 2 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 916715bec..6e3a68c97 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -1058,6 +1058,8 @@ information.
 .. index::
    single: redirecting to slash-appended routes
 
+.. _redirecting_to_slash_appended_routes:
+
 Redirecting to Slash-Appended Routes
 ------------------------------------
 
@@ -1114,12 +1116,24 @@ stanza:
      view="repoze.bfg.view.append_slash_notfound_view"
     />
 
+Or use the :meth:`repoze.bfg.configuration.Configurator.add_view`
+method if you don't use ZCML:
+
+.. code-block:: python
+   :linenos:
+
+   from repoze.bfg.exceptions import NotFound
+   from repoze.bfg.view import append_slash_notfound_view
+   config.add_view(append_slash_notfound_view, context=NotFound)
+
 See :ref:`view_module` and :ref:`changing_the_notfound_view` for more
 information about the slash-appending not found view and for a more
 general description of how to configure a not found view.
 
 .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
+.. _cleaning_up_after_a_request:
+
 Cleaning Up After a Request
 ---------------------------
 
@@ -1164,8 +1178,37 @@ Then in the ``configure.zcml`` of your package, inject the following:
   <subscriber for="repoze.bfg.interfaces.INewRequest"
     handler="mypackage.run.handle_teardown"/>
 
-This will cause the DBSession to be removed whenever the WSGI
-environment is destroyed (usually at the end of every request).
+Or, if you don't use ZCML, but you do use a :term:`scan` add a
+subscriber decorator:
+
+.. code-block:: python
+
+   from repoze.bfg.events import subscriber
+   from repoze.bfg.interfaces import INewRequest
+
+   @subscriber(INewRequest)
+   def handle_teardown(event):
+       environ = event.request.environ
+       environ['mypackage.sqlcleaner'] = Cleanup(DBSession.remove)
+
+Or finally, it can be done imperatively via the ``add_subscriber``
+method of a :term:`Configurator`.
+
+.. code-block:: python
+
+   from repoze.bfg.interfaces import INewRequest
+   from repoze.bfg.configuration imoport Configurator
+
+   def handle_teardown(event):
+       environ = event.request.environ
+       environ['mypackage.sqlcleaner'] = Cleanup(DBSession.remove)
+
+   config = Configurator()
+   config.add_subscriber(handle_teardown, INewRequest)
+
+Any of the above three ways to register a handle_teardown subscriber
+will cause the DBSession to be removed whenever the WSGI environment
+is destroyed (usually at the end of every request).
 
 .. note:: This is only an example.  In particular, it is not necessary
    to cause ``DBSession.remove`` to be called as the result of an