Remove some confusion about finished callbacks.

Rework an example code and remove an incorrect statement about
request.exception being set when an exception occurs in a view.

The reason for the change is issue #454:
https://github.com/Pylons/pyramid/issues/454

1 files changed, 7 insertions, 14 deletions

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index f1a122c6c..24ea5de21 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -421,15 +421,14 @@ parameter: ``request``.  For example:
 .. code-block:: python
    :linenos:
 
-   import transaction
+   import logging
 
-   def commit_callback(request):
-       '''commit or abort the transaction associated with request'''
-       if request.exception is not None:
-           transaction.abort()
-       else:
-           transaction.commit()
-   request.add_finished_callback(commit_callback)
+   log = logging.getLogger(__name__)
+
+   def log_callback(request):
+       """Log information at the end of request"""
+       log.debug('Request is finished.')
+   request.add_finished_callback(log_callback)
 
 Finished callbacks are called in the order they're added
 (first-to-most-recently-added).  Finished callbacks (unlike a
@@ -447,12 +446,6 @@ meaningful effect, because response processing will have already occurred,
 and the request's scope will expire almost immediately after all finished
 callbacks have been processed.
 
-It is often necessary to tell whether an exception occurred within
-:term:`view callable` code from within a finished callback: in such a case,
-the :attr:`request.exception` attribute of the request when it enters a
-response callback will be an exception object instead of its default value of
-``None``.
-
 Errors raised by finished callbacks are not handled specially.  They
 will be propagated to the caller of the :app:`Pyramid` router
 application.