repomatic.deps.provenance module

PEP 740 provenance of the PyPI releases a sync bumps to.

A project publishing through PyPI’s trusted publishing uploads every release from its own workflow, which attaches the provenance on its own. So a release with no provenance, after one that carried it, was uploaded some other way: by hand, or with a stolen API token, the shape most PyPI account takeovers take. sync-uv-lock and sync-tool-versions hold such a bump back and report it instead of adopting it unread.

The check fails open on a lookup PyPI does not answer: an unknown provenance holds nothing, since a transient error is not evidence. A trusted publisher that changes between two releases is flagged in the report and held neither: a repository transfer or rename changes it legitimately.

The cooldown and the provenance check guard different things. The cooldown waits for a compromise to be noticed and the release pulled. The provenance check catches the upload that bypassed the project’s pipeline, which a quiet compromise can survive a cooldown with.

class repomatic.deps.provenance.PypiBump(name, package, old, new)[source]

Bases: object

One version move of a PyPI package, as a sync is about to make it.

name: str

Name of the report row: a tool name, or the package name.

package: str

The PyPI project the versions belong to.

old: str

Version in place, or empty for a package the run adds.

new: str

Version the run moves to.

class repomatic.deps.provenance.ProvenanceReview(cells, holds)[source]

Bases: object

The provenance of a run’s PyPI bumps.

cells: dict[str, str]

Row name to the markdown of its “Provenance” cell.

holds: list[ProvenanceHold]

The bumps to withhold, in the order of the bumps reviewed.

property held: set[str]

Row names of the withheld bumps.

repomatic.deps.provenance.provenance_cell(new, old)[source]

Render the “Provenance” cell of a bump to new from old.

Parameters:
Return type:

str

repomatic.deps.provenance.is_regression(new, old)[source]

Whether a bump from old to new lost provenance.

Both lookups must have answered: an unknown side proves nothing.

Return type:

bool

repomatic.deps.provenance.review_bumps(bumps, *, jobs=1)[source]

Look up the provenance of both ends of each bump, and pick those to hold.

Parameters:

  • bumps (Sequence[PypiBump]) – The PyPI version moves of the run.

  • jobs (int) – How many lookups run at once.

Return type:

ProvenanceReview

Returns:

The cell of every bump, and the bumps that lost provenance.