runtime_compat

 1"""Runtime compatibility checks for supported Python versions.
 2
 3Ensures that AIFT is only executed under a supported Python interpreter
 4(currently 3.10 through 3.13 inclusive). This module is imported early in
 5the startup sequence -- before any third-party packages -- so that users
 6receive a clear error message instead of cryptic import failures.
 7
 8Attributes:
 9    SUPPORTED_PYTHON_MIN: Minimum supported Python version as a ``(major, minor)`` tuple.
10    SUPPORTED_PYTHON_MAX_EXCLUSIVE: First unsupported Python version (exclusive upper bound).
11"""
12
13from __future__ import annotations
14
15import sys
16
17SUPPORTED_PYTHON_MIN = (3, 10)
18SUPPORTED_PYTHON_MAX_EXCLUSIVE = (3, 14)
19
20
21class UnsupportedPythonVersionError(RuntimeError):
22    """Raised when the active Python runtime is unsupported."""
23
24
25def _format_version(version_info: tuple[int, int, int]) -> str:
26    """Format a version tuple as a dotted string (e.g. ``3.10.12``)."""
27    return f"{version_info[0]}.{version_info[1]}.{version_info[2]}"
28
29
30def _supported_range_label() -> str:
31    """Return a human-readable label for the supported version range (e.g. ``3.10-3.13``)."""
32    max_minor = SUPPORTED_PYTHON_MAX_EXCLUSIVE[1] - 1
33    return f"{SUPPORTED_PYTHON_MIN[0]}.{SUPPORTED_PYTHON_MIN[1]}-{SUPPORTED_PYTHON_MAX_EXCLUSIVE[0]}.{max_minor}"
34
35
36def assert_supported_python_version(version_info: tuple[int, int, int] | None = None) -> None:
37    """Validate that the current Python version is within the supported range.
38
39    Args:
40        version_info: Optional explicit version tuple ``(major, minor, micro)``.
41            Defaults to ``sys.version_info[:3]`` when *None*.
42
43    Raises:
44        UnsupportedPythonVersionError: If the version falls outside the
45            ``[SUPPORTED_PYTHON_MIN, SUPPORTED_PYTHON_MAX_EXCLUSIVE)`` range.
46    """
47    current_version = tuple(version_info or sys.version_info[:3])
48    if current_version < SUPPORTED_PYTHON_MIN or current_version >= SUPPORTED_PYTHON_MAX_EXCLUSIVE:
49        detected = _format_version(current_version)
50        supported = _supported_range_label()
51        raise UnsupportedPythonVersionError(
52            f"Unsupported Python version detected: {detected}. "
53            f"AIFT currently supports Python {supported}. "
54            "Install Python 3.13 and recreate the virtual environment (.venv)."
55        )