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.

10 files changed, 26 insertions, 90 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
diff --git a/docs/tutorials/bfgwiki2/basiclayout.rst b/docs/tutorials/bfgwiki2/basiclayout.rst
index 4c2d5d238..6df33e9fa 100644
--- a/docs/tutorials/bfgwiki2/basiclayout.rst
+++ b/docs/tutorials/bfgwiki2/basiclayout.rst
@@ -33,10 +33,7 @@ following:
 
 #. *Line 4*. Boilerplate, the comment explains.
 
-#. *Lines 6-7*.  Register a :term:`subscriber` that tears down the
-   SQLAlchemy connection after a request is finished.
-
-#. *Lines 9-13*.  Register a ``<route>`` :term:`route configuration`
+#. *Lines 6-11*.  Register a ``<route>`` :term:`route configuration`
    that will be used when the URL is ``/``.  Since this ``<route>``
    has an empty ``path`` attribute, it is the "default" route. The
    attribute named ``view`` with the value ``.views.my_view`` is the
@@ -50,7 +47,7 @@ following:
    ``.views.my_view`` view returns a dictionary, a :term:`renderer`
    will use this template to create a response.
 
-#. *Lines 15-18*.  Register a ``<static>`` directive that will match
+#. *Lines 13-16*.  Register a ``<static>`` directive that will match
    any URL that starts with ``/static/``.  This will serve up static
    resources for us, in this case, at
    ``http://localhost:6543/static/`` and below.  With this
@@ -105,8 +102,6 @@ Here is the source for ``models.py``:
    object.  It also calls the ``populate`` function, to do initial
    database population.
 
-.. _sql_tm2_cleanup:
-
 App Startup with ``run.py``
 ---------------------------
 
@@ -121,29 +116,23 @@ function within the file named ``run.py``:
       :linenos:
       :language: py
 
-#. *Lines 1-8*. Imports to support later code.
-
-#. *Lines 10-14*.  An event :term:`subscriber` which performs cleanup
-   at transaction boundaries.  As a result of registering this event
-   subscriber, after the current transaction is committed or aborted,
-   our database connection will be removed.
+#. *Lines 1-3*. Imports to support later code.
 
-#. *Lines 22-25*. Get the database configuration string from the
+#. *Lines 11-14*. Get the database configuration string from the
    ``tutorial.ini`` file's ``[app:sql]`` section.  This will be a URI
    (something like ``sqlite://``).
 
-#. Line *26*. We initialize our SQL database using SQLAlchemy, passing
+#. Line *15*. We initialize our SQL database using SQLAlchemy, passing
    it the db string.
 
-#. *Line 27*.  We construct a :term:`Configurator`.  The first
-   argument provided to the configurator is the :term:`root factory`,
-   which is used by the :mod:`repoze.bfg` :term:`traversal` mechanism.
-   Since this is a URL dispatch application, the root factory is
-   ``None``.  The second argument ``settings`` is passed as a keyword
-   argument.  It contains a dictionary of settings parsed by
-   PasteDeploy.
+#. *Line 16*.  We construct a :term:`Configurator`.  ``settings`` is
+   passed as a keyword argument with the dictionary values passed by
+   PasteDeploy as the ``settings`` argument.  This will be a
+   dictionary of settings parsed by PasteDeploy, which contains
+   deployment-related values such as ``reload_templates``,
+   ``db_string``, etc.
 
-#. *Lines 28-31*.  We then load a ZCML file to do application
+#. *Lines 17-20*.  We then load a ZCML file to do application
    configuration, and use the
    :meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` method
    to return a :term:`WSGI` application.
diff --git a/docs/tutorials/bfgwiki2/src/authorization/tutorial/configure.zcml b/docs/tutorials/bfgwiki2/src/authorization/tutorial/configure.zcml
index 018892cd1..b87ca6398 100644
--- a/docs/tutorials/bfgwiki2/src/authorization/tutorial/configure.zcml
+++ b/docs/tutorials/bfgwiki2/src/authorization/tutorial/configure.zcml
@@ -3,9 +3,6 @@
   <!-- this must be included for the view declarations to work -->
   <include package="repoze.bfg.includes" />
 
-  <subscriber for="repoze.bfg.interfaces.INewRequest"
-    handler=".run.handle_teardown"/>
-
   <static
     name="static"
     path="templates/static"
diff --git a/docs/tutorials/bfgwiki2/src/authorization/tutorial/run.py b/docs/tutorials/bfgwiki2/src/authorization/tutorial/run.py
index 2e38bd29b..2bf8a8de7 100644
--- a/docs/tutorials/bfgwiki2/src/authorization/tutorial/run.py
+++ b/docs/tutorials/bfgwiki2/src/authorization/tutorial/run.py
@@ -1,19 +1,8 @@
-import transaction
-
 from repoze.bfg.configuration import Configurator
-from repoze.tm import after_end
-from repoze.tm import isActive
 
-from tutorial.models import DBSession
 from tutorial.models import initialize_sql
 from tutorial.models import RootFactory
 
-def handle_teardown(event):
-    environ = event.request.environ
-    if isActive(environ):
-        t = transaction.get()
-        after_end.register(DBSession.remove, t)
-
 def app(global_config, **settings):
     """ This function returns a WSGI application.
     
diff --git a/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/configure.zcml b/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/configure.zcml
index f0e5ecc20..143f58a45 100644
--- a/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/configure.zcml
+++ b/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/configure.zcml
@@ -3,9 +3,6 @@
   <!-- this must be included for the view declarations to work -->
   <include package="repoze.bfg.includes" />
 
-  <subscriber for="repoze.bfg.interfaces.INewRequest"
-    handler=".run.handle_teardown"/>
-
   <route path=""
     name="home"
     view=".views.my_view"
diff --git a/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/run.py b/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/run.py
index 6105d3eea..8e1249eab 100644
--- a/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/run.py
+++ b/docs/tutorials/bfgwiki2/src/basiclayout/tutorial/run.py
@@ -1,18 +1,7 @@
-import transaction
-
 from repoze.bfg.configuration import Configurator
-from repoze.tm import after_end
-from repoze.tm import isActive
 
-from tutorial.models import DBSession
 from tutorial.models import initialize_sql
 
-def handle_teardown(event):
-    environ = event.request.environ
-    if isActive(environ):
-        t = transaction.get()
-        after_end.register(DBSession.remove, t)
-
 def app(global_config, **settings):
     """ This function returns a WSGI application.
     
diff --git a/docs/tutorials/bfgwiki2/src/models/tutorial/configure.zcml b/docs/tutorials/bfgwiki2/src/models/tutorial/configure.zcml
index f0e5ecc20..143f58a45 100644
--- a/docs/tutorials/bfgwiki2/src/models/tutorial/configure.zcml
+++ b/docs/tutorials/bfgwiki2/src/models/tutorial/configure.zcml
@@ -3,9 +3,6 @@
   <!-- this must be included for the view declarations to work -->
   <include package="repoze.bfg.includes" />
 
-  <subscriber for="repoze.bfg.interfaces.INewRequest"
-    handler=".run.handle_teardown"/>
-
   <route path=""
     name="home"
     view=".views.my_view"
diff --git a/docs/tutorials/bfgwiki2/src/models/tutorial/run.py b/docs/tutorials/bfgwiki2/src/models/tutorial/run.py
index 6105d3eea..8e1249eab 100644
--- a/docs/tutorials/bfgwiki2/src/models/tutorial/run.py
+++ b/docs/tutorials/bfgwiki2/src/models/tutorial/run.py
@@ -1,18 +1,7 @@
-import transaction
-
 from repoze.bfg.configuration import Configurator
-from repoze.tm import after_end
-from repoze.tm import isActive
 
-from tutorial.models import DBSession
 from tutorial.models import initialize_sql
 
-def handle_teardown(event):
-    environ = event.request.environ
-    if isActive(environ):
-        t = transaction.get()
-        after_end.register(DBSession.remove, t)
-
 def app(global_config, **settings):
     """ This function returns a WSGI application.
     
diff --git a/docs/tutorials/bfgwiki2/src/views/tutorial/configure.zcml b/docs/tutorials/bfgwiki2/src/views/tutorial/configure.zcml
index 218172a1c..7a8576a56 100644
--- a/docs/tutorials/bfgwiki2/src/views/tutorial/configure.zcml
+++ b/docs/tutorials/bfgwiki2/src/views/tutorial/configure.zcml
@@ -3,9 +3,6 @@
   <!-- this must be included for the view declarations to work -->
   <include package="repoze.bfg.includes" />
 
-  <subscriber for="repoze.bfg.interfaces.INewRequest"
-    handler=".run.handle_teardown"/>
-
   <static
     name="static"
     path="templates/static"
diff --git a/docs/tutorials/bfgwiki2/src/views/tutorial/run.py b/docs/tutorials/bfgwiki2/src/views/tutorial/run.py
index 6105d3eea..8e1249eab 100644
--- a/docs/tutorials/bfgwiki2/src/views/tutorial/run.py
+++ b/docs/tutorials/bfgwiki2/src/views/tutorial/run.py
@@ -1,18 +1,7 @@
-import transaction
-
 from repoze.bfg.configuration import Configurator
-from repoze.tm import after_end
-from repoze.tm import isActive
 
-from tutorial.models import DBSession
 from tutorial.models import initialize_sql
 
-def handle_teardown(event):
-    environ = event.request.environ
-    if isActive(environ):
-        t = transaction.get()
-        after_end.register(DBSession.remove, t)
-
 def app(global_config, **settings):
     """ This function returns a WSGI application.