dependency-support-policy 0.1.0__py3-none-any.whl

dependency_support_policy/__init__.py

@@ -0,0 +1,12 @@
+"""Manage rolling minimum-supported versions for Python projects."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dependency-support-policy")
+except PackageNotFoundError:  # pragma: no cover - only when running from a raw checkout
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

dependency_support_policy/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m dependency_support_policy``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dependency_support_policy/cli.py

@@ -0,0 +1,220 @@
+"""Command-line interface: check, plan, and update modes.
+
+Exit codes: 0 = compliant / success, 1 = drift found (check mode only),
+2 = configuration, registry, or lockfile error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import sys
+import uuid
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, TextIO
+
+from . import __version__
+from .config import LockMode, load_config
+from .dates import parse_iso_date
+from .errors import ConfigError, DependencyPolicyError
+from .planner import ApplyResult, ChangePlan, apply_plan, build_plan
+from .policies import available_policies
+from .pyproject_edit import load_document
+from .registry import PyPIReleaseFetcher, ReleaseFetcher
+
+EXIT_OK = 0
+EXIT_DRIFT = 1
+EXIT_ERROR = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dependency-support-policy",
+        description="Manage rolling minimum-supported versions for Python projects.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="mode", required=True, metavar="{check,plan,update}")
+    modes = {
+        "check": "Report drift; exit 1 if any floor is below the policy.",
+        "plan": "Print the machine-readable change plan as JSON; never writes.",
+        "update": "Apply floor updates to pyproject.toml (and uv.lock if configured).",
+    }
+    for mode, help_text in modes.items():
+        sub = subparsers.add_parser(mode, help=help_text, description=help_text)
+        _add_common_arguments(sub)
+    return parser
+
+
+def _add_common_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--pyproject", type=Path, default=Path("pyproject.toml"), help="Path to pyproject.toml.")
+    parser.add_argument(
+        "--reference-date",
+        default=None,
+        help="Evaluate support windows as of this date (YYYY-MM-DD); defaults to today (UTC).",
+    )
+    parser.add_argument("--policy", default=None, choices=available_policies(), help="Support policy to apply.")
+    parser.add_argument("--python-support-months", type=int, default=None, help="Override the Python support window.")
+    parser.add_argument(
+        "--package-support-months", type=int, default=None, help="Override the default package support window."
+    )
+    parser.add_argument(
+        "--package-override",
+        action="append",
+        default=None,
+        metavar="NAME=MONTHS",
+        help="Per-package support window (repeatable).",
+    )
+    parser.add_argument(
+        "--include",
+        action="append",
+        default=None,
+        metavar="NAMES",
+        help="Only manage these packages (comma separated, repeatable).",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        metavar="NAMES",
+        help="Never touch these packages (comma separated, repeatable).",
+    )
+    parser.add_argument(
+        "--groups",
+        default=None,
+        help="Comma-separated dependency collections to manage: project, optional[:name], group[:name], all.",
+    )
+    parser.add_argument(
+        "--manage-python",
+        default=None,
+        choices=("true", "false"),
+        help="Whether to manage the requires-python floor (default: true).",
+    )
+    parser.add_argument(
+        "--lock",
+        default=None,
+        choices=[mode.value for mode in LockMode],
+        help="uv.lock handling after updates (default: off).",
+    )
+    parser.add_argument("--output-json", type=Path, default=None, help="Also write the change plan JSON to this file.")
+    parser.add_argument("--quiet", action="store_true", help="Suppress the human-readable summary.")
+
+
+def _split_names(values: Sequence[str] | None) -> list[str] | None:
+    if values is None:
+        return None
+    names = [name.strip() for value in values for name in value.split(",") if name.strip()]
+    return names
+
+
+def _parse_override_flags(values: Sequence[str] | None) -> dict[str, int] | None:
+    if values is None:
+        return None
+    overrides: dict[str, int] = {}
+    for value in values:
+        name, separator, months = value.partition("=")
+        if not separator or not name.strip():
+            raise ConfigError(f"invalid --package-override {value!r}: expected NAME=MONTHS")
+        try:
+            overrides[name.strip()] = int(months)
+        except ValueError:
+            raise ConfigError(f"invalid --package-override {value!r}: MONTHS must be an integer") from None
+    return overrides
+
+
+def _cli_overrides(args: argparse.Namespace) -> dict[str, Any]:
+    manage_python = None if args.manage_python is None else args.manage_python == "true"
+    groups = None
+    if args.groups is not None:
+        groups = [token.strip() for token in args.groups.split(",") if token.strip()]
+    return {
+        "policy_name": args.policy,
+        "python_support_months": args.python_support_months,
+        "package_support_months": args.package_support_months,
+        "package_overrides": _parse_override_flags(args.package_override),
+        "include": _split_names(args.include),
+        "exclude": _split_names(args.exclude),
+        "groups": groups,
+        "manage_python": manage_python,
+        "lock": args.lock,
+    }
+
+
+def _summarize(plan: ChangePlan, mode: str, apply_result: ApplyResult | None, stream: TextIO) -> None:
+    print(f"policy: {plan.policy} (reference date {plan.reference_date.isoformat()})", file=stream)
+    if not plan.changed:
+        print("all managed floors comply with the policy", file=stream)
+    for change in plan.dependency_changes:
+        print(f"  {change.group}: {change.old_requirement!r} -> {change.new_requirement!r}", file=stream)
+    if plan.python_change is not None:
+        print(
+            f"  requires-python: {plan.python_change.old_requires_python!r} -> "
+            f"{plan.python_change.new_requires_python!r}",
+            file=stream,
+        )
+    for skipped in plan.skipped:
+        print(f"  skipped {skipped.requirement!r}: {skipped.reason}", file=stream)
+    for note in plan.notes:
+        print(f"  note: {note}", file=stream)
+    if mode == "update" and apply_result is not None:
+        if apply_result.changed_files:
+            print(f"updated files: {', '.join(apply_result.changed_files)}", file=stream)
+        else:
+            print("no files changed", file=stream)
+
+
+def _write_github_outputs(plan: ChangePlan, apply_result: ApplyResult | None) -> None:
+    output_path = os.environ.get("GITHUB_OUTPUT")
+    if not output_path:
+        return
+    floors_changed = [
+        {"name": change.name, "group": change.group, "old": change.old_floor, "new": change.new_floor}
+        for change in plan.dependency_changes
+    ]
+    changed_files = apply_result.changed_files if apply_result is not None else []
+    values = {
+        "changed": str(plan.changed).lower(),
+        "python-floor-changed": str(plan.python_change is not None).lower(),
+        "dependency-floors-changed": json.dumps(floors_changed),
+        "files-changed": json.dumps(changed_files),
+        "plan": json.dumps(plan.to_dict()),
+    }
+    with open(output_path, "a", encoding="utf-8") as handle:
+        for key, value in values.items():
+            delimiter = f"dspa-{uuid.uuid4()}"
+            handle.write(f"{key}<<{delimiter}\n{value}\n{delimiter}\n")
+
+
+def main(argv: Sequence[str] | None = None, *, fetcher: ReleaseFetcher | None = None) -> int:
+    """CLI entry point; ``fetcher`` is injectable for tests."""
+    args = build_parser().parse_args(argv)
+    try:
+        reference_date = (
+            parse_iso_date(args.reference_date) if args.reference_date is not None else dt.datetime.now(dt.UTC).date()
+        )
+        document = load_document(args.pyproject)
+        config = load_config(args.pyproject, document, reference_date, _cli_overrides(args))
+        plan = build_plan(document, config, fetcher if fetcher is not None else PyPIReleaseFetcher())
+        apply_result = apply_plan(document, plan, config) if args.mode == "update" else None
+    except DependencyPolicyError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+    plan_json = json.dumps(plan.to_dict(), indent=2)
+    if args.output_json is not None:
+        args.output_json.write_text(plan_json + "\n", encoding="utf-8")
+    if args.mode == "plan":
+        print(plan_json)
+    elif not args.quiet:
+        _summarize(plan, args.mode, apply_result, sys.stdout)
+    _write_github_outputs(plan, apply_result)
+
+    if args.mode == "check" and plan.changed:
+        return EXIT_DRIFT
+    return EXIT_OK
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

dependency_support_policy/config.py

@@ -0,0 +1,195 @@
+"""Run configuration: defaults, the pyproject tool table, and CLI overrides."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from packaging.utils import NormalizedName, canonicalize_name
+
+from .dates import parse_iso_date
+from .errors import ConfigError
+
+TOOL_TABLE = "dependency-support-policy"
+
+_PYTHON_SERIES_RE = re.compile(r"^(\d+)\.(\d+)$")
+
+
+class LockMode(Enum):
+    """How to treat uv.lock after pyproject.toml changes."""
+
+    OFF = "off"
+    MINIMAL = "minimal"
+    UPGRADE = "upgrade"
+
+
+@dataclass(frozen=True)
+class RunConfig:
+    """Fully resolved configuration for one evaluation run."""
+
+    pyproject: Path
+    reference_date: dt.date
+    policy_name: str = "spec0"
+    python_support_months: int | None = None
+    package_support_months: int | None = None
+    package_overrides: Mapping[NormalizedName, int] = field(default_factory=dict)
+    include: frozenset[NormalizedName] | None = None
+    exclude: frozenset[NormalizedName] = frozenset()
+    groups: tuple[str, ...] = ("project",)
+    manage_python: bool = True
+    lock: LockMode = LockMode.OFF
+    python_releases: Mapping[tuple[int, int], dt.date] = field(default_factory=dict)
+
+
+def _require(value: Any, expected: type, key: str) -> Any:
+    if expected is int and isinstance(value, bool):
+        raise ConfigError(f"invalid value for {key!r}: expected {expected.__name__}, got bool")
+    if not isinstance(value, expected):
+        raise ConfigError(f"invalid value for {key!r}: expected {expected.__name__}, got {type(value).__name__}")
+    return value
+
+
+def _positive_months(value: Any, key: str) -> int:
+    months = int(_require(value, int, key))
+    if months <= 0:
+        raise ConfigError(f"invalid value for {key!r}: months must be positive")
+    return months
+
+
+def _name_list(value: Any, key: str) -> frozenset[NormalizedName]:
+    if not isinstance(value, (list, tuple)):
+        raise ConfigError(f"invalid value for {key!r}: expected an array of package names")
+    return frozenset(canonicalize_name(_require(item, str, key)) for item in value)
+
+
+def _parse_python_releases(value: Any, key: str) -> dict[tuple[int, int], dt.date]:
+    if not isinstance(value, Mapping):
+        raise ConfigError(f"invalid value for {key!r}: expected a table of '<major>.<minor>' = date")
+    releases: dict[tuple[int, int], dt.date] = {}
+    for series_text, raw_date in value.items():
+        match = _PYTHON_SERIES_RE.match(str(series_text))
+        if match is None:
+            raise ConfigError(f"invalid Python series {series_text!r} in {key!r}: expected '<major>.<minor>'")
+        if isinstance(raw_date, dt.date) and not isinstance(raw_date, dt.datetime):
+            released = raw_date
+        elif isinstance(raw_date, str):
+            released = parse_iso_date(raw_date)
+        else:
+            raise ConfigError(f"invalid release date for {series_text!r} in {key!r}: expected a date")
+        releases[(int(match.group(1)), int(match.group(2)))] = released
+    return releases
+
+
+def _parse_lock_mode(value: Any, key: str) -> LockMode:
+    text = _require(value, str, key)
+    try:
+        return LockMode(text)
+    except ValueError:
+        options = ", ".join(mode.value for mode in LockMode)
+        raise ConfigError(f"invalid value for {key!r}: expected one of {options}") from None
+
+
+def parse_package_overrides(pairs: Mapping[str, Any]) -> dict[NormalizedName, int]:
+    """Parse a ``name -> months`` mapping, canonicalizing names."""
+    overrides: dict[NormalizedName, int] = {}
+    for name, months in pairs.items():
+        overrides[canonicalize_name(name)] = _positive_months(months, f"package-support.{name}")
+    return overrides
+
+
+def load_config(
+    pyproject: Path,
+    document: Mapping[str, Any],
+    reference_date: dt.date,
+    cli_overrides: Mapping[str, Any] | None = None,
+) -> RunConfig:
+    """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.
+    """
+    overrides = {key: value for key, value in (cli_overrides or {}).items() if value is not None}
+    tool = document.get("tool", {})
+    table = tool.get(TOOL_TABLE, {}) if isinstance(tool, Mapping) else {}
+    if not isinstance(table, Mapping):
+        raise ConfigError(f"[tool.{TOOL_TABLE}] must be a table")
+    known_keys = {
+        "policy",
+        "python-support-months",
+        "package-support-months",
+        "package-support",
+        "include",
+        "exclude",
+        "groups",
+        "manage-python",
+        "lock",
+        "python-releases",
+    }
+    unknown = sorted(set(table) - known_keys)
+    if unknown:
+        raise ConfigError(f"unknown key(s) in [tool.{TOOL_TABLE}]: {', '.join(unknown)}")
+
+    def setting(cli_key: str, table_key: str) -> Any:
+        if cli_key in overrides:
+            return overrides[cli_key]
+        return table.get(table_key)
+
+    policy_name = setting("policy_name", "policy")
+    python_months = setting("python_support_months", "python-support-months")
+    package_months = setting("package_support_months", "package-support-months")
+    package_support = setting("package_overrides", "package-support")
+    include = setting("include", "include")
+    exclude = setting("exclude", "exclude")
+    groups = setting("groups", "groups")
+    manage_python = setting("manage_python", "manage-python")
+    lock = setting("lock", "lock")
+    python_releases = table.get("python-releases")
+
+    if groups is not None:
+        groups_tuple = tuple(_require(item, str, "groups") for item in _require_list(groups, "groups"))
+        if not groups_tuple:
+            raise ConfigError("'groups' must not be empty")
+    else:
+        groups_tuple = ("project",)
+
+    return RunConfig(
+        pyproject=pyproject,
+        reference_date=reference_date,
+        policy_name=_require(policy_name, str, "policy") if policy_name is not None else "spec0",
+        python_support_months=(
+            _positive_months(python_months, "python-support-months") if python_months is not None else None
+        ),
+        package_support_months=(
+            _positive_months(package_months, "package-support-months") if package_months is not None else None
+        ),
+        package_overrides=(
+            parse_package_overrides(_require_mapping(package_support, "package-support"))
+            if package_support is not None
+            else {}
+        ),
+        include=_name_list(include, "include") if include is not None else None,
+        exclude=_name_list(exclude, "exclude") if exclude is not None else frozenset(),
+        groups=groups_tuple,
+        manage_python=bool(_require(manage_python, bool, "manage-python")) if manage_python is not None else True,
+        lock=_parse_lock_mode(lock, "lock") if lock is not None else LockMode.OFF,
+        python_releases=_parse_python_releases(python_releases, "python-releases")
+        if python_releases is not None
+        else {},
+    )
+
+
+def _require_list(value: Any, key: str) -> list[Any]:
+    if not isinstance(value, (list, tuple)):
+        raise ConfigError(f"invalid value for {key!r}: expected an array")
+    return list(value)
+
+
+def _require_mapping(value: Any, key: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ConfigError(f"invalid value for {key!r}: expected a table")
+    return value

dependency_support_policy/dates.py

@@ -0,0 +1,31 @@
+"""Deterministic calendar arithmetic used by support-window calculations."""
+
+from __future__ import annotations
+
+import calendar
+from datetime import date
+
+from .errors import ConfigError
+
+
+def months_before(reference: date, months: int) -> date:
+    """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).
+    """
+    if months < 0:
+        raise ValueError("months must be non-negative")
+    total = reference.year * 12 + reference.month - 1 - months
+    year, month_index = divmod(total, 12)
+    month = month_index + 1
+    day = min(reference.day, calendar.monthrange(year, month)[1])
+    return date(year, month, day)
+
+
+def parse_iso_date(text: str) -> date:
+    """Parse a ``YYYY-MM-DD`` date, raising :class:`ConfigError` on bad input."""
+    try:
+        return date.fromisoformat(text)
+    except ValueError as exc:
+        raise ConfigError(f"invalid date {text!r}: expected YYYY-MM-DD") from exc

dependency_support_policy/errors.py

@@ -0,0 +1,23 @@
+"""Exception hierarchy for dependency-support-policy."""
+
+from __future__ import annotations
+
+
+class DependencyPolicyError(Exception):
+    """Base class for all errors raised by this package."""
+
+
+class ConfigError(DependencyPolicyError):
+    """Invalid configuration (CLI flags, action inputs, or the tool table)."""
+
+
+class RegistryError(DependencyPolicyError):
+    """Failure to retrieve or parse package release metadata."""
+
+
+class PolicyError(DependencyPolicyError):
+    """A support policy could not be evaluated (e.g. no stable releases)."""
+
+
+class LockfileError(DependencyPolicyError):
+    """uv lockfile regeneration failed."""

dependency_support_policy/lockfile.py

@@ -0,0 +1,45 @@
+"""uv lockfile regeneration with rollback on failure."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from .config import LockMode
+from .errors import LockfileError
+
+_UV_TIMEOUT_SECONDS = 600.0
+
+
+def regenerate_lockfile(project_dir: Path, mode: LockMode, *, uv_executable: str = "uv") -> bool:
+    """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.
+    """
+    if mode is LockMode.OFF:
+        return False
+    lock_path = project_dir / "uv.lock"
+    before = lock_path.read_bytes() if lock_path.exists() else None
+    command = [uv_executable, "lock"]
+    if mode is LockMode.UPGRADE:
+        command.append("--upgrade")
+    try:
+        completed = subprocess.run(  # noqa: S603 - fixed argument list, no shell
+            command,
+            cwd=project_dir,
+            capture_output=True,
+            text=True,
+            timeout=_UV_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise LockfileError(f"uv executable not found: {uv_executable!r}") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise LockfileError(f"'{' '.join(command)}' timed out after {_UV_TIMEOUT_SECONDS:.0f}s") from exc
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout or "").strip()
+        raise LockfileError(f"'{' '.join(command)}' failed with exit code {completed.returncode}:\n{detail}")
+    after = lock_path.read_bytes() if lock_path.exists() else None
+    return after != before