Fixed #10771 -- added support for using the transaction management functions as context managers in Python 2.5 and above. Thanks to Jacob for help with the docs.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14288 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 114 insertions, 68 deletions

diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt
index 8f722f6cbc..39037f423c 100644
--- a/docs/releases/1.3.txt
+++ b/docs/releases/1.3.txt
@@ -73,6 +73,19 @@ you just won't get any of the nice new unittest2 features.
 
 .. _unittest2: http://pypi.python.org/pypi/unittest2
 
+Transaction context managers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users of Python 2.5 and above may now use :ref:`transaction management functions
+<transaction-management-functions>` as `context managers`_. For example::
+
+    with transaction.autocommit():
+        # ...
+
+.. _context managers: http://docs.python.org/glossary.html#term-context-manager
+
+For more information, see :ref:`transaction-management-functions`.
+
 Everything else
 ~~~~~~~~~~~~~~~
 
diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt
index 2d99c17a32..57ac2bfe9d 100644
--- a/docs/topics/db/transactions.txt
+++ b/docs/topics/db/transactions.txt
@@ -2,7 +2,7 @@
 Managing database transactions
 ==============================
 
-.. currentmodule:: django.db
+.. currentmodule:: django.db.transaction
 
 Django gives you a few ways to control how database transactions are managed,
 if you're using a database that supports transactions.
@@ -50,105 +50,138 @@ An exception is ``CacheMiddleware``, which is never affected. The cache
 middleware uses its own database cursor (which is mapped to its own database
 connection internally).
 
+.. _transaction-management-functions:
+
 Controlling transaction management in views
 ===========================================
 
+.. versionchanged:: 1.3
+   Transaction management context managers are new in Django 1.3.
+
 For most people, implicit request-based transactions work wonderfully. However,
-if you need more fine-grained control over how transactions are managed, you
-can use Python decorators to change the way transactions are handled by a
-particular view function.  All of the decorators take an option ``using``
-parameter which should be the alias for a database connection for which the
-behavior applies to.  If no alias is specified then the ``"default"`` database
-is used.
+if you need more fine-grained control over how transactions are managed, you can
+use a set of functions in ``django.db.transaction`` to control transactions on a
+per-function or per-code-block basis.
 
-.. note::
+These functions, described in detail below, can be used in two different ways:
+
+    * As a decorator_ on a particular function. For example::
+    
+            from django.db import transaction
+            
+            @transaction.commit_on_success()
+            def viewfunc(request):
+                # ...
+                # this code executes inside a transaction
+                # ...
+                
+      This technique works with all supported version of Python (that is, with
+      Python 2.4 and greater).
+      
+    * As a `context manager`_ around a particular block of code::
+    
+            from django.db import transaction
+            
+            def viewfunc(request):
+                # ...
+                # this code executes using default transaction management
+                # ... 
+                
+                with transaction.commit_on_success():
+                    # ...
+                    # this code executes inside a transaction
+                    # ...
+                    
+      The ``with`` statement is new in Python 2.5, and so this syntax can only
+      be used with Python 2.5 and above.
+      
+.. _decorator: http://docs.python.org/glossary.html#term-decorator
+.. _context manager: http://docs.python.org/glossary.html#term-context-manager
+
+For maximum compatibility, all of the examples below show transactions using the
+decorator syntax, but all of the follow functions may be used as context
+managers, too.
+
+.. note:: 
 
     Although the examples below use view functions as examples, these
-    decorators can be applied to non-view functions as well.
+    decorators and context managers can be used anywhere in your code
+    that you need to deal with transactions.
 
 .. _topics-db-transactions-autocommit:
 
-``django.db.transaction.autocommit``
-------------------------------------
+.. function:: autocommit
 
-Use the ``autocommit`` decorator to switch a view function to Django's default
-commit behavior, regardless of the global transaction setting.
+    Use the ``autocommit`` decorator to switch a view function to Django's
+    default commit behavior, regardless of the global transaction setting.
 
-Example::
-
-    from django.db import transaction
+    Example::
 
-    @transaction.autocommit
-    def viewfunc(request):
-        ....
+        from django.db import transaction
 
-    @transaction.autocommit(using="my_other_database")
-    def viewfunc2(request):
-        ....
+        @transaction.autocommit
+        def viewfunc(request):
+            ....
 
-Within ``viewfunc()``, transactions will be committed as soon as you call
-``model.save()``, ``model.delete()``, or any other function that writes to the
-database.  ``viewfunc2()`` will have this same behavior, but for the
-``"my_other_database"`` connection.
+        @transaction.autocommit(using="my_other_database")
+        def viewfunc2(request):
+            ....
 
-``django.db.transaction.commit_on_success``
--------------------------------------------
+    Within ``viewfunc()``, transactions will be committed as soon as you call
+    ``model.save()``, ``model.delete()``, or any other function that writes to
+    the database.  ``viewfunc2()`` will have this same behavior, but for the
+    ``"my_other_database"`` connection.
 
-Use the ``commit_on_success`` decorator to use a single transaction for
-all the work done in a function::
+.. function:: commit_on_success
 
-    from django.db import transaction
+    Use the ``commit_on_success`` decorator to use a single transaction for all
+    the work done in a function::
 
-    @transaction.commit_on_success
-    def viewfunc(request):
-        ....
+        from django.db import transaction
 
-    @transaction.commit_on_success(using="my_other_database")
-    def viewfunc2(request):
-        ....
+        @transaction.commit_on_success
+        def viewfunc(request):
+            ....
 
-If the function returns successfully, then Django will commit all work done
-within the function at that point. If the function raises an exception, though,
-Django will roll back the transaction.
+        @transaction.commit_on_success(using="my_other_database")
+        def viewfunc2(request):
+            ....
 
-``django.db.transaction.commit_manually``
------------------------------------------
+    If the function returns successfully, then Django will commit all work done
+    within the function at that point. If the function raises an exception,
+    though, Django will roll back the transaction.
 
-Use the ``commit_manually`` decorator if you need full control over
-transactions. It tells Django you'll be managing the transaction on your own.
+.. function:: commit_manually
 
-If your view changes data and doesn't ``commit()`` or ``rollback()``, Django
-will raise a ``TransactionManagementError`` exception.
+    Use the ``commit_manually`` decorator if you need full control over
+    transactions. It tells Django you'll be managing the transaction on your
+    own.
 
-Manual transaction management looks like this::
+    If your view changes data and doesn't ``commit()`` or ``rollback()``,
+    Django will raise a ``TransactionManagementError`` exception.
 
-    from django.db import transaction
+    Manual transaction management looks like this::
 
-    @transaction.commit_manually
-    def viewfunc(request):
-        ...
-        # You can commit/rollback however and whenever you want
-        transaction.commit()
-        ...
+        from django.db import transaction
 
-        # But you've got to remember to do it yourself!
-        try:
+        @transaction.commit_manually
+        def viewfunc(request):
             ...
-        except:
-            transaction.rollback()
-        else:
+            # You can commit/rollback however and whenever you want
             transaction.commit()
+            ...
 
-    @transaction.commit_manually(using="my_other_database")
-    def viewfunc2(request):
-        ....
-
-.. admonition:: An important note to users of earlier Django releases:
+            # But you've got to remember to do it yourself!
+            try:
+                ...
+            except:
+                transaction.rollback()
+            else:
+                transaction.commit()
 
-    The database ``connection.commit()`` and ``connection.rollback()`` methods
-    (called ``db.commit()`` and ``db.rollback()`` in 0.91 and earlier) no
-    longer exist. They've been replaced by ``transaction.commit()`` and
-    ``transaction.rollback()``.
+        @transaction.commit_manually(using="my_other_database")
+        def viewfunc2(request):
+            ....
 
 How to globally deactivate transaction management
 =================================================