Skip to content

API Reference

The core logic is importable from the dependency_support_policy package — useful if you want SPEC 0 floor computation inside your own tooling.

Policies

Support-policy definitions and support-window floor calculations.

Spec0Policy

Bases: SupportPolicy

Scientific Python SPEC 0: drop Python after 3 years, packages after 2.

SupportPolicy

Bases: ABC

A named policy providing default support windows.

Additional policies can be added by subclassing and registering in :data:_POLICIES.

windows() abstractmethod

Return the default support windows for this policy.

SupportWindows dataclass

Default support windows (in calendar months) defined by a policy.

available_policies()

Names of all registered policies.

compute_floor(series, reference, window_months)

Return the minimum supported version under a rolling support window.

A minor series is supported if its first stable release happened within window_months calendar months before reference (window boundary inclusive). The floor is the first version of the oldest supported series. If every series is older than the window, the newest series is the floor, so at least one release line is always supported.

Series first released after reference are ignored so that evaluation with a historical reference date is reproducible.

get_policy(name)

Look up a policy by name, raising :class:ConfigError if unknown.

Release metadata

Package release metadata retrieval.

The planner only needs, for every minor release series of a package, the version and date of the first stable (non-prerelease, non-yanked) release in that series. :class:ReleaseFetcher is the seam used to mock the registry in tests; :class:PyPIReleaseFetcher is the production implementation backed by the PyPI JSON API.

PyPIReleaseFetcher

Fetch release metadata from the PyPI JSON API, with retries and caching.

ReleaseFetcher

Bases: Protocol

Retrieves per-minor-series first-release information for a package.

fetch_series(package)

Return all stable minor series of package, sorted by series.

SeriesRelease dataclass

The first stable release of one minor release series of a package.

build_series(version_dates)

Collapse per-version release dates into per-minor-series first releases.

parse_pypi_payload(payload)

Extract stable minor series from a PyPI JSON API response.

Prereleases and dev releases are ignored; a release counts only if it has at least one non-yanked file, and its date is the earliest upload time of those files.

series_key(version)

Group a version into its (major, minor) series; 2 groups as (2, 0).

CPython releases

CPython release history used to compute the Python support floor.

The table lists the initial (x.y.0) release date of each CPython minor series. New series can be appended via configuration ([tool.dependency-support-policy.python-releases]) without a new release of this tool.

python_series(extra=None)

Return CPython minor series, merging configured extra releases.

table_may_be_stale(reference, extra=None)

True if the reference date is far beyond the newest known CPython release.

Requirement rewriting

Parsing and lower-bound rewriting of PEP 508 requirement strings.

Rewrites are textual splices: only the lower-bound clause (or a newly appended one) changes, so upper bounds, exclusions, extras, markers, and the original spacing are preserved character-for-character.

RewriteResult dataclass

Result of rewriting one requirement (or specifier) string.

RewriteStatus

Bases: Enum

Outcome of a lower-bound rewrite attempt.

requirement_name(text)

Canonical distribution name of a requirement string, or None if unparsable.

rewrite_requirement_lower_bound(text, floor)

Raise the lower bound of a full PEP 508 requirement string.

rewrite_specifier_lower_bound(spec_text, floor)

Raise the >= lower bound of a bare specifier set (e.g. requires-python).

pyproject.toml editing

Format-preserving pyproject.toml reading and editing via tomlkit.

DependencyItem dataclass

One string entry of a dependency array, addressable for in-place update.

available_groups(document)

All dependency collections present in the document.

iter_dependency_items(document, groups)

List all string requirement entries in the selected groups.

Non-string entries (e.g. {include-group = "..."}) are ignored.

load_document(path)

Parse path as TOML, preserving formatting and comments.

resolve_groups(document, selection)

Expand a group selection (supporting all, optional, group) to concrete groups.

Explicitly named groups that do not exist raise :class:ConfigError.

write_text_atomic(path, text)

Write text to path atomically (write temp file, then rename).

Planning and applying

Build and apply change plans: the orchestration layer.

build_plan is pure (no file writes); apply_plan performs the edits, optionally regenerates uv.lock, and rolls everything back if that fails.

ApplyResult dataclass

Files touched when a plan was applied.

ChangePlan dataclass

Everything one evaluation decided, machine-readable.

DependencyChange dataclass

A dependency whose lower bound the policy raises.

PythonFloorChange dataclass

A change to requires-python.

SkippedDependency dataclass

A dependency the policy could not (or should not) rewrite.

apply_plan(document, plan, config)

Write the planned edits to disk, regenerating uv.lock if configured.

If lockfile regeneration fails, both pyproject.toml and uv.lock are restored to their prior contents before the error propagates.

build_plan(document, config, fetcher)

Evaluate the policy against document and return the change plan.

Configuration

Run configuration: defaults, the pyproject tool table, and CLI overrides.

LockMode

Bases: Enum

How to treat uv.lock after pyproject.toml changes.

RunConfig dataclass

Fully resolved configuration for one evaluation run.

load_config(pyproject, document, reference_date, cli_overrides=None)

Merge tool-table settings with CLI overrides (CLI wins) into a RunConfig.

cli_overrides keys mirror RunConfig field names; only keys with non-None values participate.

parse_package_overrides(pairs)

Parse a name -> months mapping, canonicalizing names.

Lockfile handling

uv lockfile regeneration with rollback on failure.

regenerate_lockfile(project_dir, mode, *, uv_executable='uv')

Run uv lock in project_dir; return True if uv.lock content changed.

LockMode.MINIMAL performs the default minimal re-lock; LockMode.UPGRADE passes --upgrade. Raises :class:LockfileError on failure — the caller is responsible for rolling back file snapshots.

Dates

Deterministic calendar arithmetic used by support-window calculations.

months_before(reference, months)

Return the date months calendar months before reference.

The day of month is preserved, clamped to the length of the target month (e.g. 2024-03-31 minus one month is 2024-02-29).

parse_iso_date(text)

Parse a YYYY-MM-DD date, raising :class:ConfigError on bad input.

Errors

Exception hierarchy for dependency-support-policy.

ConfigError

Bases: DependencyPolicyError

Invalid configuration (CLI flags, action inputs, or the tool table).

DependencyPolicyError

Bases: Exception

Base class for all errors raised by this package.

LockfileError

Bases: DependencyPolicyError

uv lockfile regeneration failed.

PolicyError

Bases: DependencyPolicyError

A support policy could not be evaluated (e.g. no stable releases).

RegistryError

Bases: DependencyPolicyError

Failure to retrieve or parse package release metadata.