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.

2 files changed, 21 insertions, 10 deletions

diff --git a/repoze/bfg/tests/test_request.py b/repoze/bfg/tests/test_request.py
index d8a3c09fb..ae52f8420 100644
--- a/repoze/bfg/tests/test_request.py
+++ b/repoze/bfg/tests/test_request.py
@@ -23,6 +23,10 @@ class TestRequest(unittest.TestCase):
         r = self._makeOne({'PATH_INFO':'/'})
         self.assertEqual(r.charset, 'utf-8')
 
+    def test_exception_defaults_to_None(self):
+        r = self._makeOne({'PATH_INFO':'/'})
+        self.assertEqual(r.exception, None)
+
     def test_params_decoded_from_utf_8_by_default(self):
         environ = {
             'PATH_INFO':'/',
diff --git a/repoze/bfg/tests/test_router.py b/repoze/bfg/tests/test_router.py
index 199602a96..fade0679b 100644
--- a/repoze/bfg/tests/test_router.py
+++ b/repoze/bfg/tests/test_router.py
@@ -518,12 +518,11 @@ class TestRouter(unittest.TestCase):
         self.assertEqual(request.subpath, [])
         self.assertEqual(request.context, context)
         self.assertEqual(request.root, root)
-        routing_args = environ['wsgiorg.routing_args'][1]
-        self.assertEqual(routing_args['action'], 'action1')
-        self.assertEqual(routing_args['article'], 'article1')
-        self.assertEqual(environ['bfg.routes.matchdict'], routing_args)
+        matchdict = {'action':'action1', 'article':'article1'}
+        self.assertEqual(environ['bfg.routes.matchdict'], matchdict)
         self.assertEqual(environ['bfg.routes.route'].name, 'foo')
-        self.assertEqual(request.matchdict, routing_args)
+        self.assertEqual(request.matchdict, matchdict)
+        self.assertEqual(request.matched_route.name, 'foo')
 
     def test_call_route_matches_doesnt_overwrite_subscriber_iface(self):
         from repoze.bfg.interfaces import INewRequest
@@ -559,12 +558,11 @@ class TestRouter(unittest.TestCase):
         self.assertEqual(request.subpath, [])
         self.assertEqual(request.context, context)
         self.assertEqual(request.root, root)
-        routing_args = environ['wsgiorg.routing_args'][1]
-        self.assertEqual(routing_args['action'], 'action1')
-        self.assertEqual(routing_args['article'], 'article1')
-        self.assertEqual(environ['bfg.routes.matchdict'], routing_args)
+        matchdict = {'action':'action1', 'article':'article1'}
+        self.assertEqual(environ['bfg.routes.matchdict'], matchdict)
         self.assertEqual(environ['bfg.routes.route'].name, 'foo')
-        self.assertEqual(request.matchdict, routing_args)
+        self.assertEqual(request.matchdict, matchdict)
+        self.assertEqual(request.matched_route.name, 'foo')
         self.failUnless(IFoo.providedBy(request))
 
     def test_root_factory_raises_notfound(self):
@@ -634,6 +632,12 @@ class TestRouter(unittest.TestCase):
             pass
         from repoze.bfg.interfaces import IRequest
         from repoze.bfg.interfaces import IViewClassifier
+        from repoze.bfg.interfaces import IRequestFactory
+        def rfactory(environ):
+            return request
+        self.registry.registerUtility(rfactory, IRequestFactory)
+        from repoze.bfg.request import Request
+        request = Request.blank('/')
         context = DummyContext()
         directlyProvides(context, IContext)
         self._registerTraverserFactory(context, subpath=[''])
@@ -644,6 +648,9 @@ class TestRouter(unittest.TestCase):
         router = self._makeOne()
         start_response = DummyStartResponse()
         self.assertRaises(RuntimeError, router, environ, start_response)
+        # ``exception`` must be attached to request even if a suitable
+        # exception view cannot be found
+        self.assertEqual(request.exception.__class__, RuntimeError)
 
     def test_call_view_raises_exception_view(self):
         from repoze.bfg.interfaces import IViewClassifier