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, 15 insertions, 0 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
index 86202b830..08d8d76e1 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -73,6 +73,21 @@
       :ref:`vhosting_chapter`  for  more  information  about  virtual
       roots.
 
+   .. attribute:: exception
+
+     If an exception was raised by a :term:`root factory` or a
+     :term:`view callable`, or at various other points where
+     :mod:`repoze.bfg` executes user-defined code during the
+     processing of a request, the exception object which was caught
+     will be available as the ``exception`` attribute of the request
+     within a :term:`exception view`, a :term:`response callback` or a
+     :term:`finished callback`.  If no exception occurred, the value
+     of ``request.exception`` will be ``None`` within response and
+     finished callbacks.
+
+     .. note:: The exception attribute is new in :mod:`repoze.bfg`
+        1.3.
+
 .. autofunction:: make_request_ascii