CommitStore

class dsviper.CommitStore

Bases: object

A high-level application class used to implement the store, dispatch, undo/redo and notification concepts inspired by the redux approach.

The implementation uses a Commit database for the persistence layer.

A dispatch raises before it runs: without a database, or on an argument that does not convert to the type it is written as. What fails once it runs - the callable, a write, the commit - does not raise: nothing is committed, the error goes to the notifier’s notify_dispatch_error, and it is lost when no notifier is set.

attachment_getting() → AttachmentGetting

Return the AttachmentGetting interface of the current state or raise.

Like state(), it reads the state current when it was asked for.

can_redo() → bool

Return True if the store can redo.

can_undo() → bool

Return True if the store can undo.

clear_undo_redo() → None

Empty the undo and redo stacks, anchored on nothing.

Unlike reset_undo_redo, it needs no state and never raises.

close() → None

Let go of the database and the state this store holds.

Whether the database then closes depends on who else holds it. The store drops its reference, and the database closes when that was the last one - which it is when you handed use() a database you kept no name for. Keep your own reference to decide yourself.

After this, has_database() and has_state() are False, and a dispatch raises.

commit_mutations(label: str, commit_mutable_state: CommitMutableState) → None

Append the opcodes commit_mutable_state recorded as a new commit under label, move onto it and notify.

database() → CommitDatabase

Return the database or raise.

definitions() → DefinitionsConst

Return the Definitions every value in the database is typed by.

It is a SNAPSHOT: extending the database 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.

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. The store moves onto the parent of commit_id and clears its undo and redo stacks.

disable_commit(commit_id: ValueCommitId) → None

Append a commit hiding commit_id and move onto it.

It sits on top of the current commit.

Nothing is removed: the evaluator skips the hidden commit from here on. The undo stack is left alone; dispatch_enable_commit is the undoable form.

dispatch(label: str, callable: Callable, *args) → Any

Run callable against a fresh mutable state and commit what it wrote.

The commit carries label.

args are passed on to callable after the AttachmentMutating interface. Returns what callable returns, or None when it raises: nothing is committed, and the error reaches the notifier instead.

dispatch_diff(label: str, attachment: Attachment, key: ValueKey, value: _InputValues, *, recursive: bool = False) → None

Commit under label a diff against what attachment holds at key.

Only what differs from value is written, and an absent document is written whole. A set or map field is diffed entry by entry; a structure field is written whole, or walked field by field when recursive is True.

dispatch_enable_commit(commit_id: ValueCommitId, enabled: bool) → None

Commit the hiding of commit_id, or its unhiding when enabled is True, and move onto the new commit.

dispatch_set(label: str, attachment: Attachment, key: ValueKey, value: _InputValues) → None

Commit under label the writing of value at key in attachment.

dispatch_update(label: str, attachment: Attachment, key: ValueKey, path: PathConst, value: _InputValues) → None

Commit under label the writing of value at path, inside the document attachment holds at key.

enable_commit(commit_id: ValueCommitId) → None

Append a commit unhiding commit_id and move onto it.

It sits on top of the current commit. The undo stack is left alone; dispatch_enable_commit is the undoable form.

extend_definitions(definitions: DefinitionsConst) → DefinitionsExtendInfo

Add every type and attachment of definitions the database does not already hold, then notify.

forward() → None

Move onto the head reached from the current commit by following its single child at each step.

has_database() → bool

Return True if a database is in use.

has_state() → bool

Return True if a state has been built.

merge_commit(commit_id: ValueCommitId) → None

Append a commit joining the current head and commit_id, and move onto it.

The commit records the pair; nothing is composed here. At reconstruction commit_id’s mutations land last, so on a path both wrote its value wins and the other is dropped; nothing is signalled. The undo stack is left alone. CommitMergeAnalyzer reconstructs, after the fact, what a merge did not keep.

mutable_state() → CommitMutableState

Return a new mutable state for the current state.

notifier() → CommitStoreNotifying | None

Return the notifier or None.

notify_database_did_close() → None

Send a notification to inform that the database was closed.

notify_database_did_open() → None

Send a notification to inform that the database was opened.

notify_database_did_reset() → None

Send a notification to inform that the database did reset.

notify_database_will_reset() → None

Send a notification to inform that the database will reset.

notify_definitions_did_change() → None

Send a notification to inform that the definitions has changed.

notify_dispatch_error(error: Error) → None

Send a notification to inform that an error occurred during a dispatch.

notify_reset_database() → None

Send a notification to reset the database.

notify_state_did_change() → None

Send a notification to inform that the current state has changed.

notify_stop_live() → None

Send a notification to stop the live mode.

redo() → None

Redo the last undone dispatch.

A commit is appended that hides the hiding one.

The new commit is labelled Redo [<label of the target>].

reduce_heads() → None

Reduce the database to a single head, starting from last_commit_id.

The other heads are reduced one at a time, and the store moves onto the result.

On a path both heads wrote, the later in linearisation order wins and the other is dropped; nothing is signalled. CommitMergeAnalyzer reconstructs, after the fact, what a merge did not keep.

reset() → 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.

reset_undo_redo() → None

Empty the undo and redo stacks and anchor them on the current commit.

Raises when the store has no state, where clear_undo_redo does not.

set_database(commit_database: CommitDatabase) → None

Take commit_database as the store’s database, without building a state or notifying - use() does both.

set_notifier(notifier: CommitStoreNotifying) → None

Set the notifier.

set_state(commit_state: CommitState) → None

Take commit_state as the store’s current state, without notifying.

state() → CommitState | None

Return the current state, or None when the store holds none.

It holds none before use(commit_database) and after close(). It is a snapshot: a later dispatch, undo or redo builds a new state, and the one held keeps answering what it held. has_state() answers whether there is one.

undo() → None

Undo the last dispatch by appending a commit that hides it.

Not a rollback: nothing is removed, the history keeps growing forward, and the new commit is labelled Undo [<label of the target>].

undo_stack_ids() → tuple[list[ValueCommitId], int | None]

Return (commit_ids, current): the commits made since the base, oldest first, and the index in commit_ids of the one the store is on, or None when it is back on the base with nothing to undo. The ids after current are what redo reapplies.

use(commit_database: CommitDatabase) → None

Take commit_database, build the state of its last commit - or the initial one if it holds none - and notify.

use_commit(commit_id: ValueCommitId) → None

Rebuild the current state from the commit commit_id names.

Nothing is notified and the undo stack is left alone: an undo after it still undoes the last dispatch, and writes that undo on the commit used here - so moving back to an earlier commit, then undoing, opens a second head. reset_undo_redo() anchors the stacks on the commit used.