Commit 07ac5e24 authored by Stephan Richter's avatar Stephan Richter

MAde documentation ReST compliant. Note that savepoint.txt seems to be the

same file as ZODB/tests/testConnectionSavepoint.txt. Do we really need 
both?
parent 9cae63c4
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 Note that the data manager API, ``transaction.interfaces.IDataManager``,
- ZODB4-style data managers (transaction.interfaces.IDataManager)
Note that the data manager API, transaction.interfaces.IDataManager,
is syntactically simple, but semantically complex. The semantics is syntactically simple, but semantically complex. The semantics
were not easy to express in the interface. This could probably use were not easy to express in the interface. This could probably use
more work. The semantics are presented in detail through examples of 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``.
...@@ -12,17 +12,17 @@ a transaction allowing: ...@@ -12,17 +12,17 @@ a transaction allowing:
Savepoints make it possible to write atomic subroutines that don't Savepoints make it possible to write atomic subroutines that don't
make top-level transaction commitments. make top-level transaction commitments.
Applications Applications
------------ ------------
To demonstrate how savepoints work with transactions, we've provided a To demonstrate how savepoints work with transactions, we've provided a sample
sample data manager implementation that provides savepoint support. data manager implementation that provides savepoint support. The primary
The primary purpose of this data manager is to provide code that can purpose of this data manager is to provide code that can be read to understand
be read to understand how savepoints work. The secondary purpose is to how savepoints work. The secondary purpose is to provide support for
provide support for demonstrating the correct operation of savepoint demonstrating the correct operation of savepoint support within the
support within the transaction system. This data manager is very transaction system. This data manager is very simple. It provides flat
simple. It provides flat storage of named immutable values, like strings storage of named immutable values, like strings and numbers.
and numbers.
>>> import transaction.tests.savepointsample >>> import transaction.tests.savepointsample
>>> dm = transaction.tests.savepointsample.SampleSavepointDataManager() >>> dm = transaction.tests.savepointsample.SampleSavepointDataManager()
...@@ -43,13 +43,13 @@ and abort changes: ...@@ -43,13 +43,13 @@ and abort changes:
>>> dm['name'] >>> dm['name']
'bob' 'bob'
Now, let's look at an application that manages funds for people. Now, let's look at an application that manages funds for people. It allows
It allows deposits and debits to be entered for multiple people. deposits and debits to be entered for multiple people. It accepts a sequence
It accepts a sequence of entries and generates a sequence of status of entries and generates a sequence of status messages. For each entry, it
messages. For each entry, it applies the change and then validates applies the change and then validates the user's account. If the user's
the user's account. If the user's account is invalid, we roll back account is invalid, we roll back the change for that entry. The success or
the change for that entry. The success or failure of an entry is failure of an entry is indicated in the output status. First we'll initialize
indicated in the output status. First we'll initialize some accounts: some accounts:
>>> dm['bob-balance'] = 0.0 >>> dm['bob-balance'] = 0.0
>>> dm['bob-credit'] = 0.0 >>> dm['bob-credit'] = 0.0
...@@ -63,8 +63,8 @@ Now, we'll define a validation function to validate an account: ...@@ -63,8 +63,8 @@ Now, we'll define a validation function to validate an account:
... if dm[name+'-balance'] + dm[name+'-credit'] < 0: ... if dm[name+'-balance'] + dm[name+'-credit'] < 0:
... raise ValueError('Overdrawn', name) ... raise ValueError('Overdrawn', name)
And a function to apply entries. If the function fails in some And a function to apply entries. If the function fails in some unexpected
unexpected way, it rolls back all of its changes and prints the error: way, it rolls back all of its changes and prints the error:
>>> def apply_entries(entries): >>> def apply_entries(entries):
... savepoint = transaction.savepoint() ... savepoint = transaction.savepoint()
...@@ -118,9 +118,9 @@ If we provide entries that cause an unexpected error: ...@@ -118,9 +118,9 @@ If we provide entries that cause an unexpected error:
Updated sally Updated sally
Unexpected exception unsupported operand type(s) for +=: 'float' and 'str' Unexpected exception unsupported operand type(s) for +=: 'float' and 'str'
Because the apply_entries used a savepoint for the entire function, Because the apply_entries used a savepoint for the entire function, it was
it was able to rollback the partial changes without rolling back able to rollback the partial changes without rolling back changes made in the
changes made in the previous call to apply_entries: previous call to ``apply_entries``:
>>> dm['bob-balance'] >>> dm['bob-balance']
30.0 30.0
...@@ -195,11 +195,12 @@ However, using a savepoint invalidates any savepoints that come after it: ...@@ -195,11 +195,12 @@ However, using a savepoint invalidates any savepoints that come after it:
>>> transaction.abort() >>> transaction.abort()
Databases without savepoint support Databases without savepoint support
----------------------------------- -----------------------------------
Normally it's an error to use savepoints with databases that don't Normally it's an error to use savepoints with databases that don't support
support savepoints: savepoints:
>>> dm_no_sp = transaction.tests.savepointsample.SampleDataManager() >>> dm_no_sp = transaction.tests.savepointsample.SampleDataManager()
>>> dm_no_sp['name'] = 'bob' >>> dm_no_sp['name'] = 'bob'
...@@ -212,10 +213,10 @@ support savepoints: ...@@ -212,10 +213,10 @@ support savepoints:
>>> transaction.abort() >>> transaction.abort()
However, a flag can be passed to the transaction savepoint method to However, a flag can be passed to the transaction savepoint method to indicate
indicate that databases without savepoint support should be tolerated that databases without savepoint support should be tolerated until a savepoint
until a savepoint is rolled back. This allows transactions to proceed is rolled back. This allows transactions to proceed if there are no reasons
if there are no reasons to roll back: to roll back:
>>> dm_no_sp['name'] = 'sally' >>> dm_no_sp['name'] = 'sally'
>>> savepoint = transaction.savepoint(1) >>> savepoint = transaction.savepoint(1)
...@@ -231,13 +232,14 @@ if there are no reasons to roll back: ...@@ -231,13 +232,14 @@ if there are no reasons to roll back:
... ...
TypeError: ('Savepoints unsupported', {'name': 'sam'}) TypeError: ('Savepoints unsupported', {'name': 'sam'})
Failures Failures
-------- --------
If a failure occurs when creating or rolling back a savepoint, the If a failure occurs when creating or rolling back a savepoint, the transaction
transaction state will be uncertain and the transaction will become state will be uncertain and the transaction will become uncommitable. From
uncommitable. From that point on, most transaction operations, that point on, most transaction operations, including commit, will fail until
including commit, will fail until the transaction is aborted. the transaction is aborted.
In the previous example, we got an error when we tried to rollback the 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: savepoint. If we try to commit the transaction, the commit will fail:
...@@ -254,8 +256,8 @@ We have to abort it to make any progress: ...@@ -254,8 +256,8 @@ We have to abort it to make any progress:
>>> transaction.abort() >>> transaction.abort()
Similarly, in our earlier example, where we tried to take a savepoint Similarly, in our earlier example, where we tried to take a savepoint with a
with a data manager that didn't support savepoints: data manager that didn't support savepoints:
>>> dm_no_sp['name'] = 'sally' >>> dm_no_sp['name'] = 'sally'
>>> dm['name'] = 'sally' >>> dm['name'] = 'sally'
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment