Features

--------

- A ``request.matched_route`` attribute is now added to the request
  when a route has matched.  Its value is the "route" object that
  matched (see the ``IRoute`` interface within
  ``repoze.bfg.interfaces`` API documentation for the API of a route
  object).

- The ``exception`` attribute of the request is now set slightly
  earlier and in a slightly different set of scenarios, for benefit of
  "finished callbacks" and "response callbacks".  In previous
  versions, the ``exception`` attribute of the request was not set at
  all if an exception view was not found.  In this version, the
  ``request.exception`` attribute is set immediately when an exception
  is caught by the router, even if an exception view could not be
  found.

Backwards Incompatibilities
---------------------------

- The router no longer sets the value ``wsgiorg.routing_args`` into
  the environ when a route matches. The value used to be something
  like ``((), matchdict)``.  This functionality was only ever
  obliquely referred to in change logs; it was never documented as an
  API.

- The ``exception`` attribute of the request now defaults to ``None``.
  In prior versions, the ``request.exception`` attribute did not exist
  if an exception was not raised by user code during request
  processing; it only began existence once an exception view was
  found.

Deprecations
------------

- References to the WSGI environment values ``bfg.routes.matchdict``
  and ``bfg.routes.route`` were removed from documentation.  These
  will stick around internally for several more releases, but it is
  ``request.matchdict`` and ``request.matched_route`` are now the
  "official" way to obtain the matchdict and the route object which
  resulted in the match.

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

- Added two sections to the "Hooks" chapter of the documentation:
  "Using Response Callbacks" and "Using Finished Callbacks".

- Added documentation of the ``request.exception`` attribute to the
  ``repoze.bfg.request.Request`` API documentation.

- Added glossary entries for "response callback" and "finished
  callback".

- The "Request Processing" narrative chapter has been updated to note
  finished and response callback steps.

1 files changed, 16 insertions, 3 deletions

diff --git a/repoze/bfg/request.py b/repoze/bfg/request.py
index 6e5417d9a..84a5660ef 100644
--- a/repoze/bfg/request.py
+++ b/repoze/bfg/request.py
@@ -40,6 +40,7 @@ class Request(WebobRequest):
     implements(IRequest)
     response_callbacks = ()
     finished_callbacks = ()
+    exception = None
     default_charset = 'utf-8'
 
     def add_response_callback(self, callback):
@@ -72,7 +73,13 @@ class Request(WebobRequest):
 
         Errors raised by callbacks are not handled specially.  They
         will be propagated to the caller of the :mod:`repoze.bfg`
-        router application.  """
+        router application.
+
+        .. note: ``add_response_callback`` is new in :mod:`repoze.bfg`
+           1.3.
+
+        See also: :ref:`using_response_callbacks`.
+        """
 
         callbacks = self.response_callbacks
         if not callbacks:
@@ -101,7 +108,7 @@ class Request(WebobRequest):
 
            def commit_callback(request):
                '''commit or abort the transaction associated with request'''
-               if hasattr(request, 'exception'):
+               if request.exception is not None:
                    transaction.abort()
                else:
                    transaction.commit()
@@ -126,7 +133,13 @@ class Request(WebobRequest):
 
         Errors raised by finished callbacks are not handled specially.
         They will be propagated to the caller of the :mod:`repoze.bfg`
-        router application.  """
+        router application.
+
+        .. note: ``add_finished_callback`` is new in :mod:`repoze.bfg`
+           1.3.
+
+        See also: :ref:`using_finished_callbacks`.
+        """
 
         callbacks = self.finished_callbacks
         if not callbacks: