compat.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/compat.py
 
"""
Purpose
-------
Provide a version-compatibility check between OCT and the ``oc_diagnostics``
runtime package.
 
Responsibilities
----------------
- Define the supported ``oc_diagnostics`` version range.
- Query the installed ``oc_diagnostics`` version via ``importlib.metadata``.
- Return a human-readable warning or info string when the installed version
  is out of range or absent; return ``None`` when compatible.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- Must not import ``oc_diagnostics`` directly; ``_dbg`` arrives through
  the fail-soft ``oct.core.diagnostics`` shim, and the installed version
  is read from metadata rather than by importing the package.
- Must not require the ``packaging`` library; uses tuple-based comparison.
- Must be safe to call when ``oc_diagnostics`` is not installed.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
from oct.core.diagnostics import _dbg
 
_OC_DIAGNOSTICS_COMPAT = {"min": "2.0.0", "max": "3.0.0"}
 
 
def _parse_version_tuple(v: str) -> tuple[int, ...]:
    """Convert a dotted version string to a tuple of ints for comparison."""
    parts: list[int] = []
    for segment in v.split("."):
        digits = ""
        for ch in segment:
            if ch.isdigit():
                digits += ch
            else:
                break
        parts.append(int(digits) if digits else 0)
    return tuple(parts)
 
 
def check_oc_diagnostics_compat() -> str | None:
    """
    Check whether the installed ``oc_diagnostics`` version is within the
    supported range.
 
    Returns
    -------
    str or None
        A warning/info message if out of range or not installed.
        ``None`` if the version is compatible.
    """
    func = "check_oc_diagnostics_compat"
    _dbg("OCT-CORE", func, "checking the installed oc_diagnostics version", 3)
    try:
        from importlib.metadata import version as _pkg_version
        installed = _pkg_version("oc_diagnostics")
    except Exception:
        return (
            "Info: oc_diagnostics is not installed. "
            "Projects created by OCT require oc_diagnostics at runtime."
        )
 
    try:
        v = _parse_version_tuple(installed)
        v_min = _parse_version_tuple(_OC_DIAGNOSTICS_COMPAT["min"])
        v_max = _parse_version_tuple(_OC_DIAGNOSTICS_COMPAT["max"])
    except (ValueError, TypeError):
        return f"Warning: Could not parse oc_diagnostics version '{installed}'."
 
    if v < v_min:
        return (
            f"Warning: oc_diagnostics {installed} is below the minimum "
            f"supported version ({_OC_DIAGNOSTICS_COMPAT['min']}). "
            f"Consider upgrading."
        )
 
    if v >= v_max:
        return (
            f"Warning: oc_diagnostics {installed} is at or above the maximum "
            f"tested version ({_OC_DIAGNOSTICS_COMPAT['max']}). "
            f"OCT may need an update."
        )
 
    return None