plesty.sdk.semver

Authoritative semantic-versioning support for gate 8 of plesty check.

Compares the public API of the working tree against the newest release published on its own line (static analysis via griffe — the analyzed code is never imported) and derives the minimum version a breaking change requires: a minor bump before 1.0.0, a major bump afterwards.

Attributes

_PYPI_TIMEOUT

Timeout for PyPI requests in seconds.

Classes

PypiBaseline

The published release used as the API-diff baseline.

Functions

_wheel_url(→ str | None)	The download URL of the first usable wheel among files, if any.
fetch_pypi_baseline(→ PypiBaseline | None)	Return the release on PyPI to diff the working tree against.
download_wheel(→ pathlib.Path)	Download a wheel and extract it, returning the extraction directory.
find_api_breakages(→ list[str])	Diff the public API of top-level packages between two source roots.
required_minimum_version(→ packaging.version.Version)	Return the minimum next version a breaking change requires.
latest_tag_version(→ packaging.version.Version | None)	Return the version of the latest reachable git tag, or None.

Module Contents

plesty.sdk.semver._PYPI_TIMEOUT = 15

Timeout for PyPI requests in seconds.

class plesty.sdk.semver.PypiBaseline

The published release used as the API-diff baseline.

version: packaging.version.Version

Version of that release on PyPI.

wheel_url: str

Download URL of its wheel.

plesty.sdk.semver._wheel_url(files: list[dict[str, Any]]) → str | None

The download URL of the first usable wheel among files, if any.

Yanked files are skipped: a yanked release is one the maintainer has withdrawn, and diffing against it would measure an API nobody should be running.

Parameters:

files (list[dict[str, Any]])

Return type:

str | None

plesty.sdk.semver.fetch_pypi_baseline(name: str, line: tuple[int, int] | None = None) → PypiBaseline | None

Return the release on PyPI to diff the working tree against.

Without line this is the newest release, which is right whenever the tree continues the newest line. A maintenance branch does not: it takes fixes to its own features and merges only upward, so it never gains what a later line added. Diffing it against the newest release would read that line’s additions as removals from the older tree — every one of them, on every run, for as long as the line is supported. Passing line picks the newest release the tree could actually be a successor of.

Parameters:

• name (str) – The distribution name (e.g. plesty-sdk).

• line (tuple[int, int] | None) – (major, minor) of the line being built. The baseline is then the newest release at or below it — at or below, not equal to, so the first release of a new line still has a predecessor to diff against.

Returns:

The baseline, or None when the package is not published, has no wheel, or PyPI is unreachable (offline runs degrade gracefully).

Return type:

PypiBaseline | None

plesty.sdk.semver.download_wheel(url: str, dest: pathlib.Path) → pathlib.Path

Download a wheel and extract it, returning the extraction directory.

Parameters:

• url (str) – Wheel download URL (from the PyPI JSON API).

• dest (pathlib.Path) – Working directory for the download and extraction.

Returns:

The directory containing the extracted top-level packages.

Return type:

pathlib.Path

plesty.sdk.semver.find_api_breakages(packages: list[str], old_root: pathlib.Path, new_root: pathlib.Path) → list[str]

Diff the public API of top-level packages between two source roots.

Parameters:

• packages (list[str]) – Top-level package names to compare (e.g. ["plesty"]).

• old_root (pathlib.Path) – Root directory of the baseline (extracted release wheel).

• new_root (pathlib.Path) – Root directory of the working tree.

Returns:

One human-readable line per breaking change; empty when the new API is backwards-compatible.

Return type:

list[str]

plesty.sdk.semver.required_minimum_version(published: packaging.version.Version) → packaging.version.Version

Return the minimum next version a breaking change requires.

Pre-1.0 releases may break in a minor bump (SemVer §4 convention); from 1.0.0 on, breaking changes require a major bump.

Parameters:

published (packaging.version.Version) – The latest published version.

Returns:

The lowest acceptable version for a release containing breakages.

Return type:

packaging.version.Version

plesty.sdk.semver.latest_tag_version(project_dir: pathlib.Path) → packaging.version.Version | None

Return the version of the latest reachable git tag, or None.

Parameters:

project_dir (pathlib.Path) – Root directory of the target project.

Return type:

packaging.version.Version | None