architxt.bucket.zodb

Classes

ZODBTreeBucket([storage_path, uri, ...])

A persistent, scalable container for Tree objects backed by ZODB and RelStorage using SQLite.

class architxt.bucket.zodb.ZODBTreeBucket(storage_path=None, uri=None, bucket_name='architxt', read_only=False)

Bases: TreeBucket

A persistent, scalable container for Tree objects backed by ZODB and RelStorage using SQLite.

This container uses ZODB’s OOBTree internally with Tree OIDs (UUIDs) as keys. The OIDs are stored as raw bytes to optimize storage space. This also enables fast key comparisons as UUID objects do not need to be created during lookups.

Note

UUIDs are stored as bytes rather than integers, because ZODB only supports integers up to 64 bits, while UUIDs require 128 bits.

If no storage is specified, the bucket use a temporary database that is automatically deleted upon closing.

The bucket is serializable so it can be passed to a subprocess. However, when a temporary database is used, the original bucket remains responsible for cleanup. This means the original bucket must stay open for the subprocess to access the database safely.

>>> from architxt.bucket.zodb import ZODBTreeBucket
>>> from architxt.tree import Tree

>>> bucket = ZODBTreeBucket()
>>> tree = Tree.fromstring('(S (NP Alice) (VP (VB like) (NNS apples)))')
>>> tree.label
'S'

>>> with bucket.transaction():
...     bucket.add(tree) # Add the tree to the bucket
>>> len(bucket)
1
>>> tree in bucket
True

>>> with bucket.transaction():
...     tree.label = 'ROOT' # Modify the tree within a transaction
>>> tree.label
'ROOT'
>>> bucket[tree.oid].label
'ROOT'

>>> with bucket.transaction():
...     tree.label = 'S'
...     raise ValueError("rollback")  # Transaction are rolled back on exception
Traceback (most recent call last):
    ...
ValueError: rollback

>>> tree.label
'ROOT'
>>> with bucket.transaction():
...     bucket.discard(tree)
>>> len(bucket)
0
>>> tree in bucket
False

>>> bucket.close()

add(tree)

Add a single Tree to the bucket.

Return type:

None

clear()

Remove all Tree objects from the bucket.

Return type:

None

close()

Close the database connection and release associated resources.

This will: - Abort any uncommitted transaction. - Close the active database connection. - Clean up temporary storage if one was created.

Return type:

None

discard(tree)

Remove a Tree from the bucket if it exists.

Return type:

None

get_persistent_ref(tree)

Get a persistent reference for a given tree.

Parameters:

tree (Tree) – The tree to get the persistent reference for.

Return type:

Any

Returns:

The persistent reference of the tree for this bucket.

Raises:

KeyError – If the tree is not stored in the bucket.

oids()

Yield the object IDs (OIDs) of all trees stored in the bucket.

Return type:

Generator[TreeOID, None, None]

resolve_ref(ref)

Resolve a persistent_ref back to a live Tree instance.

Parameters:

ref (Any) – The value returned by Tree.persistent_ref().

Return type:

Tree

Returns:

The tree corresponding to the given persistent reference.

Raises:

KeyError – If the tree is not found in the bucket.

sync()

Synchronize the in-memory state of this bucket with its underlying storage.

It clears the local cache and refresh the connection. This can be used to avoid connection timeout in long-running process.

Return type:

None

transaction()

Return a context manager for managing a transaction.

Upon exiting the context, the transaction is automatically committed. If an exception occurs within the context, the transaction is rolled back.

Transactions are reentrant.

Return type:

Generator[None, None, None]