Repository¶

didactic.api.Repository ¶

Repository(inner: 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 `panproto.Repository`. Most callers should use init or open instead of constructing this class directly. TYPE: `Repository`

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

working_dir `property` ¶

working_dir: str

Path to the repository's working directory.

init `classmethod` ¶

init(path: str | PathLike[str]) -> Repository

Initialise a new repository at path.

PARAMETER	DESCRIPTION
`path`	Directory in which to create the `.panproto/` store. The directory is created if it does not exist. TYPE: `str \| PathLike[str]`

RETURNS	DESCRIPTION
`Repository`	A handle to the newly initialised repository.

RAISES	DESCRIPTION
`VcsError`	If a repository already exists at `path` or the path is not writable.

open `classmethod` ¶

open(path: str | PathLike[str]) -> Repository

Open an existing repository at path.

PARAMETER	DESCRIPTION
`path`	Directory containing a `.panproto/` store. TYPE: `str \| PathLike[str]`

RETURNS	DESCRIPTION
`Repository`	A handle to the existing repository.

RAISES	DESCRIPTION
`VcsError`	If no repository exists at `path`.

head ¶

head() -> str | None

Resolve HEAD to a commit object id.

RETURNS	DESCRIPTION
`str or None`	The commit id, or `None` if the repository has no commits yet.

head_state ¶

head_state() -> str

Describe the current HEAD state.

RETURNS	DESCRIPTION
`str`	A descriptor string from panproto. For a freshly initialised repository this is typically `"ref: refs/heads/main"`.

has_staged ¶

has_staged() -> bool

Return True if anything is staged for the next commit.

list_branches ¶

list_branches() -> list[tuple[str, str]]

Return the list of branches.

RETURNS	DESCRIPTION
`list of (str, str)`	One `(name, commit_id)` tuple per branch.

list_tags() -> list[tuple[str, str]]

Return the list of tags.

RETURNS	DESCRIPTION
`list of (str, str)`	One `(name, target_id)` tuple per tag.

log ¶

log() -> list[JsonObject]

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_ref(ref: str) -> str

Resolve a ref expression to a commit id.

PARAMETER	DESCRIPTION
`ref`	A branch name, tag name, or commit-id prefix. TYPE: `str`

RETURNS	DESCRIPTION
`str`	The full commit id.

RAISES	DESCRIPTION
`VcsError`	If `ref` does not resolve to a commit, or returns `None`.

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 bytes, leaving HEAD and the working tree untouched. This is the data-side counterpart to panproto's committed-schema lookup, so a downstream can reconstruct the record set at an arbitrary revision, for example to diff two revisions, without checking it out.

PARAMETER	DESCRIPTION
`ref`	A branch name, tag name, `HEAD`, or commit id naming the revision to read. TYPE: `str`

RETURNS	DESCRIPTION
`list of CommittedDataset`	One entry per dataset committed at `ref`, in panproto's recorded order. Empty when the revision committed no data.

RAISES	DESCRIPTION
`VcsError`	If `ref` does not resolve to a revision.

add ¶

add(target: Schema | type) -> None

Stage target for the next commit.

PARAMETER	DESCRIPTION
`target`	Either a `panproto.Schema` or a Model subclass. When given a Model class, didactic builds a schema using `panproto.Protocol.from_theories` over the Model's Theory. TYPE: `Schema \| 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
) -> None

Stage a data file for the next commit.

Reads the file at path and stages its contents 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 data file to stage. The file is read immediately and its contents are captured into the repository's object store. TYPE: `str \| PathLike[str]`
`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 `path`. TYPE: `str \| None` DEFAULT: `None`

Notes

Staging is additive: like add, repeated calls accumulate in the index until a commit flushes it.

RAISES	DESCRIPTION
`VcsError`	If no schema is staged and the repository has no commits yet, so the dataset has no schema to bind to.

commit ¶

commit(
    message: str, *, author: str, skip_verify: bool = False
) -> str

Create a commit with message and author.

PARAMETER	DESCRIPTION
`message`	The commit message. TYPE: `str`
`author`	The commit author. Free-form string; the conventional shape is `"Name <email>"`. TYPE: `str`
`skip_verify`	If `True`, skip the panproto-side verification step. Defaults to `False`. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`str`	The new commit's object id.

RAISES	DESCRIPTION
`VcsError`	If nothing is staged or panproto rejects the commit.

create_branch ¶

create_branch(name: str, commit_id: str) -> None

Create a new branch name pointing at commit_id.

checkout_branch ¶

checkout_branch(name: str) -> None

Switch HEAD to branch name.

create_tag ¶

create_tag(
    name: str, target: str, *, force: bool = False
) -> None

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: `str`
`target`	The commit id to tag, as returned by commit, head, or resolve_ref. TYPE: `str`
`force`	If `True`, overwrite an existing tag of the same name. Defaults to `False`, under which an existing `name` is an error. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`VcsError`	If a tag `name` already exists and `force` is `False`.

create_annotated_tag ¶

create_annotated_tag(
    name: str, target: str, *, message: str, tagger: str
) -> str

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: `str`
`target`	The commit id to tag (see create_tag for the accepted forms). TYPE: `str`
`message`	The tag message. TYPE: `str`
`tagger`	The tagger identity. Free-form string; the conventional shape is `"Name <email>"`. TYPE: `str`

RETURNS	DESCRIPTION
`str`	Object id of the created annotated-tag object, the id the tag ref resolves to.

RAISES	DESCRIPTION
`VcsError`	If a tag `name` already exists or panproto rejects the tag.

delete_tag ¶

delete_tag(name: str) -> None

Delete the tag name.

PARAMETER	DESCRIPTION
`name`	The tag to delete. TYPE: `str`

RAISES	DESCRIPTION
`VcsError`	If no tag `name` exists.

didactic.api.CommittedDataset `dataclass` ¶

CommittedDataset(
    schema_id: str,
    data: bytes,
    record_count: int,
    key: str | None = None,
)

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: `str`
`data`	The raw committed bytes, exactly as staged (typically content-addressed JSON). TYPE: `bytes`
`record_count`	Number of records panproto counted in `data` at commit time. TYPE: `int`
`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. `None` only if panproto recorded no identifier. TYPE: `str \| None` DEFAULT: `None`

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Repository¶

didactic.api.Repository ¶

working_dir property ¶

init classmethod ¶

open classmethod ¶

head ¶

head_state ¶

has_staged ¶

list_branches ¶

list_tags ¶

log ¶

resolve_ref ¶

data_at ¶

add ¶

add_data ¶

commit ¶

create_branch ¶

checkout_branch ¶

create_tag ¶

create_annotated_tag ¶

delete_tag ¶

didactic.api.CommittedDataset dataclass ¶

working_dir `property` ¶

init `classmethod` ¶

open `classmethod` ¶

didactic.api.CommittedDataset `dataclass` ¶