API Reference

The Python API. Repo is the entry point; everything the CLI does is a thin wrapper over it. Backend-specific behavior (locators, config, state, handles) is described in the backends guide.

Repository

The engine and the results it returns.

Repo: A tether dataset: manifests in a VCS working tree plus the systems they name.
StatusReport: Result of Repo.status.
ObjectStatus: One object’s classification in a StatusReport.
VcsDrift: A dataset commit that is gone from VCS history without tether knowing.
CommitResult: Result of Repo.commit.
GcReport: Result of Repo.gc.
AbandonReport: What Repo.abandon did.
DropReport: What Repo.drop did: a bookmark, its commits, and its store leftovers,
ForgetWorkspaceReport: What Repo.apply_forget_workspace did.
PullReport: What pull did: the fetched heads of a bookmark’s branches, committed.
SetReport: What set changed per object.
PromoteReport: Result of Repo.apply_promote.
UndoReport: What Repo.undo reversed, could not reverse, and left alone.
RepairReport: What Repo.repair rebuilt.
RecoverReport: What Repo.recover_report found: tether’s refs in each object’s store,
RecoverStep: One step of a RecoverReport: a command to run, or none, and a note.
RecoveredObject: One object’s row in a RecoverReport.
RecoveredRefs: The refs a store holds under one dataset id (see RecoverReport).
upgrade.UpgradeReport: What Repo.apply_upgrade did.
DiffEntry: One object’s row in Repo.diff.
TETHER_REV_ENV: Environment variable Repo.open reads for its default revision.

Operation log

What tether did to the stores, per workspace; what undo works from.

OpEntry: One applied operation.
oplog.OpEntry: One applied operation.
oplog.TouchedStore: One store this clone forked or pinned in (gc releases its own dead
oplog.tether_path()
oplog.new_op_id(): A fresh 12-hex operation id.
oplog.ops_path()
oplog.report_dict(): A report dataclass as plain data for the op log (without its plan).
oplog.read_ops(): Every entry, oldest first, with undo marks applied (missing log: empty).
oplog.read_jsonl(): Every decodable record of a jsonl index, oldest first. A line an
oplog.append_index_entry(): Append one record and sync it (one write of one line, O_APPEND).
oplog.remove_index_entry()
oplog.touched_path()
oplog.append_touched(): Record a store this clone just wrote a ref into; a set, so an identity
oplog.read_touched(): Every touched store on record (optionally one dataset’s), oldest first.
oplog.remove_touched(): Forget a store (nothing of this dataset’s is left in it).
oplog.pinned_path()
oplog.read_pinned(): The pin ids on record for dataset_id.
oplog.append_pinned(): Record (pin id, kind, key) triples this clone just created; a set, so
oplog.remove_pinned(): Forget pins this clone released.
oplog.mark_progress(): Record that one action of a running operation completed.
oplog.append_op()
oplog.mark_done(): Complete a started entry: what happened, and anything undo learnt
oplog.mark_undone(): Record that op_id was reversed by the undo entry by (an appended mark).
oplog.OPS_FILENAME: The log file inside .tether/ (untracked).
oplog.TOUCHED_FILENAME: Repository-wide index of stores this clone has written refs into – forked
oplog.PINNED_FILENAME: Repository-wide index of the pins this clone created, beside

OpEntry Methods

Methods for the OpEntry class

OpEntry.now()
OpEntry.incomplete: The operation began but no completion mark followed.
OpEntry.to_dict()
OpEntry.from_dict()
OpEntry.undoable: Not itself an undo, not already undone, complete, not a step of
OpEntry.summary(): One line for tether ops.

Migrations

The one composed migration behind tether upgrade, from any 0.1.0 alpha format to the current one. Ships with the betas and is removed at 0.1.0.

upgrade.Repo: A tether dataset: manifests in a VCS working tree plus the systems they name.
upgrade.Plan: The actions a command would perform, plus the inputs they depend on.
upgrade.Migration: A step of tether upgrade: bring a dataset to version.
upgrade.UpgradeReport: What Repo.apply_upgrade did.
upgrade.TetherError: Base class for all tether errors.
upgrade.ensure_ignored(): Make sure .tether/.gitignore lists every per-workspace file.
upgrade.write_config()
upgrade.report_dict(): A report dataclass as plain data for the op log (without its plan).
upgrade.pending(): Migrations a dataset at version still needs, oldest first.
upgrade.outdated_message(): Why a dataset at version cannot be opened, and what to do.
upgrade.plan_upgrade(): Compute what bringing this dataset to the current version would do.
upgrade.apply_upgrade(): Execute a plan from plan_upgrade.
upgrade.upgrade(): Bring the dataset to this tether’s version.
upgrade.CONFIG_VERSION: The [tether] version this code writes and expects. tether upgrade brings
upgrade.MIGRATIONS: Every migration, oldest first. One step covers every alpha and beta
upgrade.LAST_BETA_WITH_UPGRADE: The newest release that can upgrade alpha datasets; bump with each beta

Plans

What a store-writing command would do, as data. Repo.plan_* returns a Plan; Repo.apply_* executes one after re-checking the world matches.

Plan: The actions a command would perform, plus the inputs they depend on.
Precondition: One thing that must still hold when a plan is applied.
Action: One store-writing step in a Plan.

Plan Methods

Methods for the Plan class

Plan.writes: Actions that touch an external system or the working tree.
Plan.is_empty
Plan.require(): Append a precondition (see Precondition).
Plan.digest(): SHA-256 of everything else in the saved plan, as JSON reads it back
Plan.to_dict()
Plan.to_json()
Plan.from_dict(): Load a saved plan.
Plan.edited(): Whether this plan was loaded and its content no longer matches the
Plan.from_json()
Plan.missing_preconditions(): What this plan lacks of REQUIRED_PRECONDITIONS and
Plan.render(): Human-readable lines, one per action, then notes.

Manifest model

What is committed to the VCS (tether.toml, .tether/objects/*.toml) and kept untracked (.tether/workspace.toml), plus the hashing and naming helpers behind pin ids and refs.

RepoConfig: Committed repository configuration.
Policy: Per-object behavioral knobs.
Pin: A durable native reference created for a committed state.
ObjectManifest: The committed record for one object.
WorkspaceState: Untracked per-workspace working state.
compute_pin_id(): Content-address a pin: <dataset8>.<hash16>.
ref_for_pin(): Native reference name for a pin id (dot-delimited; no /).
working_ref_name(): The store branch that stands for a dataset bookmark.
working_ref_bookmark(): The bookmark slug a working ref stands for; None for legacy
working_ref_workspace(): The 8-char workspace id in a legacy working ref name (before
listing_name(): Content-addressed file name for a state’s listing.
manifest_hash(): Hash the full committed object set (order-independent).

Handles

Typed native handles returned by Repo.open.

handles.Handle: Base class for all native handles.
handles.FileHandle: A plain file or object-store artifact (always read-only).
handles.IcechunkHandle: An Icechunk repository positioned at a branch (write) or tag (read).
handles.NeonHandle: A Neon Postgres connection URL for a branch or a pinned point in time.
handles.GitHandle: A git/jj repository positioned at a sha (and optional worktree path).
handles.IcebergHandle: A pyiceberg table positioned at a branch (write) or tag (read).
handles.DeltaHandle: A Delta Lake table loaded at a specific version (always read-only).
handles.LanceHandle: A Lance dataset checked out at a branch (write) or tag/version (read).
handles.DuckLakeHandle: A DuckLake catalog attached (read-only) in a DuckDB connection.
handles.DoltHandle: A Dolt revision database: mysql://user@host:port/db/<ref>.
handles.MemoryHandle: In-memory reference handle used by the conformance suite and tests.
handles.redact_url(): url with any password replaced by ***.

Backend protocol

Implement ObjectBackend and register it to add a system; capability flags decide which commands apply.

backends.ChangeEntry: One changed thing inside an object: a file, table, array, key, …
backends.HistoryEntry: One native commit / snapshot / version, as listed by ObjectBackend.history.
backends.ObjectDiff: What changed inside one object between two recorded states.
backends.VerifyReport: Result of ObjectBackend.verify for one object.
backends.ObjectBackend: The operations tether needs from one class of system.
backends.Capability: What a backend can do.
backends.Tier: The cumulative capability tier of a backend (or of one object).
backends.VerifyStatus: Outcome of ObjectBackend.verify.
backends.base_at(): The locator’s at field (a detached base state), if any.
backends.build_backend()
backends.content_state(): The part of a state that identifies the data: the state minus
backends.effective_capabilities(): Capabilities for a specific object.
backends.known_kinds()
backends.register_backend()
backends.tier_of()
backends.MAX_DIFF_ENTRIES
backends.Listings

Conformance suite

Capability-parametrized checks for backend authors.

testing.BackendError: A backend operation failed.
testing.RefMovedError: A conditional ref move found the ref elsewhere than expected.
testing.ObjectDiff: What changed inside one object between two recorded states.
testing.Handle: Base class for all native handles.
testing.Pin: A durable native reference created for a committed state.
testing.Policy: Per-object behavioral knobs.
testing.ObjectBackend: The operations tether needs from one class of system.
testing.BackendHarness: Test fixture a backend author provides to drive the suite.
testing.Capability: What a backend can do.
testing.VerifyStatus: Outcome of ObjectBackend.verify.
testing.accepts_expected(): Whether a backend’s fork, promote or merge takes the expected
testing.content_state(): The part of a state that identifies the data: the state minus
testing.effective_capabilities(): Capabilities for a specific object.
testing.compute_pin_id(): Content-address a pin: <dataset8>.<hash16>.
testing.ref_for_pin(): Native reference name for a pin id (dot-delimited; no /).
testing.working_ref_name(): The store branch that stands for a dataset bookmark.
testing.run_conformance(): Run all capability-appropriate checks; raise AssertionError on fail.
testing.ABSENT: expected for a conditional ObjectBackend.fork(): the branch must
testing.Locator
testing.CONFORMANCE_DATASET: Dataset id the conformance suite pins under (any 8 hex chars would do).
testing.RACERS: Threads the CONDITIONAL_REF race checks start at once.

Registries (experimental)

Export tables (ExportBundle, TABLES), Postgres publishing, and the canonical import columns / sources for import. Lives under tether.experimental.registry; import the public names from tether.

experimental.registry: The registry layer: export, publish, and import of dataset metadata.
experimental.registry.ImportReport: Result of apply_import() (Repo.apply_import).

Store lifecycle (experimental)

add --create / Repo.create make a store tether owns; gc --delete-stores removes it once nothing references it. The created- and touched-store indexes, the planning rules, and the graduation criteria live in tether.experimental.lifecycle.

experimental.lifecycle: Store lifecycle: create a store tether then owns, and reclaim it.

VCS adapters

How tether reads and writes history through jj or git.

vcs.VcsError: A version-control operation failed.
vcs.GitObjectReader: Read many objects through one git cat-file --batch process.
vcs.JjAdapter
vcs.GitAdapter
vcs.CommitInfo: Metadata of one VCS commit, as exported to registries.
vcs.RefInfo: A named pointer into history: a jj bookmark, git branch, tag, or the head.
vcs.VcsAdapter: The VCS surface tether relies on. Paths are relative to root.
vcs.git_env(): The environment for a git (or jj) subprocess: this process’s, without
vcs.require_git_version(): Refuse a git older than MIN_GIT_VERSION; an unparseable banner (a
vcs.detect_vcs(): Discover the enclosing VCS, preferring jj when repos are colocated.
vcs.MIN_JJ_VERSION: The oldest jj tether runs on; the adapter checks once and refuses an older
vcs.MIN_GIT_VERSION: The oldest git tether runs on: safe.bareRepository, which keeps the git

Errors

TetherError: Base class for all tether errors.
ConfigError: The repository configuration or manifest layout is invalid.
VcsError: A version-control operation failed.
BackendError: A backend operation failed.
CapabilityError: An operation was requested that the backend does not support.
ImmutableObjectModified: An object registered as immutable changed on disk / in storage.
UnpinnedStateError: A pinnable object has working state that was never pinned.
PinDriftError: A pin no longer resolves to the state recorded in the manifest.
StaleWorkingCopyError: The workspace was forked from a manifest that no longer matches HEAD.
StalePlanError: A saved plan no longer matches the world it was computed from.
MergeConflict: A native merge stopped on conflicts; nothing was written.
errors.RefMovedError: A conditional ref move found the ref elsewhere than expected.
MultiObjectError: Aggregates per-object failures from a fan-out operation.