app.services.diff

Unified diff between stored snapshots (GET /api/v1/records/{id}/diff).

The diff compares the exact canonical snapshots in the revision store (never Git history). Defaults:

  • from: the identity’s last decided snapshot other than the current digest (latest acceptance, else latest rejection, app.domain.approval.last_decided()); else the record’s previous_digest; else there is no base (reason: "no_prior_revision").

  • to: the record’s current digest.

Only digests related to the record may be requested: its current and previous digest, digests decided for its identity, and the current digests of its identity siblings. Any other digest is answered with 404 unknown_revision, so the endpoint cannot be used to read arbitrary snapshots.

Public API: DiffEndpoint, RecordDiff, diff_record(), short_digest().

class app.services.diff.DiffEndpoint(*, digest, label, decided_at=None)

Bases: object

One side of a diff.

Parameters:

  • digest (str) – Digest of the snapshot.

  • label (str) – What the snapshot is, e.g. last accepted, last rejected, previous revision, current revision.

  • decided_at (datetime | None) – When it was decided, for decided snapshots.

digest: str
label: str
decided_at: datetime | None
class app.services.diff.RecordDiff(*, base, target, reason, unified_diff, identical, lines_added, lines_removed)

Bases: object

A unified diff between two snapshots of one record’s identity.

Parameters:

  • base (DiffEndpoint | None) – The from side, None without a prior revision.

  • target (DiffEndpoint) – The to side.

  • reason (str | None) – no_prior_revision when there is no base.

  • unified_diff (str) – difflib unified diff text (empty when the snapshots are identical or there is no base).

  • identical (bool) – Whether both snapshots are the same content.

  • lines_added (int) – Number of added lines.

  • lines_removed (int) – Number of removed lines.

base: DiffEndpoint | None
target: DiffEndpoint
reason: str | None
unified_diff: str
identical: bool
lines_added: int
lines_removed: int
app.services.diff.diff_record(store, record_id, *, from_digest=None, to_digest=None)

Diff two snapshots of a record’s identity.

Parameters:

  • store (CatalogStore) – Store of the caller’s unit of work.

  • record_id (UUID) – Record id.

  • from_digest (str | None) – Base digest; default per the module docstring.

  • to_digest (str | None) – Target digest; default the current digest.

Return type:

RecordDiff

Returns:

The diff.

Raises:

NotFoundError – record_not_found or unknown_revision.

app.services.diff.short_digest(digest)

Shorten a digest for display (algorithm prefix kept).

Parameters:

digest (str) – Full digest string.

Return type:

str

Returns:

<algorithm>:<first 12 hex>.