python-transaction 1.1.1-2 / usr / share / pyshared / transaction / tests / doom.txt

Dooming Transactions
====================

A doomed transaction behaves exactly the same way as an active transaction but
raises an error on any attempt to commit it, thus forcing an abort.

Doom is useful in places where abort is unsafe and an exception cannot be
raised.  This occurs when the programmer wants the code following the doom to
run but not commit. It is unsafe to abort in these circumstances as a following
get() may implicitly open a new transaction.

Any attempt to commit a doomed transaction will raise a DoomedTransaction
exception.

An example of such a use case can be found in
zope/app/form/browser/editview.py.  Here a form validation failure must doom
the transaction as committing the transaction may have side-effects. However,
the form code must continue to calculate a form containing the error messages
to return.

For Zope in general, code running within a request should always doom
transactions rather than aborting them. It is the responsibilty of the
publication to either abort() or commit() the transaction. Application code can
use savepoints and doom() safely.

To see how it works we first need to create a stub data manager:

    >>> from transaction.interfaces import IDataManager
    >>> from zope.interface import implements
    >>> class DataManager:
    ...     implements(IDataManager)
    ...     def __init__(self):
    ...         self.attr_counter = {}
    ...     def __getattr__(self, name):
    ...         def f(transaction):
    ...             self.attr_counter[name] = self.attr_counter.get(name, 0) + 1
    ...         return f
    ...     def total(self):
    ...         count = 0
    ...         for access_count in self.attr_counter.values():
    ...             count += access_count
    ...         return count
    ...     def sortKey(self):
    ...         return 1

Start a new transaction:

    >>> import transaction
    >>> txn = transaction.begin()
    >>> dm = DataManager()
    >>> txn.join(dm)

We can ask a transaction if it is doomed to avoid expensive operations. An
example of a use case is an object-relational mapper where a pre-commit hook
sends all outstanding SQL to a relational database for objects changed during
the transaction. This expensive operation is not necessary if the transaction
has been doomed. A non-doomed transaction should return False:

    >>> txn.isDoomed()
    False

We can doom a transaction by calling .doom() on it:

    >>> txn.doom()
    >>> txn.isDoomed()
    True

We can doom it again if we like:

    >>> txn.doom()

The data manager is unchanged at this point:

    >>> dm.total()
    0

Attempting to commit a doomed transaction any number of times raises a
DoomedTransaction:

    >>> txn.commit() # doctest: +ELLIPSIS
    Traceback (most recent call last):
        ...
    DoomedTransaction
    >>> txn.commit() # doctest: +ELLIPSIS
    Traceback (most recent call last):
        ...
    DoomedTransaction

But still leaves the data manager unchanged:

    >>> dm.total()
    0

But the doomed transaction can be aborted:

    >>> txn.abort()

Which aborts the data manager:

    >>> dm.total()
    1
    >>> dm.attr_counter['abort']
    1

Dooming the current transaction can also be done directly from the transaction
module. We can also begin a new transaction directly after dooming the old one:

    >>> txn = transaction.begin()
    >>> transaction.isDoomed()
    False
    >>> transaction.doom()
    >>> transaction.isDoomed()
    True
    >>> txn = transaction.begin()

After committing a transaction we get an assertion error if we try to doom the
transaction. This could be made more specific, but trying to doom a transaction
after it's been committed is probably a programming error:

    >>> txn = transaction.begin()
    >>> txn.commit()
    >>> txn.doom()
    Traceback (most recent call last):
        ...
    AssertionError

A doomed transaction should act the same as an active transaction, so we should
be able to join it:

    >>> txn = transaction.begin()
    >>> txn.doom()
    >>> dm2 = DataManager()
    >>> txn.join(dm2)

Clean up:

    >>> txn = transaction.begin()
    >>> txn.abort()