Remove bogus examples of 'database.transaction()'. (googleapis#6032)

tseaver · web-flow · commit 539d4b9690d2 · 2018-09-20T12:53:37.000-04:00
Use 'session.transaction()' instead. Use ReST markup to set off notes about manual transaction usage. Closes googleapis#6029.
diff --git a/spanner/docs/transaction-usage.rst b/spanner/docs/transaction-usage.rst
@@ -9,21 +9,11 @@ To understand more about how transactions work, visit :ref:`spanner-txn`.
 To learn more about how to use them in the Python client, continue reading.
 
 
-Begin a Transaction
--------------------
-
-To begin using a transaction:
-
-.. code:: python
-
-    transaction = database.transaction()
-
-
 Read Table Data
 ---------------
 
 Read data for selected rows from a table in the database.  Calls the ``Read``
-API, which returns all rows specified in ``key_set``, or else fails if the 
+API, which returns all rows specified in ``key_set``, or else fails if the
 result set is too large,
 
 .. code:: python
@@ -205,7 +195,7 @@ exception.  The function will automatically be retried for
 
         transaction.delete('citizens',
             keyset['bharney@example.com', 'nonesuch@example.com'])
- 
+
     db.run_in_transaction(_unit_of_work)
 
 
@@ -221,7 +211,7 @@ If an exception is raised inside the ``with`` block, the transaction's
 
 .. code:: python
 
-    with database.transaction() as transaction:
+    with session.transaction() as transaction:
 
         transaction.insert(
             'citizens', columns=['email', 'first_name', 'last_name', 'age'],
@@ -243,12 +233,30 @@ If an exception is raised inside the ``with`` block, the transaction's
             keyset['bharney@example.com', 'nonesuch@example.com'])
 
 
+Begin a Transaction
+-------------------
+
+.. note::
+
+   Normally, applications will not construct transactions manually.  Rather,
+   consider using :meth:`~Database.run_in_transaction` or the context manager 
+   as described above.
+
+To begin using a transaction manually:
+
+.. code:: python
+
+    transaction = session.transaction()
+
+
 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.
+.. note::
+
+   Normally, applications will not commit transactions manually.  Rather,
+   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`,
@@ -265,9 +273,11 @@ API call.
 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.
+.. note::
+
+   Normally, applications will not roll back transactions manually.  Rather,
+   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`,
