Next release

============

Paster Templates
----------------

- The ``bfg_alchemy`` and ``bfg_routesalchemy`` templates no longer
  register a ``handle_teardown`` event listener which calls
  ``DBSession.remove``.  This was found by Chris Withers to be
  unnecessary.

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

- The "bfgwiki2" (URL dispatch wiki) tutorial code and documentation
  was changed to remove the ``handle_teardown`` event listener which
  calls ``DBSession.remove``.

- Any mention of the ``handle_teardown`` event listener as used by the
  paster templates was removed from the URL Dispatch narrative chapter.

1 files changed, 14 insertions, 11 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 9e478ef2d..3550d57f6 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -950,7 +950,7 @@ general description of how to configure a not found view.
 Cleaning Up After a Request
 ---------------------------
 
-Often it's required that some cleanup be performed at the end of a
+Sometimes it's required that some cleanup be performed at the end of a
 request when a database connection is involved.  When
 :term:`traversal` is used, this cleanup is often done as a side effect
 of the traversal :term:`root factory`.  Often the root factory will
@@ -961,11 +961,12 @@ is not open to you.
 
 Instead of putting this cleanup logic in the root factory, however,
 you can cause a subscriber to be fired when a new request is detected;
-the subscriber can do this work.  For example, let's say you have a
-``mypackage`` :mod:`repoze.bfg` application package that uses
-SQLAlchemy, and you'd like the current SQLAlchemy database session to
-be removed after each request.  Put the following in the
-``mypackage.run`` module:
+the subscriber can do this work.
+
+For example, let's say you have a ``mypackage`` :mod:`repoze.bfg`
+application package that uses SQLAlchemy, and you'd like the current
+SQLAlchemy database session to be removed after each request.  Put the
+following in the ``mypackage.run`` module:
 
 .. ignore-next-block
 .. code-block:: python
@@ -993,11 +994,13 @@ Then in the ``configure.zcml`` of your package, inject the following:
 This will cause the DBSession to be removed whenever the WSGI
 environment is destroyed (usually at the end of every request).
 
-Alternate mechanisms for performing this sort of cleanup exist; an
-alternate mechanism which uses cleanup services offered by the
-``repoze.tm2`` package is used in the SQLAlchemy-related ``paster``
-templates generated by :mod:`repoze.bfg` and within
-:ref:`sql_tm2_cleanup` within the :ref:`bfg_sql_wiki_tutorial`.
+.. note:: This is only an example.  In particular, it is not necessary
+   to cause ``DBSession.remove`` to be called as the result of an
+   event listener in an application generated from any
+   :mod:`repoze.bfg` paster template, because these all use the
+   ``repoze.tm2`` middleware.  The cleanup done by
+   ``DBSession.remove`` is unnecessary when ``repoze.tm2`` middleware
+   is in the WSGI pipeline.
 
 .. index::
    pair: URL dispatch; security