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.

Parameters:

Name	Type	Description	Default
inner	Repository	An already-constructed panproto.Repository. Most callers should use init or open instead of constructing this class directly.	required

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.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	Directory in which to create the .panproto/ store. The directory is created if it does not exist.	required

Returns:

Type	Description
Repository	A handle to the newly initialised repository.

Raises:

Type	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.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	Directory containing a .panproto/ store.	required

Returns:

Type	Description
Repository	A handle to the existing repository.

Raises:

Type	Description
VcsError	If no repository exists at path.

head

head() -> str | None

Resolve HEAD to a commit object id.

Returns:

Type	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:

Type	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:

Type	Description
list of (str, str)	One (name, commit_id) tuple per branch.

list_tags

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

Return the list of tags.

Returns:

Type	Description
list of (str, str)	One (name, target_id) tuple per tag.

log

log() -> list[JsonObject]

List commits reachable from HEAD, newest first.

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
ref	str	A branch name, tag name, or commit-id prefix.	required

Returns:

Type	Description
str	The full commit id.

Raises:

Type	Description
VcsError	If ref does not resolve to a commit.

add

add(target: Schema | type) -> None

Stage target for the next commit.

Parameters:

Name	Type	Description	Default
target	Schema | type	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.	required

Notes

Staging is additive: subsequent calls accumulate in the index until a commit flushes it.

commit

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

Create a commit with message and author.

Parameters:

Name	Type	Description	Default
message	str	The commit message.	required
author	str	The commit author. Free-form string; the conventional shape is "Name <email>".	required
skip_verify	bool	If True, skip the panproto-side verification step. Defaults to False.	False

Returns:

Type	Description
str	The new commit's object id.

Raises:

Type	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.