Skip to content

Python API

xpt exports one name, expect. Tools that want the CLI's behavior without parsing its output import xpt.api. The CLI is a thin wrapper over these functions.

from pathlib import Path

from xpt import api

root = Path(".")
run = api.latest_run(root)
groups = api.mark(api.group(api.load_run(root, run)), api.load_rejections(root))
result = api.accept(root, [g for g in groups if g.offered], dry_run=True)
for outcome in result.outcomes:
    print(outcome.group.id, outcome.status, outcome.reason)

Reading a run

Function Returns
run_ids(root) Recorded run ids, oldest first.
latest_run(root) The id of the newest complete run. Raises RecordError when there is none.
load_run(root, run=None) The run's Observations. None reads the latest run. Raises RecordError on a malformed record and names the file and line.
group(observations) A tuple of Group, one per call site, sorted by path, line, and position. Pure.

Deciding

Function Effect
accept(root, groups, *, dry_run=False) Writes each acceptable group's actual value into its source. Returns AcceptResult(outcomes, changed). Raises AcceptError when .xpt/accept.lock is held.
reject(root, run, groups) Records each group's actual value as a bug. Returns a tuple of RejectOutcome.
load_rejections(root) The recorded rejections, as a frozenset of Rejection.
mark(groups, rejections) The groups with rejected set. Pure.

Comparing

Function Returns
diff(expected, actual) Diff(changes, unchanged), where each Change has path, op, expected, and actual.
format_path(path, root="value") A change path as text, such as value.items[1].
to_json(value), from_json(data) A Value to and from its JSON form.

Types

Type Fields
Observation run, test, site, status, expected, actual, detail
Status "missing", "mismatch", "unsupported"
Group id, site, status, actuals, expected, tests, detail, rejected, and the properties acceptable and offered
GroupStatus Status plus "conflict" and "unlocatable"
CallSite path, qualname, callee, ordinal, arg_sha, line
Unlocatable reason, path, line
Outcome group, status, reason
OutcomeStatus "accepted", "already_accepted", "stale", "skipped"
RejectOutcome group, status, reason
RejectStatus "rejected", "already_rejected", "skipped"
Value The recorded value tree.

Every type is a frozen dataclass or a Literal. offered is true when a group is acceptable and not rejected, which is what xpt accept --all selects.

The API is pre-1.0. Names may change between minor versions.