tnfr 4.5.2__py3-none-any.whl → 6.0.0__py3-none-any.whl

tnfr/io.py

@@ -1,9 +1,9 @@
 """Structured file I/O utilities.
 
 Optional parsers such as ``tomllib``/``tomli`` and ``pyyaml`` are loaded via
-the :func:`tnfr.import_utils.cached_import` helper. Their import results and
+the :func:`tnfr.utils.cached_import` helper. Their import results and
 failure states are cached and can be cleared with
-``cached_import.cache_clear()`` and :func:`tnfr.import_utils.prune_failed_imports`
+``cached_import.cache_clear()`` and :func:`tnfr.utils.prune_failed_imports`
 when needed.
 """
 
@@ -16,8 +16,7 @@ from pathlib import Path
 from typing import Any, Callable
 from functools import partial
 
-from .import_utils import cached_import
-from .logging_utils import get_logger
+from .utils import LazyImportProxy, cached_import, get_logger
 
 
 def _raise_import_error(name: str, *_: Any, **__: Any) -> Any:
@@ -37,47 +36,72 @@ _MISSING_YAML_ERROR = type(
 )
 
 
+def _resolve_lazy(value: Any) -> Any:
+    if isinstance(value, LazyImportProxy):
+        return value.resolve()
+    return value
+
+
+class _LazyBool:
+    __slots__ = ("_value",)
+
+    def __init__(self, value: Any) -> None:
+        self._value = value
+
+    def __bool__(self) -> bool:
+        return _resolve_lazy(self._value) is not None
+
+
+_TOMLI_MODULE = cached_import("tomli", emit="log", lazy=True)
 tomllib = cached_import(
     "tomllib",
     emit="log",
-    fallback=cached_import("tomli", emit="log"),
+    lazy=True,
+    fallback=_TOMLI_MODULE,
 )
-has_toml = tomllib is not None
+has_toml = _LazyBool(tomllib)
 
 
+_TOMLI_TOML_ERROR = cached_import(
+    "tomli",
+    "TOMLDecodeError",
+    emit="log",
+    lazy=True,
+    fallback=_MISSING_TOML_ERROR,
+)
 TOMLDecodeError = cached_import(
     "tomllib",
     "TOMLDecodeError",
     emit="log",
-    fallback=cached_import(
-        "tomli",
-        "TOMLDecodeError",
-        emit="log",
-        fallback=_MISSING_TOML_ERROR,
-    ),
+    lazy=True,
+    fallback=_TOMLI_TOML_ERROR,
 )
 
 
+_TOMLI_LOADS = cached_import(
+    "tomli",
+    "loads",
+    emit="log",
+    lazy=True,
+    fallback=partial(_raise_import_error, "tomllib/tomli"),
+)
 _TOML_LOADS: Callable[[str], Any] = cached_import(
     "tomllib",
     "loads",
     emit="log",
-    fallback=cached_import(
-        "tomli",
-        "loads",
-        emit="log",
-        fallback=partial(_raise_import_error, "tomllib/tomli"),
-    ),
+    lazy=True,
+    fallback=_TOMLI_LOADS,
 )
 
 
-yaml = cached_import("yaml", emit="log")
+yaml = cached_import("yaml", emit="log", lazy=True)
 
 
 YAMLError = cached_import(
     "yaml",
     "YAMLError",
     emit="log",
+    lazy=True,
     fallback=_MISSING_YAML_ERROR,
 )
 
@@ -86,6 +110,7 @@ _YAML_SAFE_LOAD: Callable[[str], Any] = cached_import(
     "yaml",
     "safe_load",
     emit="log",
+    lazy=True,
     fallback=partial(_raise_import_error, "pyyaml"),
 )
 
@@ -115,28 +140,73 @@ def _get_parser(suffix: str) -> Callable[[str], Any]:
         raise ValueError(f"Unsupported suffix: {suffix}") from exc
 
 
-ERROR_MESSAGES = {
+_BASE_ERROR_MESSAGES: dict[type[BaseException], str] = {
     OSError: "Could not read {path}: {e}",
     UnicodeDecodeError: "Encoding error while reading {path}: {e}",
     json.JSONDecodeError: "Error parsing JSON file at {path}: {e}",
-    YAMLError: "Error parsing YAML file at {path}: {e}",
     ImportError: "Missing dependency parsing {path}: {e}",
 }
-if has_toml:
-    ERROR_MESSAGES[TOMLDecodeError] = "Error parsing TOML file at {path}: {e}"
+
+
+def _resolve_exception_type(candidate: Any) -> type[BaseException] | None:
+    resolved = _resolve_lazy(candidate)
+    if isinstance(resolved, type) and issubclass(resolved, BaseException):
+        return resolved
+    return None
+
+
+_OPTIONAL_ERROR_MESSAGE_FACTORIES: tuple[
+    tuple[Callable[[], type[BaseException] | None], str],
+    ...,
+] = (
+    (lambda: _resolve_exception_type(YAMLError), "Error parsing YAML file at {path}: {e}"),
+    (lambda: _resolve_exception_type(TOMLDecodeError), "Error parsing TOML file at {path}: {e}"),
+)
+
+
+_BASE_STRUCTURED_EXCEPTIONS = (
+    OSError,
+    UnicodeDecodeError,
+    json.JSONDecodeError,
+    ImportError,
+)
+
+
+def _iter_optional_exceptions() -> list[type[BaseException]]:
+    errors: list[type[BaseException]] = []
+    for resolver, _ in _OPTIONAL_ERROR_MESSAGE_FACTORIES:
+        exc_type = resolver()
+        if exc_type is not None:
+            errors.append(exc_type)
+    return errors
+
+
+def _is_structured_error(exc: Exception) -> bool:
+    if isinstance(exc, _BASE_STRUCTURED_EXCEPTIONS):
+        return True
+    for optional_exc in _iter_optional_exceptions():
+        if isinstance(exc, optional_exc):
+            return True
+    return False
 
 
 def _format_structured_file_error(path: Path, e: Exception) -> str:
-    for exc, msg in ERROR_MESSAGES.items():
+    for exc, msg in _BASE_ERROR_MESSAGES.items():
         if isinstance(e, exc):
             return msg.format(path=path, e=e)
+
+    for resolver, msg in _OPTIONAL_ERROR_MESSAGE_FACTORIES:
+        exc_type = resolver()
+        if exc_type is not None and isinstance(e, exc_type):
+            return msg.format(path=path, e=e)
+
     return f"Error parsing {path}: {e}"
 
 
 class StructuredFileError(Exception):
     """Error while reading or parsing a structured file."""
 
-    def __init__(self, path: Path, original: Exception):
+    def __init__(self, path: Path, original: Exception) -> None:
         super().__init__(_format_structured_file_error(path, original))
         self.path = path
 
@@ -151,15 +221,10 @@ def read_structured_file(path: Path) -> Any:
     try:
         text = path.read_text(encoding="utf-8")
         return parser(text)
-    except (
-        OSError,
-        UnicodeDecodeError,
-        json.JSONDecodeError,
-        YAMLError,
-        TOMLDecodeError,
-        ImportError,
-    ) as e:
-        raise StructuredFileError(path, e) from e
+    except Exception as e:
+        if _is_structured_error(e):
+            raise StructuredFileError(path, e) from e
+        raise
 
 
 logger = get_logger(__name__)

tnfr/io.pyi

@@ -0,0 +1,11 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+StructuredFileError: Any
+TOMLDecodeError: Any
+YAMLError: Any
+read_structured_file: Any
+safe_write: Any

tnfr/locking.pyi

@@ -0,0 +1,7 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+get_lock: Any

tnfr/metrics/__init__.pyi

@@ -0,0 +1,20 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+Tg_by_node: Any
+Tg_global: Any
+build_metrics_summary: Any
+coherence_matrix: Any
+dissonance_events: Any
+export_metrics: Any
+glyph_top: Any
+glyphogram_series: Any
+latency_series: Any
+local_phase_sync: Any
+local_phase_sync_weighted: Any
+register_coherence_callbacks: Any
+register_diagnosis_callbacks: Any
+register_metrics_callbacks: Any