CommitDatabasing

class dsviper.CommitDatabasing

Bases: object

Abstracts the persistence layer behind a Commit database.

Writes here need NO transaction, unlike Databasing, where every write requires one already open. begin_transaction is available for batching and is never a precondition.

Note: Not directly instantiable.

begin_transaction(mode: str | None = None) → None

Begin a transaction in mode ‘Deferred’ (the default), ‘Immediate’ or ‘Exclusive’.

Another spelling raises.

Transactions do not nest: calling this while in_transaction() is True raises, and the transaction already open is untouched.

blob(blob_id: ValueBlobId) → ValueBlob | None

Return the bytes of the blob blob_id names, or None if it is not held here.

Raises past 2 GB, where the bytes cannot be handed over in one piece. Ask blob_info(blob_id).chunked() first, and read such a blob with read_blob.

A blob reserved by create_zero_blob raises until freeze_blob seals it; blob_info answers None for it meanwhile.

blob_datas(blob_ids: set[ValueBlobId]) → list[BlobData]

Return one BlobData per blob_id of blob_ids this source holds - the bytes together with their layout.

blob_ids() → set[ValueBlobId]

Return the set of blob_id of every sealed blob.

A blob create_zero_blob reserved joins it once freeze_blob seals it.

blob_info(blob_id: ValueBlobId) → BlobInfo | None

Return the BlobInfo for blob_id, or None if there is no such blob.

It gives the layout, the size, whether the blob is chunked, and the rowid that reaches it. A blob create_zero_blob reserved answers None until freeze_blob seals it.

blob_infos(blob_ids: set[ValueBlobId]) → list[BlobInfo]

Return one BlobInfo per blob_id of blob_ids this source holds.

An unknown blob_id is left out, so the list may be shorter than blob_ids.

blob_statistics() → BlobStatistics

Return the statistics for blobs.

blob_stream_close(stream_id: ValueUUId, blob_id: ValueBlobId) → None

Close the stream stream_id names, storing what it collected under blob_id.

blob_stream_create(blob_layout: BlobLayout, size: int) → ValueUUId

Open a stream for a blob of size bytes laid out by blob_layout, and return the uuid naming it.

blob_stream_delete(stream_id: ValueUUId) → None

Drop the stream stream_id names, discarding what it collected.

blob_stream_write(stream_id: ValueUUId, blob: ValueBlob, offset: int) → None

Write blob into the stream stream_id names, at offset.

children_commit_ids(commit_id: ValueCommitId) → set[ValueCommitId]

Return the set of commit_id for the children of the commit.

close() → None

Close the connection.

codec_name() → str

Return the name of the codec.

commit() → None

Commit the transaction, so what it wrote stays.

Raises when no transaction is open.

commit_data(commit_id: ValueCommitId) → CommitData | None

Return the CommitData commit_id names - its header and its encoded opcodes - or None if this source does not hold it.

commit_datas(commit_ids: set[ValueCommitId] | None = None) → list[CommitData]

Return one CommitData per commit_id of commit_ids, or all of them when commit_ids is None.

commit_exists(commit_id: ValueCommitId) → bool

Return True if this source holds the commit commit_id names.

commit_header(commit_id: ValueCommitId) → CommitHeader

Return the header of the commit associated with the commit_id.

commit_ids() → set[ValueCommitId]

Return the set of commit_ids.

create_blob(blob_id: ValueBlobId, blob_layout: BlobLayout, blob: ValueBlob) → bool

Store blob under blob_id and blob_layout.

create_blobs(blob_datas: list[BlobData]) → set[ValueBlobId]

Store every BlobData of blob_datas, and return the blob_ids it added.

One the store already holds is left as it is and stays out of the answer, so an empty set means every one of them was there already.

create_commit_data(commit_data: CommitData) → bool

Store commit_data, and return True if it was not already there.

create_zero_blob(blob_id: ValueBlobId, blob_layout: BlobLayout, size: int) → bool

Reserve size zeroed bytes under blob_id and blob_layout.

The blob is filled later. Returns True if it was created.

Until freeze_blob seals it, blob_ids leaves it out, blob_info answers None, and blob and read_blob raise.

data_version() → int

Return the counter another connection’s commit bumps.

An unchanged value means nothing was committed elsewhere since the last read.

definitions() → DefinitionsConst

Return the Definitions every value in this source is typed by.

It is a SNAPSHOT: extending the source afterwards does not show through the handle you hold, so ask again. A view obtained from Definitions.const() is live instead - same class, opposite liveness.

definitions_hexdigest() → str

Return the SHA1 of the definitions, as a hex string.

delete_commit(commit_id: ValueCommitId) → None

Delete the commit commit_id names.

Breaks the append-only invariant every other reader relies on, and only makes sense on a head: deleting any other commit orphans its descendants. Kept for rewinding an interactive demonstration, not for storage management.

documentation() → str

Return the free text stored with the database at create(). One made without any answers ‘not documented.’, one made in memory answers ‘In Memory’ - both are placeholders written in at create(), not substituted on read.

extend_definitions(other: DefinitionsConst) → DefinitionsExtendInfo

Add every type and attachment of other that this source does not already hold.

first_commit_id() → ValueCommitId | None

Return the commit_id of the first commit or None.

First in creation order, which is the root of the DAG CommitNode.build walks.

freeze_blob(blob_id: ValueBlobId) → bool

Seal the blob blob_id names against further writes, and return True if it was still open.

head_commit_ids() → set[ValueCommitId]

Return the set of commit_id for the heads.

in_transaction() → bool

Return True if a transaction is running.

is_closed() → bool

Return True if the connection to the database is closed.

last_commit_id() → ValueCommitId | None

Return the commit_id of the last commit or None.

Last in creation order: the one a new commit follows, and the one CommitStore.use resumes from.

nephew_commit_ids(commit_id: ValueCommitId) → set[ValueCommitId]

Return the set of commit_id for the nephew of the commit.

path() → str

Return the file path behind this source.

A database made in memory answers ‘InMemory’ rather than a path, and that exact string is how the runtime recognises one, so no file may take it: creating or opening a file of that path raises. Over a socket the answer is whatever the server answers for its own database.

read_blob(blob_id: ValueBlobId, size: int, offset: int) → ValueBlob

Return size bytes of the blob blob_id names, starting at offset.

The read side of blob_stream_create, blob_stream_write and blob_stream_close, and the only way to read a blob past 2 GB, which blob() refuses.

reset_commits() → None

Remove all commits except the first one.

Breaks the append-only invariant every other reader relies on. Kept for replaying an interactive demonstration from a known baseline, not for storage management.

rollback() → None

Roll back the transaction, so what it wrote is dropped.

Raises when no transaction is open.

sync_data(commit_ids: set[ValueCommitId]) → CommitSyncData

Return what a synchronizer needs to carry the commits of commit_ids.

The commits, the codec their opcodes were encoded with, and the digest of the definitions. The blobs they reference are not included: they travel apart, through blob_datas.

unknown_blob_ids(blob_ids: set[ValueBlobId]) → set[ValueBlobId]

Return a set of blob_id for all unknown blob_id found in blob_ids.

uuid() → ValueUUId

Return the uuid identifying the database behind this source.

write_blob(blob_id: ValueBlobId, blob: ValueBlob, offset: int) → None

Write the bytes of blob into the stored blob blob_id names, at offset.