transaction
API Reference¶
Interfaces¶
- interface transaction.interfaces.ITransactionManager[source]¶
An object that manages a sequence of transactions.
Applications use transaction managers to establish transaction boundaries.
A transaction manager supports the “context manager” protocol: Its
__enter__
begins a new transaction; its__exit__
commits the current transaction if no exception has occured; otherwise, it aborts it.- explicit¶
Explicit mode indicator.
This is true if the transaction manager is in explicit mode. In explicit mode, transactions must be begun explicitly, by calling
begin
and ended explicitly by callingcommit
orabort
.Added in version 2.1.0.
- begin()¶
Explicitly begin and return a new transaction.
If an existing transaction is in progress and the transaction manager not in explicit mode, the previous transaction will be aborted. If an existing transaction is in progress and the transaction manager is in explicit mode, an
AlreadyInTransaction
exception will be raised..The
newTransaction
method of registered synchronizers is called, passing the new transaction object.Note that when not in explicit mode, transactions may be started implicitly without calling
begin
. In that case,newTransaction
isn’t called because the transaction manager doesn’t know when to call it. The transaction is likely to have begun long before the transaction manager is involved. (Conceivably thecommit
andabort
methods could callbegin
, but they don’t.)
- get()¶
Get the current transaction.
In explicit mode, if a transaction hasn’t begun, a
NoTransaction
exception will be raised.
- commit()¶
Commit the current transaction.
In explicit mode, if a transaction hasn’t begun, a
NoTransaction
exception will be raised.
- abort()¶
Abort the current transaction.
In explicit mode, if a transaction hasn’t begun, a
NoTransaction
exception will be raised.
- doom()¶
Doom the current transaction.
In explicit mode, if a transaction hasn’t begun, a
NoTransaction
exception will be raised.
- isDoomed()¶
Return True if the current transaction is doomed, otherwise False.
In explicit mode, if a transaction hasn’t begun, a
NoTransaction
exception will be raised.
- savepoint(optimistic=False)¶
Create a savepoint from the current transaction.
If the optimistic argument is true, then data managers that don’t support savepoints can be used, but an error will be raised if the savepoint is rolled back.
An
ISavepoint
object is returned.In explicit mode, if a transaction hasn’t begun, a
NoTransaction
exception will be raised.
- registerSynch(synch)¶
Register an
ISynchronizer
.Synchronizers are notified about some major events in a transaction’s life. See
ISynchronizer
for details.If a synchronizer registers while there is an active transaction, its
newTransaction
method will be called with the active transaction.
- unregisterSynch(synch)¶
Unregister an
ISynchronizer
.Synchronizers are notified about some major events in a transaction’s life. See
ISynchronizer
for details.
- clearSynchs()¶
Unregister all registered
ISynchronizer
objects.This exists to support test cleanup/initialization
- registeredSynchs()¶
Determine if any
ISynchronizers
are registered.Return true if any are registered, and return False otherwise.
This exists to support test cleanup/initialization
- attempts(number=3)¶
Generate up to number (transactional) context managers.
This method is typically used as follows:
for attempt in transaction_manager.attempts(): with attempt: *with block*
The
with attempt:
starts a new transaction for the execution of the with block. If the execution succeeds, the (then current) transaction is commited and thefor
loop terminates. If the execution raised an exception, then the transaction is aborted. If the exception was some kind ofretriable error
and the maximal number of attempts is not yet reached, then a next iteration of thefor
loop starts. In all other cases, thefor
loop terminates with the exception.
- run(func=None, tries=3)¶
Call func() in its own transaction; retry in case of some kind of
retriable error
.The call is tried up to tries times.
The call is performed in a new transaction. After the call, the (then current) transaction is committed (no exception) or aborted (exception).
run
supports the alternative signaturerun(tries=3)
. If func is not given or passed asNone
, then the call torun
returns a function taking func as argument and then callingrun(func, tries)
.
- interface transaction.interfaces.ITransaction[source]¶
Object representing a running transaction.
- user¶
A user name associated with the transaction.
The format of the user name is defined by the application. The value is text (unicode). Storages record the user value, as meta-data, when a transaction commits.
A storage may impose a limit on the size of the value; behavior is undefined if such a limit is exceeded (for example, a storage may raise an exception, or truncate the value).
- description¶
A textual description of the transaction.
The value is text (unicode). Method
note
is the intended way to set the value. Storages record the description, as meta-data, when a transaction commits.A storage may impose a limit on the size of the description; behavior is undefined if such a limit is exceeded (for example, a storage may raise an exception, or truncate the value).
- extension¶
A dictionary containing application-defined metadata.
- commit()¶
Finalize the transaction.
This executes the two-phase commit algorithm for all
IDataManager
objects associated with the transaction.
- abort()¶
Abort the transaction.
This is called from the application. This can only be called before the two-phase commit protocol has been started.
- doom()¶
Doom the transaction.
Dooms the current transaction. This will cause
DoomedTransaction
to be raised on any attempt to commit the transaction.Otherwise the transaction will behave as if it was active.
- savepoint(optimistic=False)¶
Create a savepoint.
If the optimistic argument is true, then data managers that don’t support savepoints can be used, but an error will be raised if the savepoint is rolled back.
An
ISavepoint
object is returned.
- join(datamanager)¶
Add a data manager to the transaction.
datamanager must provide the
IDataManager
interface.
- note(text)¶
Add text (unicode) to the transaction description.
This modifies the
description
attribute; see its docs for more detail. First surrounding whitespace is stripped from text. Ifdescription
is currently an empty string, then the stripped text becomes its value, else two newlines and the stripped text are appended todescription
.
- setExtendedInfo(name, value)¶
Add extension data to the transaction.
- Parameters:
name (text) – is the text (unicode) name of the extension property to set
value – must be picklable and json serializable
Multiple calls may be made to set multiple extension properties, provided the names are distinct.
Storages record the extension data, as meta-data, when a transaction commits.
A storage may impose a limit on the size of extension data; behavior is undefined if such a limit is exceeded (for example, a storage may raise an exception, or remove
<name, value>
pairs).
- addBeforeCommitHook(hook, args=(), kws=None)¶
Register a hook to call before the transaction is committed.
The specified hook function will be called after the transaction’s commit method has been called, but before the commit process has been started.
- Parameters:
args (sequence) – Additional positional arguments to be passed to the hook. The default is to pass no positional arguments.
kws (dict) – Keyword arguments to pass to the hook. The default is to pass no keyword arguments.
Multiple hooks can be registered and will be called in the order they were registered (first registered, first called). This method can also be called from a hook: an executing hook can register more hooks. Applications should take care to avoid creating infinite loops by recursively registering hooks.
Hooks are called only for a top-level commit. A savepoint creation does not call any hooks. If the transaction is aborted, hooks are not called, and are discarded. Calling a hook “consumes” its registration too: hook registrations do not persist across transactions. If it’s desired to call the same hook on every transaction commit, then
addBeforeCommitHook
must be called with that hook during every transaction; in such a case consider registering a synchronizer object viaITransactionManager.registerSynch
instead.
- getBeforeCommitHooks()¶
Return iterable producing registered
addBeforeCommitHook
hooks.A triple
(hook, args, kws)
is produced for each registered hook. The hooks are produced in the order in which they would be invoked by a top-level transaction commit.
- addAfterCommitHook(hook, args=(), kws=None)¶
Register a hook to call after a transaction commit attempt.
The specified hook function will be called after the transaction commit succeeds or aborts. The first argument passed to the hook is a Boolean value,
True
if the commit succeeded, orFalse
if the commit aborted. args and kws are interpreted as foraddBeforeCommitHook
(with the exception that there is always one positional argument, the commit status). As withaddBeforeCommitHook
, multiple hooks can be registered, savepoint creation doesn’t call any hooks, and calling a hook consumes its registration.
- getAfterCommitHooks()¶
Return iterable producing the registered
addAfterCommitHook
hooks.As with
getBeforeCommitHooks
, a triple(hook, args, kws)
is produced for each registered hook. The hooks are produced in the order in which they would be invoked by a top-level transaction commit.
- addBeforeAbortHook(hook, args=(), kws=None)¶
Register a hook to call before the transaction is aborted.
The specified hook function will be called after the transaction’s abort method has been called, but before the abort process has been started.
args and kws are interpreted as for
addBeforeCommitHook
. As withaddBeforeCommitHook
, multiple hooks can be registered, savepoint creation doesn’t call any hooks, and calling a hook consumes its registration.Abort hooks are called only for a top-level abort. If the transaction is committed, abort hooks are not called. This is true even if the commit fails. In this case, however, the transaction is in the
COMMITFAILED
state and is virtually unusable; therefore, a top-level abort will typically follow.
- getBeforeAbortHooks()¶
Return iterable producing the registered
addBeforeAbortHook
hooks.As with
getBeforeCommitHooks
, a triple(hook, args, kws)
is produced for each registered hook. The hooks are produced in the order in which they would be invoked by a top-level transaction abort.
- addAfterAbortHook(hook, args=(), kws=None)¶
Register a hook to call after a transaction abort.
The specified hook function will be called after the transaction abort.
args and kws are interpreted as for
addBeforeCommitHook
. As withaddBeforeCommitHook
, multiple hooks can be registered, savepoint creation doesn’t call any hooks, and calling a hook consumes its registration.As with
addBeforeAbortHook
, these hooks are called only for a top-level abort. See that method for more.
- getAfterAbortHooks()¶
Return iterable producing the registered
addAfterAbortHook
hooks.As with
getBeforeCommitHooks
, a triple(hook, args, kws)
is produced for each registered hook. The hooks are produced in the order in which they would be invoked by a top-level transaction abort.
- set_data(ob, data)¶
Hold data on behalf of an object
For objects such as data managers or their subobjects that work with multiple transactions, it’s convenient to store transaction-specific data on the transaction itself. The transaction knows nothing about the data, but simply holds it on behalf of the object.
The object passed should be the object that needs the data, as opposed to a simple object like a string. (Internally, the id of the object is used as the key.)
- isRetryableError(error)¶
Determine if the error is retryable.
Returns true if any joined
IRetryDataManager
considers the error transient or if the error is an instance ofTransientError
. Such errors may occur due to concurrency issues in the underlying storage engine.
- interface transaction.interfaces.IDataManager[source]¶
Objects that manage transactional storage.
These objects may manage data for other objects, or they may manage non-object storages, such as relational databases. For example, a
ZODB.Connection.Connection
.Note that when some data is modified, that data’s data manager should join a transaction so that data can be committed when the user commits the transaction.
These objects implement the two-phase commit protocol in order to allow multiple data managers to safely participate in a single transaction. The methods
tpc_begin
,commit
,tpc_vote
, and then eithertpc_finish
ortpc_abort
are normally called in that order when committing a transaction.- transaction_manager¶
The transaction manager (TM) used by this data manager.
This is a public attribute, intended for read-only use. The value is an instance of
ITransactionManager
, typically set by the data manager’s constructor.
- abort(transaction)¶
Abort a transaction and forget all changes.
Abort must be called outside of a two-phase commit.
Abort is called by the transaction manager to abort transactions that are not yet in a two-phase commit. It may also be called when rolling back a savepoint made before the data manager joined the transaction.
In any case, after abort is called, the data manager is no longer participating in the transaction. If there are new changes, the data manager must rejoin the transaction.
- tpc_begin(transaction)¶
Begin commit of a transaction, starting the two-phase commit.
transaction is the
ITransaction
instance associated with the transaction being committed.
- commit(transaction)¶
Commit modifications to registered objects.
Save changes to be made persistent if the transaction commits (if
tpc_finish
is called later). Iftpc_abort
is called later, changes must not persist.This includes conflict detection and handling. If no conflicts or errors occur, the data manager should be prepared to make the changes persist when
tpc_finish
is called.
- tpc_vote(transaction)¶
Verify that a data manager can commit the transaction.
This is the last chance for a data manager to vote ‘no’. A data manager votes ‘no’ by raising an exception.
transaction is the
ITransaction
instance associated with the transaction being committed.
- tpc_finish(transaction)¶
Indicate confirmation that the transaction is done.
Make all changes to objects modified by this transaction persist.
transaction is the
ITransaction
instance associated with the transaction being committed.This should never fail. If this raises an exception, the database is not expected to maintain consistency; it’s a serious error.
- tpc_abort(transaction)¶
Abort a transaction.
This is called by a transaction manager to end a two-phase commit on the data manager. Abandon all changes to objects modified by this transaction.
transaction is the
ITransaction
instance associated with the transaction being committed.This should never fail.
- sortKey()¶
Return a key to use for ordering registered
IDataManagers
.In order to guarantee a total ordering, keys must be
strings
.Transactions use a global sort order to prevent deadlock when committing transactions involving multiple data managers. The data managers must define a
sortKey
method that provides a global ordering across all registered data managers.
- interface transaction.interfaces.ISavepointDataManager[source]¶
Extends:
transaction.interfaces.IDataManager
- savepoint()¶
Return a data-manager savepoint (
IDataManagerSavepoint
).
- interface transaction.interfaces.IRetryDataManager[source]¶
Extends:
transaction.interfaces.IDataManager
- should_retry(exception)¶
Return whether a given exception instance should be retried.
A data manager can provide this method to indicate that a a transaction that raised the given error should be retried. This method may be called by an
ITransactionManager
when considering whether to retry a failed transaction.
- interface transaction.interfaces.IDataManagerSavepoint[source]¶
Savepoint for data-manager changes for use in transaction savepoints.
Datamanager savepoints are used by, and only by, transaction savepoints.
Note that data manager savepoints don’t have any notion of, or responsibility for, validity. It isn’t the responsibility of data-manager savepoints to prevent multiple rollbacks or rollbacks after transaction termination. Preventing invalid savepoint rollback is the responsibility of transaction rollbacks. Application code should never use data-manager savepoints.
- rollback()¶
Rollback any work done since the savepoint.
- interface transaction.interfaces.ISavepoint[source]¶
A transaction savepoint.
- rollback()¶
Rollback any work done since the savepoint.
InvalidSavepointRollbackError
is raised if the savepoint isn’t valid.
- valid¶
Boolean indicating whether the savepoint is valid
- interface transaction.interfaces.ISynchronizer[source]¶
Objects that participate in the transaction-boundary notification API.
- beforeCompletion(transaction)¶
Hook that is called by the transaction at the start of a commit.
- afterCompletion(transaction)¶
Hook that is called by the transaction after completing a commit.
Exceptions¶
- class transaction.interfaces.TransactionError[source]¶
Bases:
Exception
An error occurred due to normal transaction processing.
- class transaction.interfaces.TransactionFailedError[source]¶
Bases:
TransactionError
Cannot perform an operation on a transaction that previously failed.
An attempt was made to commit a transaction, or to join a transaction, but this transaction previously raised an exception during an attempt to commit it. The transaction must be explicitly aborted by invoking
ITransaction.abort
. (If the transaction manager is not operating in explicit mode, thenITransactionManager.begin
can also be used to perform an implicit abort.)
- class transaction.interfaces.DoomedTransaction[source]¶
Bases:
TransactionError
A commit was attempted on a transaction that was doomed.
- class transaction.interfaces.TransientError[source]¶
Bases:
TransactionError
An error has occured when performing a transaction.
It’s possible that retrying the transaction will succeed.
- class transaction.interfaces.InvalidSavepointRollbackError[source]¶
Bases:
Exception
Attempt to rollback an invalid savepoint.
A savepoint may be invalid because:
The surrounding transaction has committed or aborted.
An earlier savepoint in the same transaction has been rolled back.
- class transaction.interfaces.NoTransaction[source]¶
Bases:
TransactionError
No transaction has been defined
An application called an operation on a transaction manager that affects an exciting transaction, but no transaction was begun. The transaction manager was in explicit mode, so a new transaction was not explicitly created.
Added in version 2.1.0.
- class transaction.interfaces.AlreadyInTransaction[source]¶
Bases:
TransactionError
Attempt to create a new transaction without ending a preceding one
An application called
begin
on a transaction manager in explicit mode, without committing or aborting the previous transaction.Added in version 2.1.0.
API Objects¶
transaction
module: Exported transaction functions.
- transaction.manager = <transaction._manager.ThreadTransactionManager object>¶
The default transaction manager (a
ThreadTransactionManager
). All other functions in this module refer to this object.
- transaction.get()¶
- transaction.begin()¶
- transaction.commit()¶
- transaction.abort()¶
- transaction.doom()¶
- transaction.isDoomed()¶
- transaction.savepoint(optimistic=False)¶
- transaction.attempts(number=3)¶
- class transaction.Transaction(synchronizers=None, manager=None)[source]¶
Bases:
object
Default implementation of
ITransaction
.- isDoomed()[source]¶
See
ITransaction
.
- doom()[source]¶
See
ITransaction
.
- join(resource)[source]¶
See
ITransaction
.
- savepoint(optimistic=False)[source]¶
See
ITransaction
.
- commit()[source]¶
See
ITransaction
.
- getBeforeCommitHooks()[source]¶
See
ITransaction
.
- addBeforeCommitHook(hook, args=(), kws=None)[source]¶
See
ITransaction
.
- getAfterCommitHooks()[source]¶
See
ITransaction
.
- addAfterCommitHook(hook, args=(), kws=None)[source]¶
See
ITransaction
.
- getBeforeAbortHooks()[source]¶
See
ITransaction
.
- addBeforeAbortHook(hook, args=(), kws=None)[source]¶
See
ITransaction
.
- getAfterAbortHooks()[source]¶
See
ITransaction
.
- addAfterAbortHook(hook, args=(), kws=None)[source]¶
See
ITransaction
.
- abort()[source]¶
See
ITransaction
.
- note(text)[source]¶
See
ITransaction
.
- setUser(user_name, path='/')[source]¶
See
ITransaction
.
- setExtendedInfo(name, value)[source]¶
See
ITransaction
.
- class transaction.TransactionManager(explicit=False)[source]¶
Bases:
object
Single-thread implementation of
ITransactionManager
.- begin()[source]¶
See
ITransactionManager
.
- get()[source]¶
See
ITransactionManager
.
- registerSynch(synch)[source]¶
See
ITransactionManager
.
- unregisterSynch(synch)[source]¶
See
ITransactionManager
.
- clearSynchs()[source]¶
See
ITransactionManager
.
- registeredSynchs()[source]¶
See
ITransactionManager
.
- isDoomed()[source]¶
See
ITransactionManager
.
- doom()[source]¶
See
ITransactionManager
.
- commit()[source]¶
See
ITransactionManager
.
- abort()[source]¶
See
ITransactionManager
.
- savepoint(optimistic=False)[source]¶
See
ITransactionManager
.
- class transaction.ThreadTransactionManager[source]¶
Bases:
_local
Thread-local
transaction manager
.A thread-local transaction manager can be used as a global variable, but has a separate copy for each thread.
Advanced applications can use the
manager
attribute to get a wrappedTransactionManager
to allow cross-thread calls for graceful shutdown of data managers.
- class transaction.Savepoint(transaction, optimistic, *resources)[source]¶
Bases:
object
Implementation of
ISavepoint
, a transaction savepoint.Transaction savepoints coordinate savepoints for data managers participating in a transaction.
- rollback()[source]¶
See
ISavepoint
.