VCS Repository¶
dx.Repository wraps panproto's filesystem-backed schema repository:
a content-addressed object store, refs, a staging index, and reflog
entries, all stored under .panproto/ in a working directory.
Initialising a repository¶
import didactic.api as dx
repo = dx.Repository.init("/path/to/my-repo")
print(repo.working_dir)
print(repo.head()) # None for a freshly initialised repo
Staging and committing¶
Repository.add accepts two shapes. The simplest is to pass a
dx.Model subclass directly. Didactic synthesises a schema with one
vertex for the Model and one deterministic ModelName.field_name
vertex for every declared field. Each field vertex records its didactic
sort, structural kind, requiredness, usage mode, axioms, and nominal or
structural identity; the edge from the Model records the serialized field
name:
import didactic.api as dx
class User(dx.Model):
id: str
email: str
repo = dx.Repository.init("/path/to/repo")
repo.add(User)
commit_id = repo.commit("initial user schema", author="Ada <ada@example.org>")
You can also stage a panproto Schema you constructed yourself:
import panproto
proto = panproto.get_builtin_protocol("openapi")
builder = proto.schema()
builder.vertex("ping", "string")
schema = builder.build()
repo.add(schema)
repo.commit("openapi ping schema", author="Ada <ada@example.org>")
Staging data against a persisted schema¶
Repository.add_data normally validates a dataset against the staged schema,
or HEAD's schema when no schema is staged. Pass schema_id to reuse an exact
persisted schema without changing either of those schema pointers:
repo.add_data(
"run-config.json",
key="configuration",
schema_id=config_schema_id,
)
repo.add_data("run-record.json", key="record")
repo.commit("record run", author="Ada <ada@example.org>")
The committed configuration dataset records config_schema_id; the record
dataset records the staged or HEAD schema id. This permits one commit to carry
datasets governed by distinct persisted schemas while leaving field blame on
the HEAD schema stable.
Reading committed data¶
Repository.data_at returns the canonical Panproto MessagePack bytes for each
dataset at a revision. Use Repository.decoded_data_at when the caller needs
ordinary JSON-like records instead:
datasets = repo.decoded_data_at("release-candidate")
for dataset in datasets:
print(dataset.key, dataset.schema_id, dataset.record_count)
users = [User.model_validate(record) for record in dataset.records]
The result retains each dataset's key, persisted schema id, and record count. Dataset order and record order match the commit. Maps, lists, strings, booleans, nulls, integers, and finite floats are decoded to their ordinary Python JSON shapes; validation against a current Model remains an explicit caller decision.
Both accessors accept HEAD, a branch, a tag, a full commit id, or an accepted
commit-id prefix. They traverse history without checking out the revision or
changing HEAD, the working tree, or the staged schema. Missing or malformed
refs, absent or tampered objects, and malformed canonical data raise Panproto's
typed VcsError. The raw CommittedDataset.data bytes remain available for
callers that need the canonical representation.
Blaming a field¶
blame_field attributes one declared field without exposing panproto's
repository handle:
blame = repo.blame_field("HEAD", User, "email")
print(blame.commit_id)
print(blame.author)
print(blame.message)
The walk follows first-parent history. A committed schema migration that maps an old field vertex to a renamed one preserves the original field's attribution. Fields added without a migration preimage are attributed to the adding commit.
Branches and refs¶
repo.create_branch("feature", commit_id)
repo.checkout_branch("feature")
# resolve any ref expression to a commit id
cid = repo.resolve_ref("HEAD")
See also¶
- Repository reference for the full API.