diff options
| -rw-r--r-- | CHANGES.txt | 8 | ||||
| -rw-r--r-- | docs/narr/urldispatch.rst | 43 |
2 files changed, 49 insertions, 2 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 0986820e0..64d6309d9 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,12 +1,16 @@ 0.8dev (unreleased) ------------------- -Features --------- +Documentation +------------- - Added documentation to the URL Dispatch chapter about how to catch the root URL using a ZCML ``route`` directive. +- Added documentation to the URL Dispatch chapter about how to perform + a cleanup function at the end of a request (e.g. close the SQL + connection). + Bug Fixes --------- diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 7c2c71ad0..b53292d2f 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -378,6 +378,49 @@ declaration: view_name="root_view" /> +Cleaning Up After a Request +--------------------------- + +Often 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 +insert an object into the WSGI environment that performs some cleanup +when its ``__del__`` method is called. When URL dispatch is used, +however, no root factory is required, so sometimes that option 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`` BFG 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: + +.. code-block:: python + + from mypackage.sql import DBSession + + class Cleanup: + def __init__(self, cleaner): + self.cleaner = cleaner + def __del__(self): + self.cleaner() + + def handle_teardown(event): + environ = event.request.environ + environ['mypackage.sqlcleaner'] = Cleanup(DBSession.remove) + +Then in the ``configure.zcml`` of your package, inject the following: + +.. code-block:: xml + + <subscriber for="repoze.bfg.interfaces.INewRequest" + handler="mypackage.run.handle_teardown"/> + +This will cause the DBSession to be removed whenever the WSGI +environment is destroyed (usually at the end of every request). + Using :mod:`repoze.bfg` Security With URL Dispatch -------------------------------------------------- |