Spanner: run in transaction documentation (googleapis#4742)

chemelnucfin · web-flow · commit 4c18e2759cd6 · 2018-01-11T14:56:24.000-08:00
diff --git a/docs/spanner/transaction-usage.rst b/docs/spanner/transaction-usage.rst
@@ -171,43 +171,50 @@ Non-existent rows do not cause errors.
         'citizens', keyset=['bharney@example.com', 'nonesuch@example.com'])
 
 
-Commit changes for a Transaction
---------------------------------
-
-After describing the modifications to be made to table data via the
-:meth:`Transaction.insert`, :meth:`Transaction.update`,
-:meth:`Transaction.insert_or_update`, :meth:`Transaction.replace`, and
-:meth:`Transaction.delete` methods above, send them to
-the back-end by calling :meth:`Transaction.commit`, which makes the ``Commit``
-API call.
+Using :meth:`~Database.run_in_transaction`
+------------------------------------------
+
+Rather than calling :meth:`~Transaction.commit` or :meth:`~Transaction.rollback`
+manually, you should use :meth:`~Database.run_in_transaction` to run the
+function that you need.  The transaction's :meth:`~Transaction.commit` method
+will be called automatically if the ``with`` block exits without raising an
+exception.  The function will automatically be retried for
+:class:`~google.api_core.exceptions.Aborted` errors, but will raise on
+:class:`~google.api_core.exceptions.GoogleAPICallError` and
+:meth:`~Transaction.rollback` will be called on all others.
 
 .. code:: python
 
-    transaction.commit()
-
+    def _unit_of_work(transaction):
 
-Roll back changes for a Transaction
------------------------------------
+        transaction.insert(
+            'citizens', columns=['email', 'first_name', 'last_name', 'age'],
+            values=[
+                ['phred@exammple.com', 'Phred', 'Phlyntstone', 32],
+                ['bharney@example.com', 'Bharney', 'Rhubble', 31],
+            ])
 
-After describing the modifications to be made to table data via the
-:meth:`Transaction.insert`, :meth:`Transaction.update`,
-:meth:`Transaction.insert_or_update`, :meth:`Transaction.replace`, and
-:meth:`Transaction.delete` methods above, cancel the transaction on the
-the back-end by calling :meth:`Transaction.rollback`, which makes the
-``Rollback`` API call.
+        transaction.update(
+            'citizens', columns=['email', 'age'],
+            values=[
+                ['phred@exammple.com', 33],
+                ['bharney@example.com', 32],
+            ])
 
-.. code:: python
+        ...
 
-    transaction.rollback()
+        transaction.delete('citizens',
+            keyset['bharney@example.com', 'nonesuch@example.com'])
+ 
+    db.run_in_transaction(_unit_of_work)
 
 
 Use a Transaction as a Context Manager
 --------------------------------------
 
-Rather than calling :meth:`Transaction.commit` or :meth:`Transaction.rollback`
-manually, you should use the :class:`Transaction` instance as a context manager.  
-The transaction's :meth:`~Transaction.commit` method will be called automatically
-if the ``with`` block exits without raising an exception.
+Alternatively, you can use the :class:`Transaction` instance as a context
+manager.  The transaction's :meth:`~Transaction.commit` method will be called
+automatically if the ``with`` block exits without raising an exception.
 
 If an exception is raised inside the ``with`` block, the transaction's
 :meth:`~Transaction.rollback` method will automatically be called.
@@ -234,3 +241,41 @@ If an exception is raised inside the ``with`` block, the transaction's
 
         transaction.delete('citizens',
             keyset['bharney@example.com', 'nonesuch@example.com'])
+
+
+Commit changes for a Transaction
+--------------------------------
+
+This function should not be used manually.  Rather, should consider using
+:meth:`~Database.run_in_transaction` or the context manager as described
+above.
+
+After  modifications to be made to table data via the
+:meth:`Transaction.insert`, :meth:`Transaction.update`,
+:meth:`Transaction.insert_or_update`, :meth:`Transaction.replace`, and
+:meth:`Transaction.delete` methods above, send them to
+the back-end by calling :meth:`Transaction.commit`, which makes the ``Commit``
+API call.
+
+.. code:: python
+
+    transaction.commit()
+
+
+Roll back changes for a Transaction
+-----------------------------------
+
+This function should not be used manually.  Rather, should consider using
+:meth:`~Database.run_in_transaction` or the context manager as described
+above.
+
+After describing the modifications to be made to table data via the
+:meth:`Transaction.insert`, :meth:`Transaction.update`,
+:meth:`Transaction.insert_or_update`, :meth:`Transaction.replace`, and
+:meth:`Transaction.delete` methods above, cancel the transaction on the
+the back-end by calling :meth:`Transaction.rollback`, which makes the
+``Rollback`` API call.
+
+.. code:: python
+
+    transaction.rollback()
