Skip to content

abczarr.abc.transactions

Transactions over a store: batch a set of writes into one commit.

A transaction is a view of a store, not a new kind of object. Its store property is an ordinary Store whose reads see the transaction's own pending writes. Nothing is applied to the underlying store until commit is called.

store.transaction() opens a transaction. It is best used as a context manager, since a context manager commits on a clean exit and aborts if the block raises:

with store.transaction(atomic=False) as txn:
    txn.store.set("a", b"1")
    txn.store.set("b", b"2")
# both writes land together here

A backend with real transactions, such as tensorstore or an Icechunk session, returns a native transaction from store.transaction(). Every other store gets BufferedTransaction, which buffers writes and flushes them on commit. This buffered transaction is never atomic, because a failure part-way through the flush leaves a partial result, so it is only offered for transaction(atomic=False). An atomic transaction is never built this way. A store with no native support for one raises rather than pretend to provide it.

Classes

Transaction

Bases: ABC

A batch of store operations that commit or abort together.

Attributes

atomic class-attribute instance-attribute 
atomic: bool = False
store abstractmethod property 
store: Store

A store whose reads see this transaction's pending writes.

Methods:

commit abstractmethod 
commit(message: str | None = None) -> None

Apply the batch.

Parameters:

Name Type Description Default
message str

Recorded by a backend that keeps commit messages, such as Icechunk. Other backends ignore it.

 None

Raises:

Type Description
[TransactionConflict][TransactionConflict]

If the store moved on underneath this transaction.
abort abstractmethod 
abort() -> None

Discard the batch without applying it.

__enter__ 
__enter__() -> Transaction
__exit__ 
__exit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) -> None

BufferedTransaction 

BufferedTransaction(parent: Store)

Bases: Transaction

A non-atomic transaction: buffer writes, flush them on commit.

Reads through store see the buffered writes and deletes. commit then applies them to the parent store one at a time, so a failure part-way through leaves a partial result. This transaction is useful for batching many small writes on a backend with no native transaction support, but it is never atomic. atomic is always False.

Attributes

atomic class-attribute instance-attribute 
atomic = False
store property 
store: Store

Methods:

commit 
commit(message: str | None = None) -> None
abort 
abort() -> None

AsyncTransaction

Bases: ABC

The coroutine twin of Transaction.

Attributes

atomic class-attribute instance-attribute 
atomic: bool = False
store abstractmethod property 
store: AsyncStore

A store whose reads see this transaction's pending writes.

Methods:

commit abstractmethod async 
commit(message: str | None = None) -> None

Apply the batch.

See Transaction.commit.

abort abstractmethod async 
abort() -> None

Discard the batch.

__aenter__ async 
__aenter__() -> AsyncTransaction
__aexit__ async 
__aexit__(exc_type: Type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None) -> None

AsyncBufferedTransaction 

AsyncBufferedTransaction(parent: AsyncStore)

Bases: AsyncTransaction

The async, non-atomic buffered transaction.

See BufferedTransaction.

Attributes

atomic class-attribute instance-attribute 
atomic = False
store property 
store: AsyncStore

Methods:

commit async 
commit(message: str | None = None) -> None
abort async 
abort() -> None