check_python_version¶

def check_version_consistency(repo_root: Path) -> list[str]:
    """Check Python version consistency across project files.

    Args:
        repo_root: Root directory of the repository

    Returns:
        List of error messages (empty if consistent)
    """
    python_version = get_python_version_file(repo_root)
    requires_python = get_pyproject_requires_python(repo_root)

    if python_version is None or requires_python is None:
        # One or both files don't specify a version, that's okay
        return []

    # Every clause of a (possibly compound) specifier must be satisfied.
    unsatisfied = any(
        not version_satisfies_constraint(python_version, operator, constraint_version)
        for operator, constraint_version in requires_python
    )
    if not unsatisfied:
        return []

    return [
        f"Python version mismatch: .python-version has {python_version}, "
        f"but pyproject.toml requires-python is {_format_specifier(requires_python)}"
    ]

def get_pyproject_requires_python(repo_root: Path) -> list[tuple[str, str]] | None:
    """Read requires-python constraint(s) from pyproject.toml.

    Args:
        repo_root: Root directory of the repository

    Returns:
        List of (operator, version) clauses, or None if not specified or
        unparseable. A compound specifier yields one entry per comma-separated
        clause, e.g. ">=3.11,<3.14" -> [(">=", "3.11"), ("<", "3.14")].
    """
    # A missing, malformed, unreadable or non-UTF-8 pyproject.toml is treated as
    # "unspecified" rather than crashing the hook; see :mod:`rhiza_hooks._toml`.
    data = load_toml(repo_root / "pyproject.toml")
    if data is None:
        return None

    requires_python = data.get("project", {}).get("requires-python")
    if not requires_python:
        return None

    clauses = _parse_specifier(requires_python)
    # No clause parsed (e.g. "invalid-version"): treat as unspecified.
    return clauses or None

def get_python_version_file(repo_root: Path) -> str | None:
    """Read Python version from .python-version file.

    Args:
        repo_root: Root directory of the repository

    Returns:
        Python version string or None if file doesn't exist
    """
    version_file = repo_root / ".python-version"
    if not version_file.exists():
        return None

    content = version_file.read_text(encoding="utf-8").strip()
    # Extract major.minor version
    match = re.match(r"(\d+\.\d+)", content)
    return match.group(1) if match else content

def main(argv: list[str] | None = None) -> int:
    """Main entry point for the hook."""
    parser = argparse.ArgumentParser(description="Check Python version consistency")
    parser.add_argument(
        "filenames",
        nargs="*",
        help="Filenames (ignored, checks repo root)",
    )
    parser.parse_args(argv)  # validate/consume pre-commit's filename args; result unused

    repo_root = find_repo_root()
    errors = check_version_consistency(repo_root)

    if errors:
        for error in errors:
            print(f"ERROR: {error}", file=sys.stderr)
        return 1

    return 0

def parse_version(version_str: str) -> tuple[int, int]:
    """Parse a version string into a tuple of (major, minor).

    This is deliberately not :func:`rhiza_hooks._version.parse_version`, which the
    Rust and Go hooks share. That one is lenient: it accepts any number of
    components, reads the leading digits of ``"1.21rc1"``, and returns None for
    text with no version in it. This one has a narrower contract: the comparators
    in ``_COMPARATORS`` are typed on ``tuple[int, int]`` and compare exactly
    ``major.minor``, the granularity ``requires-python`` is checked at, so it
    returns a pair and raises on anything else rather than returning a sentinel
    that every comparison would need to handle.

    Args:
        version_str: Version string like "3.11" or "3.12"

    Returns:
        Tuple of (major, minor) integers

    >>> parse_version("3.11")
    (3, 11)
    >>> parse_version("3.12")
    (3, 12)
    """
    normalized = version_str.strip()
    if re.fullmatch(r"\d+\.\d+", normalized) is None:
        msg = f"Invalid version string: {version_str!r}. Expected 'major.minor'."
        raise ValueError(msg)

    parts = normalized.split(".")
    return (int(parts[0]), int(parts[1]))

def version_satisfies_constraint(version: str, operator: str, constraint_version: str) -> bool:
    """Check if a version satisfies a constraint.

    Args:
        version: The version to check (e.g., "3.12")
        operator: The comparison operator (e.g., ">=", "==")
        constraint_version: The version in the constraint (e.g., "3.11")

    Returns:
        True if version satisfies the constraint

    >>> version_satisfies_constraint("3.12", ">=", "3.11")
    True
    >>> version_satisfies_constraint("3.10", ">=", "3.11")
    False

    ``~=`` additionally pins the major component:

    >>> version_satisfies_constraint("3.12", "~=", "3.11")
    True
    >>> version_satisfies_constraint("4.0", "~=", "3.11")
    False

    An operator this hook does not model is treated permissively rather than as a
    violation — the hook reports disagreements it is sure about, not everything it
    cannot parse:

    >>> version_satisfies_constraint("3.10", "<>", "3.11")
    True
    """
    comparator = _COMPARATORS.get(operator)
    if comparator is None:
        # Unknown operator: be permissive.
        return True
    return comparator(parse_version(version), parse_version(constraint_version))