Transactions

Transaction support is provided by the transaction package [1], which is installed automatically when you install ZODB. There are two important APIs provided by the transaction package, ITransactionManager and ITransaction, described below.

ITransactionManager

interface transaction.interfaces.ITransactionManager

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.

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 ~ISynchronizer.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 the commit and abort methods could call begin, 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.

ITransaction

interface transaction.interfaces.ITransaction

Object representing a running transaction.

user = <zope.interface.interface.Attribute object at 0x7fc32c761c90 transaction.interfaces.ITransaction.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 = <zope.interface.interface.Attribute object at 0x7fc32c761c10 transaction.interfaces.ITransaction.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).

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.

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. If description is currently an empty string, then the stripped text becomes its value, else two newlines and the stripped text are appended to description.

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 via ITransactionManager.registerSynch instead.

getBeforeCommitHooks()

Return iterable producing the 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, or False if the commit aborted. args and kws are interpreted as for addBeforeCommitHook (with the exception that there is always one positional argument, the commit status). As with addBeforeCommitHook, 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.

[1]	The :mod:transaction package is a general purpose package for managing distributed transactions with a two-phase commit protocol. It can and occasionally is used with packages other than ZODB.