Python API reference¶
The API is the protocolith.core package. For a worked example see the Python API guide.
Functions¶
| Function | Returns | Notes |
|---|---|---|
freeze(store, protocol, *, supersedes=None, clock=None) |
the new entry (dict) | protocol must be an object |
record(store, body, *, clock=None) |
the new entry | |
deviation(store, body, *, clock=None) |
the new entry | |
verify(store, expect_head=None) |
Verdict |
expect_head="SEQ:HASH" adds the anchored-head check; never raises for a bad ledger; raises EnvError (NO_LEDGER) for a missing one |
entries(store) |
list of entries | raises VerificationFailed if the ledger does not verify |
log(store, *, protocol=None, type=None, status=None, tail=None) |
list of entries | filtered entries; unknown protocol is UNKNOWN_PROTOCOL |
show(store, seq) |
{"entry", "protocol", "points_at", "pointed_by"} |
unknown seq is DANGLING_REF |
summary(store, protocol=None) |
dict (see spec 5.1) | does not raise for a ledger that fails verification: ok is false and problems lists why |
init(store) |
{"created", "path"} |
creates an empty ledger; harmless to repeat |
capture(files=(), *, env=False, base=None) |
{"environment", "inputs"} |
hashes files inside base (default the working directory); BAD_PATH otherwise |
schema_for(name) |
JSON Schema dict | freeze, record, deviation, issue or entry |
head(store) |
{"count", "hash", "seq"} |
hash and seq are None for an empty ledger |
issue(store, seq, *, out=None, clock=None) |
{"card", "entry", "json_path", "svg_path"} |
|
repair_truncate_partial_tail(store) |
bytes removed | see repair |
scan(data, card_hasher=None) |
(Verdict, Verifier) |
verify bytes without a store |
encode(value), decode(raw), sha256_hex(value) |
bytes, value, str | canonical JSON |
resolve_store(path) |
Store |
explicit path, then PROTOCOLITH_STORE, then .protocolith |
Verdict has ok, count, head_seq, head_hash, violations, codes and to_dict().
Atlas¶
from protocolith import core
page = core.build_atlas(store=".protocolith") # bytes of one self-contained HTML file
page = core.build_atlas(cards=["docs/evidence_cards"], title="My atlas", max_rows=5000)
build_atlas(*, store=None, cards=(), title=..., i18n_dir=None, default_lang="en", max_rows=None) returns the page. With
neither store nor cards it uses a local ledger, else docs/evidence_cards (NO_SOURCE if there is none).
protocolith.core.atlas.build_atlas_result returns an AtlasResult (html, ok, total, shown, skipped,
warnings, ledger); ok is false when the ledger does not verify. write_atlas(page, out) writes it atomically.
The output is deterministic: same input, same bytes.
Errors¶
All errors derive from ProtocolithError and carry code, message and violations.
| Class | CLI exit code | Meaning |
|---|---|---|
InputError |
2 | bad input or a rejected operation; nothing was written |
VerificationFailed |
1 | the stored ledger does not verify |
EnvError |
3 | I/O or environment problem (NO_LEDGER, LOCK_TIMEOUT, IO_ERROR) |
CanonError |
invalid JSON input for decode or encode |
try:
core.freeze(store, protocol)
except core.InputError as exc:
print(exc.code, exc.message) # e.g. DUPLICATE_FREEZE
The operations are the same as the CLI commands and the MCP tools.