Log message for revision 39910:
MAde documentation ReST compliant. Note that savepoint.txt seems to be the
same file as ZODB/tests/testConnectionSavepoint.txt. Do we really need
both?
Changed:
U ZODB/trunk/src/transaction/README.txt
U ZODB/trunk/src/transaction/savepoint.txt
-=-
Modified: ZODB/trunk/src/transaction/README.txt
===================================================================
--- ZODB/trunk/src/transaction/README.txt 2005-11-05 13:30:48 UTC (rev 39909)
+++ ZODB/trunk/src/transaction/README.txt 2005-11-05 13:41:40 UTC (rev 39910)
@@ -1,14 +1,13 @@
-This package is currently a facade of the ZODB.Transaction module.
+============
+Transactions
+============
-It exists to support:
+This package contains a generic transaction implementation for Python. It is
+mainly used by the ZODB, though.
-- Application code that uses the ZODB 4 transaction API
-
-- ZODB4-style data managers (transaction.interfaces.IDataManager)
-
-Note that the data manager API, transaction.interfaces.IDataManager,
+Note that the data manager API, ``transaction.interfaces.IDataManager``,
is syntactically simple, but semantically complex. The semantics
were not easy to express in the interface. This could probably use
more work. The semantics are presented in detail through examples of
-a sample data manager in transaction.tests.test_SampleDataManager.
+a sample data manager in ``transaction.tests.test_SampleDataManager``.
Modified: ZODB/trunk/src/transaction/savepoint.txt
===================================================================
--- ZODB/trunk/src/transaction/savepoint.txt 2005-11-05 13:30:48 UTC (rev 39909)
+++ ZODB/trunk/src/transaction/savepoint.txt 2005-11-05 13:41:40 UTC (rev 39910)
@@ -12,17 +12,17 @@
Savepoints make it possible to write atomic subroutines that don't
make top-level transaction commitments.
+
Applications
------------
-To demonstrate how savepoints work with transactions, we've provided a
-sample data manager implementation that provides savepoint support.
-The primary purpose of this data manager is to provide code that can
-be read to understand how savepoints work. The secondary purpose is to
-provide support for demonstrating the correct operation of savepoint
-support within the transaction system. This data manager is very
-simple. It provides flat storage of named immutable values, like strings
-and numbers.
+To demonstrate how savepoints work with transactions, we've provided a sample
+data manager implementation that provides savepoint support. The primary
+purpose of this data manager is to provide code that can be read to understand
+how savepoints work. The secondary purpose is to provide support for
+demonstrating the correct operation of savepoint support within the
+transaction system. This data manager is very simple. It provides flat
+storage of named immutable values, like strings and numbers.
>>> import transaction.tests.savepointsample
>>> dm = transaction.tests.savepointsample.SampleSavepointDataManager()
@@ -43,13 +43,13 @@
>>> dm['name']
'bob'
-Now, let's look at an application that manages funds for people.
-It allows deposits and debits to be entered for multiple people.
-It accepts a sequence of entries and generates a sequence of status
-messages. For each entry, it applies the change and then validates
-the user's account. If the user's account is invalid, we roll back
-the change for that entry. The success or failure of an entry is
-indicated in the output status. First we'll initialize some accounts:
+Now, let's look at an application that manages funds for people. It allows
+deposits and debits to be entered for multiple people. It accepts a sequence
+of entries and generates a sequence of status messages. For each entry, it
+applies the change and then validates the user's account. If the user's
+account is invalid, we roll back the change for that entry. The success or
+failure of an entry is indicated in the output status. First we'll initialize
+some accounts:
>>> dm['bob-balance'] = 0.0
>>> dm['bob-credit'] = 0.0
@@ -63,8 +63,8 @@
... if dm[name+'-balance'] + dm[name+'-credit'] < 0:
... raise ValueError('Overdrawn', name)
-And a function to apply entries. If the function fails in some
-unexpected way, it rolls back all of its changes and prints the error:
+And a function to apply entries. If the function fails in some unexpected
+way, it rolls back all of its changes and prints the error:
>>> def apply_entries(entries):
... savepoint = transaction.savepoint()
@@ -118,9 +118,9 @@
Updated sally
Unexpected exception unsupported operand type(s) for +=: 'float' and 'str'
-Because the apply_entries used a savepoint for the entire function,
-it was able to rollback the partial changes without rolling back
-changes made in the previous call to apply_entries:
+Because the apply_entries used a savepoint for the entire function, it was
+able to rollback the partial changes without rolling back changes made in the
+previous call to ``apply_entries``:
>>> dm['bob-balance']
30.0
@@ -195,11 +195,12 @@
>>> transaction.abort()
+
Databases without savepoint support
-----------------------------------
-Normally it's an error to use savepoints with databases that don't
-support savepoints:
+Normally it's an error to use savepoints with databases that don't support
+savepoints:
>>> dm_no_sp = transaction.tests.savepointsample.SampleDataManager()
>>> dm_no_sp['name'] = 'bob'
@@ -212,10 +213,10 @@
>>> transaction.abort()
-However, a flag can be passed to the transaction savepoint method to
-indicate that databases without savepoint support should be tolerated
-until a savepoint is rolled back. This allows transactions to proceed
-if there are no reasons to roll back:
+However, a flag can be passed to the transaction savepoint method to indicate
+that databases without savepoint support should be tolerated until a savepoint
+is rolled back. This allows transactions to proceed if there are no reasons
+to roll back:
>>> dm_no_sp['name'] = 'sally'
>>> savepoint = transaction.savepoint(1)
@@ -231,13 +232,14 @@
...
TypeError: ('Savepoints unsupported', {'name': 'sam'})
+
Failures
--------
-If a failure occurs when creating or rolling back a savepoint, the
-transaction state will be uncertain and the transaction will become
-uncommitable. From that point on, most transaction operations,
-including commit, will fail until the transaction is aborted.
+If a failure occurs when creating or rolling back a savepoint, the transaction
+state will be uncertain and the transaction will become uncommitable. From
+that point on, most transaction operations, including commit, will fail until
+the transaction is aborted.
In the previous example, we got an error when we tried to rollback the
savepoint. If we try to commit the transaction, the commit will fail:
@@ -254,8 +256,8 @@
>>> transaction.abort()
-Similarly, in our earlier example, where we tried to take a savepoint
-with a data manager that didn't support savepoints:
+Similarly, in our earlier example, where we tried to take a savepoint with a
+data manager that didn't support savepoints:
>>> dm_no_sp['name'] = 'sally'
>>> dm['name'] = 'sally'