Case management#

hash_case(case)#

Return a stable content identifier for a case.

open_ledger(case_path, *, current=None, create=True, ts=None)#

Open a case ledger and reconcile the current case state.

Parameters:

  • case_path -- Path to the tracked case file.

  • current -- Current parsed case. None loads it from case_path.

  • create -- Create initial history for an untracked case.

  • ts -- Optional timestamp for a new entry.

Returns:

A read-only ledger handle.

read_ledger(case_path)#

Open the available version history for a case without changing it.

Parameters:

case_path -- Tracked case file. The function reads its adjacent .gpflog history file and does not read or modify the case.

Returns:

A read-only handle that supports history listing, checkout, and verification. A case without stored history returns an empty handle.

track_tool_write(case_path, after_case, *, op, params, ts=None, version=None, track=True)#

Write a case and record the operation in its sidecar ledger.

Parameters:

  • case_path -- Destination case path.

  • after_case -- Case state to write.

  • op -- Operation name for the ledger entry.

  • params -- Operation parameters to store.

  • ts -- Optional timestamp for the new entry.

  • version -- Output file revision.

  • track -- Record history when true.

Returns:

A read-only history handle, or None when tracking is disabled.

class Ledger(path)#

Read and update one case's version history.

The writable handle records case changes, reconciles external file changes, and compacts stored history. Open it through writing_ledger so updates remain coordinated with other writers.

current#

The case on disk that this handle reconciled against, or None when the file is absent or unparsable. track_tool_write() records the state as the before of the op it is about to write.

reconcile(current, *, ts=None)#

Record an external case change when it differs from stored history.

Parameters:

  • current -- Current case state.

  • ts -- Optional timestamp for the new ledger entry.

Returns:

True if the method appended an entry.

record(op, params, before, after, *, ts=None)#

Record a labeled case operation when it changes the case.

before and after contain the customer case states. op and params identify the operation. The method returns true when it records a new version.

compact(*, ts=None)#

Reduce stored history while preserving restorable versions.

Parameters:

ts -- Optional timestamp for the maintenance operation.

Returns:

The number of removed history records.

class ReadLedger(path)#

Read and verify a case's version history.

Use history to list versions, checkout to return a selected case, head_case to return the latest case, and verify to check the stored history. Open a read-only handle with read_ledger.

torn_at#

Byte length of the parsable prefix when a crash left a partial final line, otherwise None. _emit() truncates the partial bytes under the commit lock.

classmethod from_bytes(path, data)#

Decode captured history without reading its source again.

property head_hash#

Return the case hash at the ledger head.

property head_seq#

Return the sequence number at the ledger head.

head_case()#

Return the case state at the ledger head.

checkout(ref, *, allow_skew=False)#

Restore a recorded case version.

Parameters:

  • ref -- Sequence number, decimal sequence string, or hash prefix.

  • allow_skew -- Drop unknown fields and record findings for them.

Returns:

The restored case with its original source-format defaults.

Raises:

  • KeyError -- If the reference is absent or ambiguous.

  • DiffConflictError -- If stored history conflicts with a saved state.

  • SchemaSkewError -- If the snapshot contains unknown fields and allow_skew is false.

history()#

Return one row per stored version.

Each row contains the sequence, timestamp, operation, short content identifier, and a one-line summary.

verify()#

Verify the stored history and return its status.

class VerifyReport(chain_ok, replay_ok, errors=<factory>, notes=<factory>)#

Report whether stored case history passed verification.

chain_ok reports record integrity. replay_ok reports whether the installed version can reproduce the stored case states. errors lists integrity failures. notes lists compatibility or reproduction issues. Boolean conversion returns chain_ok.

summary()#

Return a one-line verification summary.

export_bundle(project_path, out_zip)#

Export a saved project and its declared resources as one ZIP snapshot.

The application can export its active session with prepare_export(). Both entry points use the same resource capture and publication plan.

import_bundle(zip_path, dest_dir)#

Restore a verified snapshot and return its fully loaded project session.

write_project(path, model, *, name, history=None)#

Write a project manifest that names one network file and its history.

A project file is what export_bundle() reads, so this is the entry point that turns a case on disk into something a colleague can receive.

Parameters:

  • path -- Project TOML file to write.

  • model -- Network file, named relative to the project file.

  • name -- Project name.

  • history -- Version ledger of the network, when the case is tracked.

Returns:

The path written.

Examples

>>> project = write_project(
...     "project.toml", "case.rawx", name="Grid",
...     history="case.rawx.gpflog")