pip_checkcompat.py

#!/usr/bin/env python3
"""Check whether PyPI packages provide compatible wheels.

Usage: python3.14 pip_checkcompat.py (-p PACKAGE | -r REQUIREMENTS) [options]
Requires requests and packaging. Results are supported, unsupported, or
uncertain when only generic wheels or incomplete classifiers are available.
"""

from __future__ import annotations

import argparse
import json
import platform
import re
import sys
from typing import Any

import requests
from packaging.requirements import Requirement
from packaging.specifiers import SpecifierSet
from packaging.version import Version

PYPI_URL_TEMPLATE = "https://pypi.org/pypi/{name}/json"
TIMEOUT = 10.0


def classifiers_support_python_version(
    classifiers: list[str], target_py: tuple[int, int],
) -> bool | None:
    """Return whether classifiers explicitly support the target Python version."""
    if not classifiers:
        return None

    # Keep only classifiers that name a Python version.
    py_classifiers = [c for c in classifiers if c.startswith("Programming Language :: Python ::")]

    if not py_classifiers:
        return None

    # Target version.
    major, minor = target_py
    target_str_full = f"Programming Language :: Python :: {major}.{minor}"
    target_str_major = f"Programming Language :: Python :: {major}"

    if target_str_full in py_classifiers:
        return True

    # Specific versions exist, but none matches the target.
    has_specific_versions = any(
        re.match(r"Programming Language :: Python :: \d+\.\d+$", c) for c in py_classifiers
    )

    if target_str_major in py_classifiers and not has_specific_versions:
        return True

    if has_specific_versions:
        return False

    # No specific Python versions were declared.
    return None

# Environment helpers
def detect_default_python() -> tuple[int, int]:
    v = sys.version_info
    return (v.major, v.minor)


def detect_default_platform_shorthand() -> str:
    system = platform.system().lower()
    if system.startswith("win"):
        return "win"
    if system.startswith("darwin") or system.startswith("mac"):
        return "macosx"
    if system.startswith("linux"):
        return "linux"
    return system


# === PyPI ===
def fetch_pypi_json(name: str) -> dict | None:
    url = PYPI_URL_TEMPLATE.format(name=name)
    try:
        r = requests.get(url, timeout=TIMEOUT)
        if r.status_code == 200:
            return r.json()
        return None
    except Exception:
        return None


def choose_version_from_info(info: dict, requirement: Requirement | None) -> str | None:
    if requirement and requirement.specifier:
        for spec in requirement.specifier:
            if spec.operator == "==":
                return spec.version
    return info.get("version")


# Wheel analysis
def parse_wheel_tags_from_filename(filename: str) -> tuple[str, str, str] | None:
    if not filename.endswith(".whl"):
        return None
    base = filename[:-4]
    parts = base.split("-")
    if len(parts) < 5:
        return None
    python_tag, abi_tag, platform_tag = parts[-3:]
    return python_tag, abi_tag, platform_tag


def python_tag_matches(python_tag: str, target_py: tuple[int, int]) -> bool:
    maj, mino = target_py
    cp_tag = f"cp{maj}{mino}"
    tokens = python_tag.split(".")
    for t in tokens:
        t = t.lower()
        if t in ("py3", "py2.py3") and maj == 3:
            return True
        if t == cp_tag:
            return True
        if t.startswith("py") and len(t) > 2 and t[2:] == f"{maj}{mino}":
            return True
    return False


def platform_tag_matches(platform_tag: str, requested_platform_sh: str) -> bool:
    requested = requested_platform_sh.lower()
    pt = platform_tag.lower()
    if pt == "any":
        return True
    if requested == "linux" and ("manylinux" in pt or "musllinux" in pt or "linux" in pt):
        return True
    if requested == "macosx" and "macosx" in pt:
        return True
    if requested == "win" and "win" in pt:
        return True
    return requested in pt

def is_version_compatible(requires_python: str | None, version: tuple[int, int]) -> bool:
    """Return whether a major/minor Python version satisfies requires-python."""
    # Expand the version to three components.
    v_tuple = (*version, 0)  # (3,10) -> (3,10,0)
    ver_str = ".".join(map(str, v_tuple))
    if not requires_python:
        return True
    spec_set = SpecifierSet(requires_python)
    return Version(ver_str) in spec_set


# Package analysis
def analyze_package(
    name: str,
    requirement: Requirement | None,
    target_py: tuple[int, int],
    requested_platform_sh: str,
) -> dict[str, Any]:
    data = fetch_pypi_json(name)
    if not data:
        return {"name": name, "error": "package_not_found_on_pypi"}

    info = data.get("info", {})
    chosen_version = choose_version_from_info(info, requirement)
    releases = data.get("releases", {})
    release_files = releases.get(chosen_version, [])
    classifiers = info.get("classifiers", [])
    requires_python = info.get("requires_python")

    matching = []
    generic = []
    only_sources = all(f.get("packagetype") != "bdist_wheel" for f in release_files) \
        and len(release_files)
    for f in release_files:
        if f.get("packagetype") != "bdist_wheel":
            continue
        filename = f.get("filename", "")
        tags = parse_wheel_tags_from_filename(filename)
        if not tags:
            continue
        py_tag, abi_tag, plat_tag = tags
        if (python_tag_matches(py_tag, target_py) or abi_tag == "abi3") and platform_tag_matches(
            plat_tag, requested_platform_sh,
        ):
            matching.append(filename)
        elif py_tag in ("py3", "py2.py3", "py2", "py"):
            generic.append(filename)

    if only_sources:
        status = "uncertain"
        reason = "no_wheels_sourcecode_is_present"
    elif not classifiers_support_python_version(classifiers, target_py) and only_sources:
        status = "uncertain"
        reason = "no_wheel_and_no_explicit_python_classifier"
    elif (matching or generic) and is_version_compatible(requires_python, target_py):
        status = "supported"
        reason = "wheel_found"
    else:
        status = "unsupported"
        reason = "no_compatible_wheel"

    return {
        "name": name,
        "requirement": str(requirement) if requirement else name,
        "chosen_version": chosen_version,
        "status": status,
        "check_py_version": ".".join(map(str, target_py)),
        "reason": reason,
        "matching_wheels": matching,
        "generic_wheels": generic,
        "requires_python": requires_python,
        "wheel_count": len([f for f in release_files if f.get("packagetype") == "bdist_wheel"]),
    }


# requirements.txt parsing
def parse_requirements_file(path: str) -> list[Requirement]:
    reqs = []
    with open(path, encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if not line or line.startswith("#"):
                continue
            try:
                reqs.append(Requirement(line))
            except ValueError as exc:
                print(f"Warning: skipping invalid requirement {line!r}: {exc}", file=sys.stderr)
    return reqs


# CLI
def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(
        description="Check PyPI packages for wheel support on given Python version/platform.",
    )
    g = p.add_mutually_exclusive_group(required=True)
    g.add_argument("-p", "--package", help="single package name (optionally with specifier)")
    g.add_argument("-r", "--requirements", help="path to requirements.txt")
    p.add_argument("--python", help="target Python version, e.g. 3.10 (default: current)")
    p.add_argument("--platform", help="target platform shorthand (linux, win, macosx)")
    p.add_argument("--json", action="store_true", help="output JSON report")
    args = p.parse_args(argv)

    if args.python:
        py_version: tuple[int, int] = tuple(map(int, args.python.split("."))) # pyright: ignore[reportAssignmentType]
        if len(py_version) != 2 and py_version:
            print("Error: incorrect version number. Right example: 3.12", file=sys.stderr)
        target_py: tuple[int, int] = py_version
    else:
        target_py = detect_default_python()

    requested_platform = args.platform or detect_default_platform_shorthand()

    if args.package:
        reqs = [Requirement(args.package)]
    else:
        reqs = parse_requirements_file(args.requirements)

    results = [analyze_package(r.name, r, target_py, requested_platform) for r in reqs]

    if args.json:
        print(json.dumps(results, ensure_ascii=False, indent=2))
        return 0

    # Human-readable output.
    if args.requirements:
        for r in results:
            if not r.get("status"):
                continue
            mark = {
                "supported": "✅ OK",
                "unsupported": "❌ NO",
                "uncertain": "⚠️  UNCERTAIN",
            }.get(r["status"], r["status"])
            print(f"{r['name']:25} {mark:12} ({r['reason']})")
    else:
        r = results[0]
        print(f"Package: {r['name']}")
        print(f"  chosen_version: {r['chosen_version']}")
        print(f"  check_py_version: {r['check_py_version']}")
        print(f"  declared_minimal_python_version: {r['requires_python']}")
        print(f"  status: {r['status']}")
        print(f"  reason: {r['reason']}")
        if r.get("matching_wheels", []):
            print("  matching wheels:")
            for w in r.get("matching_wheels", []):
                print("    -", w)
        print(f"  total_wheels: {r['wheel_count']}")
        if r["status"] == "uncertain":
            print("  ⚠️  Found only generic wheels (py3-none-any) or source code files and no specific Python version classifiers.")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())