Transaction

https://github.com/zopefoundation/transaction
Admin
A general-purpose transaction manager for Python applications, enabling atomic operations across...
Tokens:14,066
Snippets:95
Trust Score:9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install transaction Package

Source: https://github.com/zopefoundation/transaction/blob/master/docs/index.rst

Installs the transaction package using pip, making it available for import in Python projects. No specific inputs or outputs are detailed beyond the installation command.

```shell
$ pip install transaction
```

--------------------------------

### Setup PostgreSQL for Savepoints - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

Sets up a PostgreSQL database connection and defines a User model for demonstrating savepoints. This involves creating an engine, declarative base, and session with ZopeTransactionExtension.

```python
>>> from sqlalchemy import create_engine
>>> engine = create_engine('postgresql://postgres@127.0.0.1:5432')
>>> from sqlalchemy import Column, Integer, String
>>> from sqlalchemy.ext.declarative import declarative_base
>>> Base = declarative_base()
>>> Base.metadata.create_all(engine)
>>> class User(Base):
...     __tablename__ = 'users'
...     id = Column(Integer, primary_key=True)
...     name = Column(String)
...     fullname = Column(String)
...     password = Column(String)
...
>>> Base.metadata.create_all(engine)
>>> from sqlalchemy.orm import sessionmaker
>>> from zope.sqlalchemy import ZopeTransactionExtension
>>> Session = sessionmaker(bind=engine, extension=ZopeTransactionExtension())
```

--------------------------------

### Simple Data Manager Initialization and State - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Demonstrates the initialization of a simple `DataManager` and its initial state and delta values. This serves as a basic example for understanding the data manager's internal state before any transaction operations.

```python
from transaction.tests.examples import DataManager

rm = DataManager()

rm.state
# Expected output: 0
rm.delta
# Expected output: 0
```

--------------------------------

### Setup ZODB Connection

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

This snippet establishes a connection to a ZODB (Zope Object Database) using FileStorage. It opens a database connection and retrieves the root object for storing data.

```python
from ZODB import DB, FileStorage

storage = FileStorage.FileStorage('test.fs')
db = DB(storage)
connection = db.open()
root = connection.root()
```

--------------------------------

### Setup SQLAlchemy Database Engine and Session

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

This snippet sets up a SQLAlchemy engine for a PostgreSQL database and configures a session with the ZopeTransactionExtension for transaction management. It defines a User model and ensures the table is created in the database.

```python
from sqlalchemy import create_engine
engine = create_engine('postgresql://postgres@127.0.0.1:5432')
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()
Base.metadata.create_all(engine)
class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    fullname = Column(String)
    password = Column(String)

Base.metadata.create_all(engine)
from sqlalchemy.orm import sessionmaker
from zope.sqlalchemy import ZopeTransactionExtension
Session = sessionmaker(bind=engine, extension=ZopeTransactionExtension())
```

--------------------------------

### Basic Transaction Commit and Abort in Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/index.rst

Demonstrates the fundamental usage of the transaction package in Python. It shows how to import the library, perform operations within a try-except block, and either commit the transaction on success or abort it on encountering an error. This example assumes the existence of a 'SomeError' exception and operations that interact with transaction backends.

```python
import transaction

try:
    # some code that uses one or more backends
    .
    .
    .
    transaction.commit()
except SomeError:
    transaction.abort()
```

--------------------------------

### Python Transaction Savepoint and Rollback Example

Source: https://github.com/zopefoundation/transaction/blob/master/docs/savepoint.rst

Demonstrates creating savepoints, modifying data, rolling back to savepoints, and handling invalid rollback errors. It illustrates how savepoints allow for partial rollbacks within a transaction.

```python
>>> dm['bob-balance'] = 200.0
>>> dm['bob-balance']
200.0
>>> savepoint1 = transaction.savepoint()

>>> dm['bob-balance'] = 300.0
>>> dm['bob-balance']
300.0
>>> savepoint2 = transaction.savepoint()

>>> savepoint.rollback()
>>> dm['bob-balance']
100.0

>>> savepoint2.rollback() #doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
InvalidSavepointRollbackError: invalidated by a later savepoint

>>> savepoint1.rollback() #doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
InvalidSavepointRollbackError: invalidated by a later savepoint

>>> transaction.abort()
```

--------------------------------

### Applying Entries with Partial Rollback using Savepoints

Source: https://github.com/zopefoundation/transaction/blob/master/docs/savepoint.rst

This example shows how to apply a sequence of financial entries, validating each one and rolling back only the invalid entries using nested savepoints. It also demonstrates handling unexpected exceptions by rolling back all changes within the function.

```python
import transaction

def validate_account(name):
    if dm[name+'-balance'] + dm[name+'-credit'] < 0:
        raise ValueError('Overdrawn', name)

def apply_entries(entries):
    savepoint = transaction.savepoint()
    try:
        for name, amount in entries:
            entry_savepoint = transaction.savepoint()
            try:
                dm[name+'-balance'] += amount
                validate_account(name)
            except ValueError as error:
                entry_savepoint.rollback()
                print("%s %s" % ('Error', str(error)))
            else:
                print("%s %s" % ('Updated', name))
    except Exception as error:
        savepoint.rollback()
        print("%s" % ('Unexpected exception'))

# Initialization and example calls would precede this snippet in a full script.
```

--------------------------------

### tpc_abort Method Example - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Demonstrates the functionality of the `tpc_abort` method, showing how it resets both `state` and `delta` to zero when called without any savepoints. This effectively discards any tentative changes.

```python
from transaction.tests.examples import DataManager

rm = DataManager()
rm.inc()
t1 = '1'
rm.tpc_abort(t1)

rm.state, rm.delta
# Expected output: (0, 0)
```

--------------------------------

### Joining Doomed Transaction

Source: https://github.com/zopefoundation/transaction/blob/master/docs/doom.rst

This Python example shows that it is possible to join a data manager to a transaction even after it has been doomed. This highlights that a doomed transaction still behaves like an active transaction in terms of allowing new participants.

```python
import transaction

# Begin a transaction
txn = transaction.begin()

# Doom the transaction
txn.doom()

# Create a new DataManager
dm2 = DataManager() # Assuming DataManager is defined elsewhere

# Join the doomed transaction with the new DataManager
txn.join(dm2)

# You can verify dm2 has not been 'aborted' yet by checking its counts
print(f"DataManager 2 abort count: {dm2.attr_counter.get('abort', 0)}")
```

--------------------------------

### Savepoint Transaction Mismatch Error

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Shows an example where creating a savepoint with a different transaction identifier than the currently active one results in a `TypeError` indicating a transaction mismatch.

```python
>>> r1 = rm.savepoint(t1)
>>> rm.state, rm.delta
(1, 0)
>>> rm.inc()
>>> rm.state, rm.delta
(1, 1)
>>> t2 = '2'
>>> r2 = rm.savepoint(t2)
Traceback (most recent call last):
...
TypeError: ('Transaction missmatch', '2', '1')
```

--------------------------------

### Abort Transaction - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

Aborts a transaction after modifying a user's full name. This example shows how to revert changes when an error occurs or the operation needs to be cancelled.

```python
>>> session = Session()
>>> john = session.query(User).all()[0]
>>> john.fullname
'John Smith'
>>> john.fullname = 'John Q. Public'
>>> john.fullname
'John Q. Public'
>>> transaction.abort()
```

--------------------------------

### Using Sample Savepoint Data Manager with Transaction Commit/Abort

Source: https://github.com/zopefoundation/transaction/blob/master/docs/savepoint.rst

This snippet demonstrates the basic usage of a sample data manager that supports savepoints. It shows how to set values, commit changes, and abort changes using the transaction library.

```python
import transaction
from transaction.tests import savepointsample
dm = savepointsample.SampleSavepointDataManager()
dm['name'] = 'bob'
transaction.commit()
print(dm['name'])
dm['name'] = 'sally'
transaction.abort()
print(dm['name'])
```

--------------------------------

### Two-Phase Commit (2PC) Begin and Commit - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Shows the initial steps of a two-phase commit process using `tpc_begin` and `commit`. This demonstrates how the data manager prepares for a transaction and updates its state based on the transaction ID provided.

```python
from transaction.tests.examples import DataManager

rm = DataManager()
t1 = '1'
rm.tpc_begin(t1)
rm.commit(t1)

rm.state, rm.delta
# Expected output: (0, 1)
```

--------------------------------

### Global Transaction Management: Doom and Begin

Source: https://github.com/zopefoundation/transaction/blob/master/docs/doom.rst

Illustrates how to manage transactions using the top-level functions in the 'transaction' module. It shows how to check if the current transaction is doomed globally and how to doom it directly. It also demonstrates beginning a new transaction after dooming the previous one.

```python
import transaction

# Begin a transaction
txn = transaction.begin()

# Check global doomed status (initially False)
print(transaction.isDoomed())

# Doom the current transaction globally
transaction.doom()

# Check global doomed status again (now True)
print(transaction.isDoomed())

# Begin a new transaction, which will be active
txn = transaction.begin()
print(f"New transaction doomed status: {transaction.isDoomed()}")
```

--------------------------------

### Create SQLAlchemy Session with ZopeTransactionExtension

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

This Python snippet shows how to create a SQLAlchemy session factory and then instantiate a session. It integrates with the transaction package by using `ZopeTransactionExtension`, which automatically manages transaction joining for the SQLAlchemy session.

```python
from sqlalchemy.orm import sessionmaker
from zope.sqlalchemy import ZopeTransactionExtension

Session = sessionmaker(bind=engine, extension=ZopeTransactionExtension())
session = Session()
```

--------------------------------

### Transaction Management: Begin, Doom, and Check Status

Source: https://github.com/zopefoundation/transaction/blob/master/docs/doom.rst

Demonstrates the basic lifecycle of a transaction using the 'transaction' module. It shows how to begin a new transaction, doom it to prevent commits, and check if it's currently doomed. This is useful for understanding transaction control flow and error handling.

```python
import transaction

# Start a new transaction
txn = transaction.begin()
dm = DataManager() # Assuming DataManager is defined elsewhere
txn.join(dm)

# Check if the transaction is doomed (initially False)
print(txn.isDoomed())

# Doom the transaction
txn.doom()

# Check if the transaction is now doomed (True)
print(txn.isDoomed())

# Doom it again (no effect)
txn.doom()

# Attempt to commit a doomed transaction (raises DoomedTransaction)
try:
    txn.commit()
except Exception as e:
    print(f"Commit failed: {e}")

# Abort the doomed transaction
txn.abort()
print(f"Data manager abort count: {dm.attr_counter.get('abort', 0)}")
```

--------------------------------

### Transaction Manager API

Source: https://github.com/zopefoundation/transaction/blob/master/docs/api.rst

Documentation for TransactionManager methods, including context management.

```APIDOC
## TransactionManager API

### Description
Provides methods for managing transactions, including entering and exiting transaction contexts.

### Class
`transaction.TransactionManager`

### Methods

#### `__enter__`
Alias for `get`.

### Method
`__enter__`

### Parameters
None

### Request Body
None

### Request Example
```python
# Example of using TransactionManager as a context manager
try:
    with TransactionManager() as tm:
        # Perform operations within the transaction
        pass
except Exception as e:
    print(f"Transaction failed: {e}")
```

### Response
#### Success Response (200)
None (context manager)

#### Response Example
None
```

```APIDOC
## TransactionManager Context Exit

### Description
Handles the exiting of a transaction context. Commits the transaction on success, aborts on error.

### Method
`__exit__`

### Parameters
- `exc_type` (type) - The exception type if an exception occurred within the `with` block.
- `exc_value` (object) - The exception value if an exception occurred.
- `traceback` (object) - The traceback object if an exception occurred.

### Request Body
None

### Request Example
```python
# Example demonstrating __exit__ behavior
try:
    with TransactionManager():
        # Operations that might raise an exception
        if some_error_condition:
            raise ValueError("Something went wrong")
except ValueError as e:
    print(f"Caught expected error: {e}") # Transaction will be aborted

# If no exception, transaction is committed automatically
```

### Response
#### Success Response (200)
None (context manager)

#### Response Example
None
```

--------------------------------

### tpc_begin, tpc_vote, tpc_finish Sequence - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Demonstrates a complete transaction lifecycle from beginning to finish, including `tpc_begin`, `tpc_vote`, and `tpc_finish`. This sequence ensures that changes are applied correctly after a successful transaction.

```python
from transaction.tests.examples import DataManager

rm = DataManager()
rm.inc()
t1 = '1'
rm.tpc_begin(t1)
rm.tpc_vote(t1)
rm.tpc_finish(t1)

rm.state
# Expected output: 1
```

--------------------------------

### Multiple Before Commit Hooks and Order - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/hooks.rst

Shows how to register multiple before-commit hooks and verifies that `getBeforeCommitHooks` returns them in the order they were registered, and that `commit` calls them in that same order.

```python
from transaction import begin, commit

log = []
def reset_log():
    del log[:]

def hook(arg='no_arg', kw1='no_kw1', kw2='no_kw2'):
    log.append("arg %r kw1 %r kw2 %r" % (arg, kw1, kw2))

t = begin()
t.addBeforeCommitHook(hook, ('4',), dict(kw1='4.1'))
t.addBeforeCommitHook(hook, ('5',), dict(kw2='5.2'))

print([(h.__name__, args, kws) for h, args, kws in t.getBeforeCommitHooks()])

t.commit()

print(len(log))
print(log)
reset_log()
```

--------------------------------

### Zope Transaction Savepoint and Rollback

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Demonstrates creating a savepoint, checking its state and delta, and then performing a rollback. This code relies on the Zope transaction manager and resource manager objects.

```python
>>> rm.state, rm.delta
(1, 3)
>>> r1.rollback()
>>> rm.state, rm.delta
(1, 0)
```

--------------------------------

### Initializing Transaction Manager in Explicit Mode

Source: https://github.com/zopefoundation/transaction/blob/master/docs/developer.rst

Shows how to instantiate a transaction manager with the 'explicit' flag set to True. This enforces stricter control over transaction boundaries, preventing many common bugs.

```Python
tm = transaction.TransactionManager(explicit=True)
```

--------------------------------

### Define SQLAlchemy Mapped Class

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

This Python code defines a SQLAlchemy model class named 'User' using declarative syntax. It maps the class to a 'users' table and defines columns for 'id', 'name', 'fullname', and 'password'. The `Base.metadata.create_all(engine)` call ensures the table is created in the database.

```python
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'

    id = Column(Integer, primary_key=True)
    name = Column(String)
    fullname = Column(String)
    password = Column(String)

Base.metadata.create_all(engine)
```

--------------------------------

### Python Transaction Savepoint with Unsupported Databases

Source: https://github.com/zopefoundation/transaction/blob/master/docs/savepoint.rst

Shows how to use savepoints with databases that do not natively support them. It highlights the error that occurs by default and how a flag can be used to tolerate unsupported savepoints until a rollback is attempted.

```python
>>> dm_no_sp = savepointsample.SampleDataManager()
>>> dm_no_sp['name'] = 'bob'
>>> transaction.commit()
>>> dm_no_sp['name'] = 'sally'
>>> transaction.savepoint() #doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
TypeError: ('Savepoints unsupported', {'name': 'bob'})

>>> transaction.abort()

>>> dm_no_sp['name'] = 'sally'
>>> savepoint = transaction.savepoint(1)
>>> dm_no_sp['name'] = 'sue'
>>> transaction.commit()
>>> dm_no_sp['name']
'sue'

>>> dm_no_sp['name'] = 'sam'
>>> savepoint = transaction.savepoint(1)
>>> savepoint.rollback() #doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
TypeError: ('Savepoints unsupported', {'name': 'sam'})
```

--------------------------------

### Two-Phase Commit Methods for Resource Managers

Source: https://github.com/zopefoundation/transaction/blob/master/docs/developer.rst

This outlines the four key methods a resource manager must implement for participation in a two-phase commit. The transaction manager invokes these in a specific sequence to ensure transactional integrity across multiple resources.

```Python
def tpc_begin(txn):
    pass

def commit(txn):
    pass

def tpc_vote(txn):
    pass

def tpc_finish(txn):
    pass
```

--------------------------------

### Adding Before-Commit Hooks to Transactions

Source: https://github.com/zopefoundation/transaction/blob/master/docs/developer.rst

Demonstrates how to register a callable function to be executed just before a transaction begins its commit phase. This is useful for performing checks or initiating preparatory actions.

```Python
transaction.addBeforeCommitHook(my_callable, arg1, arg2)
```

--------------------------------

### Savepoint Rollback and Transaction Management

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Illustrates the functionality of savepoints, allowing for partial rollback of transaction state. It demonstrates saving partial work, rolling back to a savepoint, and how this affects subsequent operations and the transaction's state.

```python
>>> rm = DataManager()
>>> rm.inc()
>>> t1 = '1'
>>> r = rm.savepoint(t1)
>>> rm.state, rm.delta
(0, 1)
>>> rm.inc()
>>> rm.state, rm.delta
(0, 2)
>>> r.rollback()
>>> rm.state, rm.delta
(0, 1)
>>> rm.tpc_begin(t1)
>>> rm.tpc_vote(t1)
>>> rm.tpc_finish(t1)
>>> rm.state, rm.delta
(1, 0)
```

--------------------------------

### Create SQLAlchemy Engine

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

This Python snippet demonstrates how to create a SQLAlchemy engine to connect to a database. It uses the `create_engine` function from SQLAlchemy and is configured for an in-memory SQLite database. The connection string can be modified for other database backends.

```python
from sqlalchemy import create_engine
engine = create_engine('sqlite:///:memory:')
```

--------------------------------

### Error: Commit without tpc_begin

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Demonstrates that calling the `commit` method without first calling `tpc_begin` results in a `TypeError` indicating that the system is not prepared to commit.

```python
>>> dm = DataManager()
>>> t2 = '2'
>>> dm.commit(t2)
Traceback (most recent call last):
...
TypeError: Not prepared to commit
```

--------------------------------

### Use 'with' statement for transaction boundaries (Python)

Source: https://github.com/zopefoundation/transaction/blob/master/docs/convenience.rst

Demonstrates using the 'with' statement to define transaction boundaries. This is a convenient way to ensure transactions are properly committed or rolled back. It supports nesting and exception handling within the transaction block.

```python
import transaction.tests.savepointsample
dm = transaction.tests.savepointsample.SampleSavepointDataManager()

with transaction.manager as t:
    dm['z'] = 3
    t.note(u'test 3')

# Example showing rollback on exception
# with transaction.manager: #doctest ELLIPSIS
#     dm['z'] = 4
#     xxx
# Traceback (most recent call last):
# ...
# NameError: ... name 'xxx' is not defined

# dm['z'] will be 3 after the exception example
```

--------------------------------

### Registering and Committing an After-Commit Hook

Source: https://github.com/zopefoundation/transaction/blob/master/docs/hooks.rst

Demonstrates how to define a hook function, register it with a transaction using `addAfterCommitHook`, and then commit the transaction to trigger the hook's execution. It also shows how to retrieve registered hooks.

```python
>>> def hook(status, arg='no_arg', kw1='no_kw1', kw2='no_kw2'):
...     log.append("%r arg %r kw1 %r kw2 %r" % (status, arg, kw1, kw2))

>>> from transaction import begin
>>> t = begin()
>>> t.addAfterCommitHook(hook, ('1',))

>>> [(hook.__name__, args, kws)
...  for hook, args, kws in t.getAfterCommitHooks()]
[('hook', ('1',), {})]

>>> t.commit()
>>> log
["True arg '1' kw1 'no_kw1' kw2 'no_kw2'"]
>>> reset_log()
```

--------------------------------

### Use Savepoint and Rollback - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

Demonstrates the use of savepoints to selectively rollback changes. A savepoint is created, a second user is added, and then the savepoint is rolled back, reverting to the state before the second user was added.

```python
>>> import transaction
>>> session = Session()
>>> session.add(User(id=1, name='John', fullname='John Smith', password='123'))
>>> sp = transaction.savepoint()
>>> session.add(User(id=2, name='John', fullname='John Watson', password='123'))
>>> [o.fullname for o in session.query(User).all()]
['John Smith', 'John Watson']
>>> sp.rollback()
>>> [o.fullname for o in session.query(User).all()]
['John Smith']
>>> transaction.commit()
```

--------------------------------

### Transaction Meta Data Handling for Backward Compatibility

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

For backward compatibility, the handling of transaction meta data (user and description) has been relaxed. Previously, non-text values would be decoded using ASCII, leading to potential bugs. Now, if `None` is assigned, the assignment is ignored. If a non-text value is assigned, a warning is issued, and the value is converted to text. Binary strings are decoded using UTF-8 with the 'replace' error policy.

```python
For backward compatibility, relax the requirements that transaction
  meta data (user or description) be text:

  - If None is assigned, the assignment is ignored.

  - If a non-text value is assigned, a warning is issued and the value
    is converted to text. If the value is a binary string, it will be
    decoded with the UTF-8 encoding the ``replace`` error policy.
```

--------------------------------

### Multiple After-Commit Hooks and Order of Execution

Source: https://github.com/zopefoundation/transaction/blob/master/docs/hooks.rst

Shows how to register multiple after-commit hooks and verifies that they are called in the order they were registered during transaction commit.

```python
>>> t = begin()
>>> t.addAfterCommitHook(hook, ('4',), dict(kw1='4.1'))
>>> t.addAfterCommitHook(hook, ('5',), dict(kw2='5.2'))

>>> [(hook.__name__, args, kws)     #doctest: +NORMALIZE_WHITESPACE
...  for hook, args, kws in t.getAfterCommitHooks()]
[('hook', ('4',), {'kw1': '4.1'})
('hook', ('5',), {'kw2': '5.2'})]

>>> t.commit()
>>> len(log)
2
>>> log  #doctest: +NORMALIZE_WHITESPACE
["True arg '4' kw1 '4.1' kw2 'no_kw2'"
"True arg '5' kw1 'no_kw1' kw2 '5.2'"]
>>> reset_log()
```

--------------------------------

### Run function as a transaction with retries (Python)

Source: https://github.com/zopefoundation/transaction/blob/master/docs/convenience.rst

Provides a helper function 'run' on the transaction manager to execute a given function within a transaction. It automatically retries the function if it raises a 'TransientError', with a default of 3 retries. Other exceptions are propagated.

```python
def do_somthing():
    """Do something"""
    # ... some something ...
    pass

# Run with default retries
transaction.manager.run(do_somthing)

# Run with a specific number of retries
transaction.manager.run(do_somthing, 9)

# Using as a decorator
@transaction.manager.run
def _: 
    """Do something"""
    # ... some something ...
    pass

@transaction.manager.run(9)
def __:
    """Do something"""
    # ... some something ...
    pass
```

--------------------------------

### tpc_begin, tpc_vote, tpc_abort Sequence - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Illustrates the abortion of a transaction after `tpc_begin` and `tpc_vote` have been called. This shows how `tpc_abort` reverts the tentative changes, leaving the state unchanged.

```python
from transaction.tests.examples import DataManager

rm = DataManager()
rm.inc()
t2 = '2'
rm.tpc_begin(t2)
rm.tpc_vote(t2)
rm.tpc_abort(t2)

rm.state
# Expected output: 1
```

--------------------------------

### Commit Transaction After tpc_begin

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Details the process of committing a transaction after it has been prepared using `tpc_begin`. It shows the sequence of calling `commit`, `tpc_vote`, and `tpc_finish` to make changes persistent.

```python
>>> dm = DataManager()
>>> dm.state
0
>>> dm.inc()
>>> t1 = '1'
>>> dm.tpc_begin(t1)
>>> dm.commit(t1)
>>> dm.tpc_vote(t1)
>>> dm.tpc_finish(t1)
>>> dm.state
1
```

--------------------------------

### Abort Savepoint Transaction

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Shows how to use the `abort` method with savepoints. It highlights that when savepoints are used, the `abort` method must be passed the same transaction identifier as used for creating the savepoint.

```python
>>> dm.inc()
>>> r = dm.savepoint(t1)
>>> dm.inc()
>>> r = dm.savepoint(t1)
>>> dm.state, dm.delta
(0, 2)
>>> dm.abort(t1)
>>> dm.state, dm.delta
(0, 0)
```

--------------------------------

### Error Handling: Duplicate tpc_begin Call - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Shows the error raised when `tpc_begin` is called more than once without completing the two-phase commit process. This highlights the state management within the data manager to prevent invalid transaction states.

```python
from transaction.tests.examples import DataManager

rm = DataManager()
t1 = '1'
rm.tpc_begin(t1)

# This will raise a ValueError
# rm.tpc_begin(t1)
# Traceback (most recent call last):
# ...
# ValueError: txn in state 'tpc_begin' but expected one of (None,)

rm.tpc_abort(t1)
```

--------------------------------

### Use 'with' statement for transaction boundaries in Python

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

Demonstrates how to use the 'with' statement with the transaction module to define transaction boundaries. This simplifies transaction management by automatically handling commit or rollback operations. It requires the 'transaction' module to be imported.

```python
import transaction

with transaction:
    # do some things within the transaction boundary
```

--------------------------------

### Adding Before Abort Hooks to Transactions

Source: https://github.com/zopefoundation/transaction/blob/master/docs/developer.rst

Illustrates the mechanism for registering a function to be executed before a transaction is aborted. This is distinct from commit hooks and specific to abort scenarios.

```Python
transaction.addBeforeAbortHook(my_callable, arg1, arg2)
```

--------------------------------

### Thread Transaction Manager

Source: https://github.com/zopefoundation/transaction/blob/master/docs/api.rst

A transaction manager implementation suitable for multi-threaded environments.

```APIDOC
## ThreadTransactionManager

### Description
An implementation of `ITransactionManager` designed for use in multi-threaded applications. It ensures that transactions are managed correctly per thread.

### Class
`transaction.ThreadTransactionManager`

### Methods
(Specific methods for thread-safe transaction management would be detailed here.)

### Parameters
None

### Request Body
None

### Request Example
```python
from transaction import ThreadTransactionManager

tm = ThreadTransactionManager()
# Use tm for managing transactions in a threaded context
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Error Handling: Transaction Mismatch in tpc_begin - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Demonstrates the `TypeError` raised when `tpc_begin` is called with a different transaction ID than a pre-existing savepoint. This enforces the requirement that savepoint transactions must match the current transaction.

```python
from transaction.tests.examples import DataManager

rm = DataManager()
t1 = '1'
t2 = '2'
rm.savepoint(t1)

# This will raise a TypeError
# rm.tpc_begin(t2)
# Traceback (most recent call last):
# ...
# TypeError: ('Transaction missmatch', '2', '1')

rm.tpc_begin(t1)
```

--------------------------------

### Adding After Abort Hooks to Transactions

Source: https://github.com/zopefoundation/transaction/blob/master/docs/developer.rst

Demonstrates how to register a function to be executed after a transaction has completed its abort process. This allows for cleanup or logging after an abort.

```Python
transaction.addAfterAbortHook(my_callable, arg1, arg2)
```

--------------------------------

### Run Function as Transaction with Retries

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

Provides a method to execute a function within a transaction, with automatic retries for transient errors. This is useful for operations that might fail temporarily and can be safely retried.

```python
import transaction

def my_operation():
    # Perform some operations that might fail temporarily
    pass

try:
    transaction.manager.run(my_operation)
except Exception as e:
    print(f"Operation failed: {e}")
```

--------------------------------

### Abort Two-Phase Commit Transaction

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Demonstrates how to abort a two-phase commit transaction using the `tpc_abort` method. It ensures that the transaction object passed to `tpc_abort` matches the one used in `tpc_begin` to prevent mismatches.

```python
>>> rm.inc()
>>> rm.state, rm.delta
(0, 1)
>>> rm.tpc_begin(t1)
>>> rm.state, rm.delta
(0, 1)
>>> rm.tpc_vote(t1)
>>> rm.state, rm.delta
(1, 1)
>>> rm.tpc_abort(t1)
>>> rm.state, rm.delta
(0, 0)
```

--------------------------------

### Register and Call Before Commit Hook - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/hooks.rst

Demonstrates registering a function as a before-commit hook using `addBeforeCommitHook`. The hook is called with specified positional and keyword arguments when the transaction commits. Hooks are consumed after execution.

```python
from transaction import begin, commit

log = []
def reset_log():
    del log[:]

def hook(arg='no_arg', kw1='no_kw1', kw2='no_kw2'):
    log.append("arg %r kw1 %r kw2 %r" % (arg, kw1, kw2))

t = begin()
t.addBeforeCommitHook(hook, ('1',))
t.commit()

print(log)
reset_log()

t = begin()
t.addBeforeCommitHook(hook, ('A',), dict(kw1='B'))
t.savepoint()
t.commit()

print(log)
reset_log()

t = begin()
t.addBeforeCommitHook(hook, ["OOPS!"])
transaction.abort()

print(log)
transaction.commit()

print(log)
reset_log()
```

--------------------------------

### Adding After-Commit Hooks to Transactions

Source: https://github.com/zopefoundation/transaction/blob/master/docs/developer.rst

Shows how to attach a function that will be called after a transaction has successfully committed or aborted. The hook receives a boolean indicating the commit status.

```Python
transaction.addAfterCommitHook(my_callable, arg1, arg2)
```

--------------------------------

### Python Transaction Failure Handling with Savepoints

Source: https://github.com/zopefoundation/transaction/blob/master/docs/savepoint.rst

Illustrates the behavior of a transaction when a savepoint operation fails. It demonstrates that the transaction becomes uncommitable and must be aborted to proceed with new transactions. This includes errors during savepoint creation and rollback on unsupported databases.

```python
>>> transaction.commit() #doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
TransactionFailedError: An operation previously failed, with traceback:
...
TypeError: ('Savepoints unsupported', {'name': 'sam'})
<BLANKLINE>

>>> transaction.abort()

>>> dm_no_sp['name'] = 'sally'
>>> dm['name'] = 'sally'
>>> savepoint = transaction.savepoint() # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
TypeError: ('Savepoints unsupported', {'name': 'sue'})

>>> transaction.commit() #doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
TransactionFailedError: An operation previously failed, with traceback:
...
TypeError: ('Savepoints unsupported', {'name': 'sue'})
<BLANKLINE>

>>> transaction.abort()

>>> dm_no_sp['name'] = 'sally'
>>> dm['name'] = 'sally'
>>> transaction.commit()
>>> dm_no_sp['name']
'sally'
>>> dm['name']
'sally'
```

--------------------------------

### TransactionManager.run Transaction Handling

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

The TransactionManager.run method's behavior regarding transaction commits and aborts has been updated. It now commits/aborts the transaction active *after* the execution of the provided function, rather than the initial transaction. This ensures that any commit/abort actions within the function itself are respected. The method also now aborts the transaction for all exceptions raised by the function, including BaseException subclasses like SystemExit and KeyboardInterrupt.

```python
TransactionManager.run now commits/aborts the transaction
  "active" after the execution of *func* (and no longer the initial
  transaction which might already have been committed/aborted by *func*)
  (`#58 <https://github.com/zopefoundation/transaction/issues/58>`_).

  It aborts the transaction now for all exceptions raised by *func* - even
  if it is only an instance of `BaseException` but not of `Exception`,
  such as e.g. a ``SystemExit`` or ``KeyboardInterupt`` exception.
```

--------------------------------

### Transaction Mismatch during tpc_begin and Abort

Source: https://github.com/zopefoundation/transaction/blob/master/docs/datamanager.rst

Illustrates a `TypeError` when `abort` is called with a transaction identifier that does not match the one used in `tpc_begin`, even if there's no current transaction.

```python
>>> dm.tpc_begin(t1)
>>> dm.abort(t2)
Traceback (most recent call last):
...
TypeError: ('Transaction missmatch', '2', '1')
```

--------------------------------

### Transaction Interface Decorator Usage

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

Demonstrates the use of `zope.interface.implementer` as a class decorator to declare that a class implements an interface, replacing the older `zope.interface.implements` class advisor. This is a more modern and Pythonic way to handle interface implementation.

```python
from zope.interface import Interface, implementer

class IMyInterface(Interface):
    def my_method(self):
        """A sample method."""

@implementer(IMyInterface)
class MyClass:
    def my_method(self):
        print("Implementing my_method")

# Verification
if IMyInterface.providedBy(MyClass()):
    print("MyClass implements IMyInterface")
else:
    print("MyClass does not implement IMyInterface")
```

--------------------------------

### Handling Commit Failures with Before Commit Hooks - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/hooks.rst

Illustrates that before-commit hooks are executed even if the transaction commit process subsequently fails. A custom `FailingDataManager` is used to simulate a commit failure, showing that the hook still runs.

```python
from transaction import begin, commit
from transaction import _transaction
from transaction.tests.common import DummyFile, Monkey, assertRaisesEx

class CommitFailure(Exception):
    pass

class FailingDataManager:
    def tpc_begin(self, txn, sub=False):
        raise CommitFailure('failed')
    def abort(self, txn):
        pass

log = []
def reset_log():
    del log[:]

def hook(arg='no_arg', kw1='no_kw1', kw2='no_kw2'):
    log.append("arg %r kw1 %r kw2 %r" % (arg, kw1, kw2))

t = begin()
t.join(FailingDataManager())
t.addBeforeCommitHook(hook, ('2',))

with Monkey(_transaction, _TB_BUFFER=DummyFile()):
    assertRaisesEx(CommitFailure, t.commit)

print(log)
reset_log()
```

--------------------------------

### Transaction Manager Free Method Error Handling

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

Modifies `TransactionManager.free` to raise a `ValueError` if passed a foreign transaction. This prevents incorrect usage and ensures transactions are managed within their originating managers.

```python
import transaction

tm1 = transaction.TransactionManager()
tm2 = transaction.TransactionManager()

t1 = tm1.get()
t2 = tm2.get()

try:
    # Attempt to free a transaction from a different manager
    tm1.free(t2)
except ValueError as e:
    print(f"Caught expected error for foreign transaction: {e}")
except Exception as e:
    print(f"Caught unexpected error: {e}")
```

--------------------------------

### Handling Commit Failures with After-Commit Hooks

Source: https://github.com/zopefoundation/transaction/blob/master/docs/hooks.rst

Demonstrates how after-commit hooks are executed even if the transaction commit itself fails. A custom `FailingDataManager` is used to simulate a commit failure, and the hook's execution status is logged.

```python
>>> class CommitFailure(Exception):
...     pass
>>> class FailingDataManager:
...     def tpc_begin(self, txn):
...         raise CommitFailure('failed')
...     def abort(self, txn):
...         pass

>>> t = begin()
>>> t.join(FailingDataManager())

>>> t.addAfterCommitHook(hook, ('2',))
>>> from transaction.tests.common import DummyFile
>>> from transaction.tests.common import Monkey
>>> from transaction.tests.common import assertRaisesEx
>>> from transaction import _transaction
>>> buffer = DummyFile()
>>> with Monkey(_transaction, _TB_BUFFER=buffer):
...     err = assertRaisesEx(CommitFailure, t.commit)
>>> log
["False arg '2' kw1 'no_kw1' kw2 'no_kw2'"]
>>> reset_log()
```

--------------------------------

### Retry code blocks using an attempt iterator (Python)

Source: https://github.com/zopefoundation/transaction/blob/master/docs/convenience.rst

Offers an iterator-based approach for retrying code blocks within transactions. The 'attempts' method provides an iterator that yields 'attempt' objects. Each attempt can be used with a 'with' statement to execute code that will be retried upon transient errors.

```python
# Use with default number of attempts (3)
for attempt in transaction.manager.attempts():
    with attempt as t:
        # ... some something ...
        pass

# Use with a specific number of attempts
for attempt in transaction.manager.attempts(9):
    with attempt as t:
        # ... some something ...
        pass
```

--------------------------------

### ThreadTransactionManager Implementation Change

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

The implementation of `ThreadTransactionManager` has been modified. It now uses `thread.local` to wrap a `TransactionManager`, rather than inheriting from `TransactionManager`. This change exposes a `manager` attribute, allowing access to the wrapped transaction manager and enabling cross-thread calls.

```python
Changed the implementation of ThreadTransactionManager to be a
  thread.local that wraps a TransactionManager rather than a
  thread.local that inherits from TransactionManager. It now exposes a
  manager attribute that allows access to the wrapped transaction
  manager to allow cross thread calls. See `issue 68
  <https://github.com/zopefoundation/transaction/pull/68>`_.
```

--------------------------------

### Verify Aborted Transaction - Python

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

Verifies that changes made before an abort operation were reverted. This re-queries the user data to confirm the effect of transaction.abort().

```python
>>> session = Session()
>>> john = session.query(User).all()[0]
>>> john.fullname
'John Smith'
```

--------------------------------

### Add Data to SQLAlchemy and ZODB within a Transaction

Source: https://github.com/zopefoundation/transaction/blob/master/docs/sqlalchemy.rst

This snippet demonstrates adding data to both a SQLAlchemy relational database and a ZODB object store. It then commits the transaction, ensuring both operations succeed or fail together.

```python
import transaction
session.add(User(id=1, name='John', fullname='John Smith', password='123'))
root['John'] = 'some data that goes into the object database'

transaction.commit()
```

--------------------------------

### Transaction Extended Info Attribute

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

Introduces the 'extended_info' attribute for transactions, which stores JSON-serializable meta-data. The 'ITransaction' interface now requires keys to be text (unicode) and values to be JSON-serializable. This provides more flexibility for transaction metadata.

```python
import transaction
import json

t = transaction.Transaction()
t.extended_info['user_id'] = 123
t.extended_info['operation'] = 'update_record'

# Values must be JSON-serializable
try:
    json.dumps(t.extended_info)
    print("Extended info is JSON-serializable.")
except TypeError as e:
    print(f"Error: {e}")

# Keys must be text (unicode)
try:
    t.extended_info[123] = 'value' # This will raise a TypeError
except TypeError as e:
    print(f"Error: {e}")
```

--------------------------------

### Transaction Doom Method Error Handling

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

Modifies the behavior of `Transaction.doom` to raise a `ValueError` instead of an `AssertionError` if the transaction is in a non-doomable state. This provides more specific error handling for invalid states.

```python
import transaction

t = transaction.Transaction()
t.doom()

try:
    # Attempt to doom again in a non-doomable state
    t.doom()
except ValueError as e:
    print(f"Caught expected error: {e}")
except Exception as e:
    print(f"Caught unexpected error: {e}")
```

--------------------------------

### Transaction Meta Data Type Enforcement

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

The user and description fields for transactions must now be set with text (unicode) data. Previously, if bytes were provided, they would be decoded as ASCII, which was found to cause hard-to-test bugs. The transaction meta-data field `extended_info` has also been renamed to `extension` for clarity.

```python
The user and description fields must now be set with text (unicode)
  data.  Previously, if bytes were provided, they'd be decoded as
  ASCII.  It was decided that this would lead to bugs that were hard
  to test for.

  Also, the transaction meta-data field, ``extended_info`` has been
  renamed to ``extension``.
```

--------------------------------

### Transaction Exceptions

Source: https://github.com/zopefoundation/transaction/blob/master/docs/api.rst

Details on exceptions raised during transaction operations.

```APIDOC
## Transaction Exceptions

### Description
This section outlines the various exceptions that can be raised during transaction processing.

### Exceptions

- **`TransactionError`**: Base class for transaction-related errors.
- **`TransactionFailedError`**: Raised when a transaction fails to commit or abort.
- **`DoomedTransaction`**: Indicates that a transaction has been marked as doomed and cannot proceed.
- **`TransientError`**: Raised for errors that might be resolved by retrying the operation.
- **`InvalidSavepointRollbackError`**: Raised when attempting an invalid rollback operation on a savepoint.
- **`NoTransaction`**: Raised when an operation is attempted outside of an active transaction.
- **`AlreadyInTransaction`**: Raised when trying to start a new transaction when one is already active.

### Error Handling Example
```python
from transaction import TransactionFailedError, NoTransaction

try:
    # Code that might raise transaction exceptions
    pass
except TransactionFailedError as e:
    print(f"Transaction failed: {e}")
except NoTransaction:
    print("Error: No active transaction found.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```
```

--------------------------------

### Automate transient error handling with transaction.attempts in Python

Source: https://github.com/zopefoundation/transaction/blob/master/CHANGES.rst

Shows how to use the 'transaction.attempts' iterator to automatically retry operations that might fail due to transient errors. The code specifies the maximum number of attempts. This is useful for operations that are prone to temporary failures, like ZODB conflict errors. It requires the 'transaction' module.

```python
import transaction

for attempt in transaction.attempts(5):
    with attempt:
        # do some things that might raise transient errors
        pass
```

--------------------------------

### Stub Data Manager Implementation for Transaction Testing

Source: https://github.com/zopefoundation/transaction/blob/master/docs/doom.rst

This Python code defines a stub DataManager class implementing the IDataManager interface. It's used to simulate data management operations within transaction tests, tracking attribute accesses and providing a method to count total operations.

```python
from transaction.interfaces import IDataManager
from zope.interface import implementer

@implementer(IDataManager)
class DataManager:
    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'
```

--------------------------------

### Recursive Hook Registration During Commit

Source: https://github.com/zopefoundation/transaction/blob/master/docs/hooks.rst

Illustrates a scenario where an after-commit hook can itself register new hooks, which are then executed before the main commit completes. This demonstrates recursive hook registration.

```python
>>> def recurse(status, txn, arg):
...     log.append('rec' + str(arg))
...     if arg:
...         txn.addAfterCommitHook(hook, ('-',))
...         txn.addAfterCommitHook(recurse, (txn, arg-1))

>>> t = begin()
>>> t.addAfterCommitHook(recurse, (t, 3))
>>> commit()
>>> log  #doctest: +NORMALIZE_WHITESPACE
['rec3',
        "True arg '-' kw1 'no_kw1' kw2 'no_kw2'",
'rec2',
        "True arg '-' kw1 'no_kw1' kw2 'no_kw2'",
'rec1',
        "True arg '-' kw1 'no_kw1' kw2 'no_kw2'",
'rec0']
>>> reset_log()
```
Tokens:
Raw