- The BFG router now emits an additional event unconditionally at the

  end of request processing:
  ``repoze.bfg.interfaces.IFinishedRequest``.  This event is meant to
  be used when it is necessary to perform unconditional cleanup after
  request processing.  See the ``repoze.bfg.events.FinishedRequest``
  class documentation for more information.

- The ``repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`` event
  interface was renamed to
  ``repoze.bfg.interfaces.IApplicationCreated``.  Likewise, the
  ``repoze.bfg.events.WSGIApplicationCreatedEvent`` class was renamed
  to ``repoze.bfg.events.ApplicationCreated``.  The older aliases will
  continue to work indefinitely.

- The ``repoze.bfg.interfaces.IAfterTraversal`` event interface was
  renamed to ``repoze.bfg.interfaces.IContextFound``.  Likewise, the
  ``repoze.bfg.events.AfterTraveral`` class was renamed to
  ``repoze.bfg.events.ContextFound``.  The older aliases will continue
  to work indefinitely.

1 files changed, 95 insertions, 19 deletions

diff --git a/repoze/bfg/events.py b/repoze/bfg/events.py
index dd4f2eacc..301c28953 100644
--- a/repoze/bfg/events.py
+++ b/repoze/bfg/events.py
@@ -2,10 +2,11 @@ import venusian
 
 from zope.interface import implements
 
-from repoze.bfg.interfaces import IAfterTraversal
+from repoze.bfg.interfaces import IContextFound
 from repoze.bfg.interfaces import INewRequest
 from repoze.bfg.interfaces import INewResponse
-from repoze.bfg.interfaces import IWSGIApplicationCreatedEvent
+from repoze.bfg.interfaces import IApplicationCreated
+from repoze.bfg.interfaces import IFinishedRequest
 
 class subscriber(object):
     """ Decorator activated via a :term:`scan` which treats the
@@ -72,8 +73,8 @@ class subscriber(object):
 class NewRequest(object):
     """ An instance of this class is emitted as an :term:`event`
     whenever :mod:`repoze.bfg` begins to process a new request.  The
-    instance has an attribute, ``request``, which is a :term:`request`
-    object.  This class implements the
+    even instance has an attribute, ``request``, which is a
+    :term:`request` object.  This event class implements the
     :class:`repoze.bfg.interfaces.INewRequest` interface."""
     implements(INewRequest)
     def __init__(self, request):
@@ -81,12 +82,23 @@ class NewRequest(object):
 
 class NewResponse(object):
     """ An instance of this class is emitted as an :term:`event`
-    whenever any :mod:`repoze.bfg` view returns a :term:`response`.
+    whenever any :mod:`repoze.bfg` :term:`view` or :term:`exception
+    view` returns a :term:`response`.
 
     The instance has two attributes:``request``, which is the request
     which caused the response, and ``response``, which is the response
     object returned by a view or renderer.
 
+    If the ``response`` was generated by an :term:`exception view`,
+    the request will have an attribute named ``exception``, which is
+    the exception object which caused the exception view to be
+    executed.  If the response was generated by a 'normal' view, the
+    request will not have this attribute.
+
+    This event will not be generated if a response cannot be created
+    due to an exception that is not caught by an exception view (no
+    response is created under this circumstace).
+
     This class implements the
     :class:`repoze.bfg.interfaces.INewResponse` interface.
 
@@ -104,30 +116,94 @@ class NewResponse(object):
         self.request = request
         self.response = response
 
-class AfterTraversal(object):
-    implements(IAfterTraversal)
+class ContextFound(object):
+    implements(IContextFound)
     """ An instance of this class is emitted as an :term:`event` after
-    the :mod:`repoze.bfg` :term:`router` performs traversal but before
-    any view code is executed.  The instance has an attribute,
-    ``request``, which is the request object generated by
-    :mod:`repoze.bfg`.  Notably, the request object will have an
-    attribute named ``context``, which is the context that will be
-    provided to the view which will eventually be called, as well as
-    other attributes defined by the traverser.  This class implements
-    the :class:`repoze.bfg.interfaces.IAfterTraversal` interface."""
+    the :mod:`repoze.bfg` :term:`router` finds a :term:`context`
+    object (after it performs traversal) but before any view code is
+    executed.  The instance has an attribute, ``request``, which is
+    the request object generated by :mod:`repoze.bfg`.
+
+    Notably, the request object will have an attribute named
+    ``context``, which is the context that will be provided to the
+    view which will eventually be called, as well as other attributes
+    attached by context-finding code.
+
+    This class implements the
+    :class:`repoze.bfg.interfaces.IContextFound` interface.
+
+    .. note:: As of :mod:`repoze.bfg` 1.3, for backwards compatibility
+       purposes, this event may also be imported as
+       :class:`repoze.bfg.events.AfterTraversal`.
+    """
     def __init__(self, request):
         self.request = request
+
+AfterTraversal = ContextFound # b/c as of 1.3
     
-class WSGIApplicationCreatedEvent(object):    
+class ApplicationCreated(object):    
     """ An instance of this class is emitted as an :term:`event` when
     the :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` is
     called.  The instance has an attribute, ``app``, which is an
     instance of the :term:`router` that will handle WSGI requests.
     This class implements the
-    :class:`repoze.bfg.interfaces.IWSGIApplicationCreatedEvent`
-    interface."""
-    implements(IWSGIApplicationCreatedEvent)
+    :class:`repoze.bfg.interfaces.IApplicationCreated` interface.
+
+    .. note:: For backwards compatibility purposes, this class can
+       also be imported as
+       :class:`repoze.bfg.events.WSGIApplicationCreatedEvent`.  This
+       was the name of the event class before :mod:`repoze.bfg` 1.3.
+
+    """
+    implements(IApplicationCreated)
     def __init__(self, app):
         self.app = app
         self.object = app
 
+WSGIApplicationCreatedEvent = ApplicationCreated # b/c (as of 1.3)
+
+class FinishedRequest(object):
+    """
+    This :term:`event` is sent after all request processing is
+    finished.
+
+    An event of this type is emitted unconditionally at the end of
+    request processing, even when an unhandled exception occurs.  This
+    is in contrast to the :class:`repoze.bfg.interfaces.INewResponse`
+    event, which cannot be emitted when, due to an unhandled
+    exception, a response object cannot not be created .  The
+    :class:`repoze.bfg.events.FinishedRequest` event will even be sent
+    when a request cannot not be created due to an error in request
+    factory code: in such a case, the ``request`` attribute of the
+    event will be ``None``.
+
+    Mutating the attached ``request`` object in a subscriber to this
+    event will have no effect, because, when this event is emitted,
+    there is no further request or response processing to be done.  It
+    is purely an informational event, which can be hooked to do
+    'finally:'-style tear-down at the end of each request.
+
+    Instances of this event have an attribute, ``request``, which is
+    the :term:`request` object (or, in extremely rare cases might be
+    ``None``, when a request object cannot be created due to a bug in
+    a request factory) .
+
+    Because this event happens unconditionally, the set of attributes
+    possessed by an attached ``request`` object are indeterminate.  At
+    very least, if the request is not ``None``, it will have a
+    ``registry`` attribute.  However, if an exception was thrown
+    before this event is broadcast, it may not have other
+    :mod:`repoze.bfg` -specific attributes such as ``subpath``,
+    ``root`, ``traversed``, etc.
+
+    Exceptions raised by subscribers of this event are unhandled.
+
+    This class implements the
+    :class:`repoze.bfg.interfaces.IFinishedRequest` interface.
+
+    .. note:: This event type is new as of :mod:`repoze.bfg` 1.3.
+    """
+    implements(IFinishedRequest)
+    def __init__(self, request):
+        self.request = request
+