Repository¶
Repository.add(Model) commits a field-addressable schema. The Model is an
object vertex, and every declared field is a field vertex named
ModelName.field_name. A labelled edge records the serialized field name;
constraints record the didactic sort, structural kind, requiredness, usage
mode, and axioms. The schema's nominal map records FieldSpec.nominal
explicitly for every field.
This representation makes field history available without exposing panproto's repository handle:
import didactic.api as dx
class RunSpec(dx.Model):
run_id: str = dx.field(nominal=True)
seed: int
repo = dx.Repository.open("experiment-schema")
blame = repo.blame_field("main", RunSpec, "run_id")
print(blame.commit_id, blame.author, blame.message)
Blame walks first-parent history. When a committed schema migration maps an old field vertex to a renamed vertex, attribution follows that mapping to the commit that introduced the original field.
didactic.api.Repository ¶
Filesystem-backed panproto repository.
Wraps a panproto.Repository. Construction is
via the Repository.init and
Repository.open class methods rather
than the bare constructor; the constructor accepts an already-open
handle and is mostly for internal use.
| PARAMETER | DESCRIPTION |
|---|---|
inner
|
An already-constructed
TYPE:
|
Notes
The wrapper delegates almost every operation to the inner panproto handle. The reason it exists, rather than re-exporting panproto's type, is to keep didactic's public API independent of panproto's Python binding details (attribute names, argument keywords, etc.) as panproto evolves.
Examples:
>>> import didactic.api as dx
>>> repo = dx.Repository.init("/tmp/my-repo")
>>> repo.head() is None
True
init
classmethod
¶
init(path: str | PathLike[str]) -> Repository
Initialise a new repository at path.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Directory in which to create the
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Repository
|
A handle to the newly initialised repository. |
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If a repository already exists at |
open
classmethod
¶
open(path: str | PathLike[str]) -> Repository
Open an existing repository at path.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Directory containing a
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Repository
|
A handle to the existing repository. |
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If no repository exists at |
head ¶
Resolve HEAD to a commit object id.
| RETURNS | DESCRIPTION |
|---|---|
str or None
|
The commit id, or |
head_state ¶
Describe the current HEAD state.
| RETURNS | DESCRIPTION |
|---|---|
str
|
A descriptor string from panproto. For a freshly
initialised repository this is typically
|
list_branches ¶
Return the list of branches.
| RETURNS | DESCRIPTION |
|---|---|
list of (str, str)
|
One |
list_tags ¶
Return the list of tags.
| RETURNS | DESCRIPTION |
|---|---|
list of (str, str)
|
One |
log ¶
List commits reachable from HEAD, newest first.
| RETURNS | DESCRIPTION |
|---|---|
list of dict
|
One commit-record dict per commit, in newest-first order. The exact shape is panproto-defined; callers that depend on specific keys should consult panproto's documentation. |
resolve_ref ¶
Resolve a ref expression to a commit id.
| PARAMETER | DESCRIPTION |
|---|---|
ref
|
A branch name, tag name, or commit-id prefix.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
str
|
The full commit id. |
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If |
data_at ¶
data_at(ref: str) -> list[CommittedDataset]
Read the datasets committed at ref.
A read-only accessor for committed content: it resolves
ref, loads the datasets recorded at that revision, and
returns their canonical Panproto encodings, leaving HEAD and the
working tree untouched. This is the data-side counterpart to
panproto's committed-schema lookup, so a downstream can identify
and migrate the checked record set at an arbitrary revision
without checking it out.
| PARAMETER | DESCRIPTION |
|---|---|
ref
|
A branch name, tag name,
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list of CommittedDataset
|
One entry per dataset committed at |
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If |
decoded_data_at ¶
decoded_data_at(ref: str) -> list[DecodedCommittedDataset]
Read and decode the datasets committed at ref.
This is the decoded counterpart to data_at. Panproto resolves the ref, verifies and loads each stored dataset, and decodes its canonical MessagePack records. The operation is read-only: it does not check out the revision or change HEAD, the working tree, or the staged schema.
| PARAMETER | DESCRIPTION |
|---|---|
ref
|
A branch name, tag name,
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list of DecodedCommittedDataset
|
One entry per dataset committed at |
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If |
blame_field ¶
Find the commit that introduced a declared Model field.
| PARAMETER | DESCRIPTION |
|---|---|
ref
|
Branch name, tag,
TYPE:
|
model
|
Model class whose schema was committed.
TYPE:
|
field
|
Python name of one of
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Blame
|
Attribution for the commit that introduced the field vertex. |
| RAISES | DESCRIPTION |
|---|---|
KeyError
|
If |
VcsError
|
If |
add ¶
Stage target for the next commit.
| PARAMETER | DESCRIPTION |
|---|---|
target
|
Either a
TYPE:
|
Notes
Staging is additive: subsequent calls accumulate in the index until a commit flushes it.
add_data ¶
add_data(
path: str | PathLike[str],
*,
key: str | None = None,
schema_id: str | None = None,
skip_verify: bool = False,
) -> None
Stage a data file for the next commit.
Reads the file at path, parses and validates its records, and
stages their canonical Panproto instances as a dataset bound to
the staged schema, or to HEAD's schema when no schema is staged.
The staged data is flushed by the next
commit and is then readable at
that revision through
data_at. This is the
write-side counterpart to data_at.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Filesystem path to the JSON data file to stage. The file is read immediately; its records are checked against the active schema and captured in the repository's canonical encoding.
TYPE:
|
key
|
Identifier to record for the dataset, surfaced as
CommittedDataset.key. A
downstream that versions one record per dataset passes its
own key (for example an AT-URI) so it can map the committed
dataset back. When omitted, the dataset's key defaults to
TYPE:
|
schema_id
|
Object id of a persisted schema to use when parsing, lifting, and validating this dataset. Supplying an id does not change HEAD or the staged schema. When omitted, panproto uses the staged schema, or HEAD's schema when no schema is staged.
TYPE:
|
skip_verify
|
If
TYPE:
|
Notes
Staging is additive: like add, repeated calls accumulate in the index until a commit flushes it.
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If |
commit ¶
Create a commit with message and author.
| PARAMETER | DESCRIPTION |
|---|---|
message
|
The commit message.
TYPE:
|
author
|
The commit author. Free-form string; the conventional
shape is
TYPE:
|
skip_verify
|
If
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
str
|
The new commit's object id. |
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If nothing is staged or panproto rejects the commit. |
create_branch ¶
Create a new branch name pointing at commit_id.
create_tag ¶
Create a lightweight tag name pointing at target.
A lightweight tag is a named pointer to a commit, carrying no message or tagger. Use create_annotated_tag for a tag object that records who tagged what, when, and why.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
The tag name.
TYPE:
|
target
|
The commit id to tag, as returned by commit, head, or resolve_ref.
TYPE:
|
force
|
If
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If a tag |
create_annotated_tag ¶
Create an annotated tag name pointing at target.
An annotated tag is a first-class object recording a tagger,
a timestamp, and a message, unlike a lightweight tag which is
only a named pointer. The tag ref resolves to the annotated-tag
object rather than to target directly.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
The tag name.
TYPE:
|
target
|
The commit id to tag (see create_tag for the accepted forms).
TYPE:
|
message
|
The tag message.
TYPE:
|
tagger
|
The tagger identity. Free-form string; the conventional
shape is
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
str
|
Object id of the created annotated-tag object, the id the tag ref resolves to. |
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If a tag |
delete_tag ¶
Delete the tag name.
| PARAMETER | DESCRIPTION |
|---|---|
name
|
The tag to delete.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
VcsError
|
If no tag |
didactic.api.CommittedDataset
dataclass
¶
A dataset as recorded at a committed revision.
Returned by data_at, one per dataset committed at the requested revision. The wrapper exposes a typed value rather than panproto's raw mapping so the public surface does not leak the binding's dict shape.
| PARAMETER | DESCRIPTION |
|---|---|
schema_id
|
Object id of the schema the dataset was validated against when it was committed.
TYPE:
|
data
|
Panproto's canonical MessagePack encoding of the checked
TYPE:
|
record_count
|
Number of records panproto counted in
TYPE:
|
key
|
Identifier recorded for the dataset: the key passed to
add_data, or the source
path when none was given. A downstream that versions one record
per dataset uses this to map a committed dataset back to its own
key.
TYPE:
|
didactic.api.DecodedCommittedDataset
dataclass
¶
DecodedCommittedDataset(
schema_id: str,
records: list[JsonValue],
record_count: int,
key: str | None = None,
)
A decoded dataset as recorded at a committed revision.
Returned by decoded_data_at, one per dataset committed at the requested revision. The records are ordinary JSON-like Python values decoded by Panproto from its canonical storage representation. A caller can thus pass each record to an explicit current Model without importing Panproto or implementing its MessagePack codec.
| PARAMETER | DESCRIPTION |
|---|---|
schema_id
|
Object id of the schema the dataset was validated against when it was committed.
TYPE:
|
records
|
Decoded records in their committed order. Maps, lists, strings, booleans, nulls, integers, and finite floats retain their JSON shapes.
TYPE:
|
record_count
|
Number of records in
TYPE:
|
key
|
Identifier recorded for the dataset. This has the same value as CommittedDataset.key for the raw representation at the same revision.
TYPE:
|
didactic.api.Blame
dataclass
¶
The commit that introduced a Model field.
Returned by blame_field. The wrapper gives callers a stable didactic type rather than exposing panproto's dict-shaped binding result.
| PARAMETER | DESCRIPTION |
|---|---|
commit_id
|
Object id of the commit that introduced the field vertex.
TYPE:
|
author
|
Author recorded on that commit.
TYPE:
|
timestamp
|
Commit timestamp as Unix seconds.
TYPE:
|
message
|
Commit message.
TYPE:
|