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

tnfr/__init__.py

@@ -1,89 +1,91 @@
-
-from __future__ import annotations
-"""
-TNFR — Teoría de la Naturaleza Fractal Resonante
-API pública del paquete.
-
-Ecuación nodal:
-    ∂EPI/∂t = νf · ΔNFR(t)
-"""
-
-__version__ = "4.5.0"
-
-# Re-exports de la API pública
-from .dynamics import step, run, set_delta_nfr_hook, validate_canon
-from .ontosim import preparar_red
-from .observers import attach_standard_observer, coherencia_global, orden_kuramoto
-from .gamma import GAMMA_REGISTRY, eval_gamma, kuramoto_R_psi
-from .grammar import enforce_canonical_grammar, on_applied_glifo
-from .sense import (
-    GLYPHS_CANONICAL, glyph_angle, glyph_unit,
-    sigma_vector_node, sigma_vector_global,
-    push_sigma_snapshot, sigma_series, sigma_rose,
-    register_sigma_callback,
-)
-from .metrics import (
-    register_metrics_callbacks,
-    Tg_global, Tg_by_node,
-    latency_series, glifogram_series,
-    glyph_top, glyph_dwell_stats, export_history,
-)
-from .operators import aplicar_remesh_red_topologico
-from .trace import register_trace
-from .program import play, seq, block, target, wait, THOL, TARGET, WAIT, ejemplo_canonico_basico
-from .cli import main as cli_main
-from .scenarios import build_graph
-from .presets import get_preset
-from .types import NodeState
-from .structural import (
-    create_nfr,
-    Operador,
-    Emision,
-    Recepcion,
-    Coherencia,
-    Disonancia,
-    Acoplamiento,
-    Resonancia,
-    Silencio,
-    Expansion,
-    Contraccion,
-    Autoorganizacion,
-    Mutacion,
-    Transicion,
-    Recursividad,
-    OPERADORES,
-    validate_sequence,
-    run_sequence,
-)
-
-
-__all__ = [
-    "preparar_red",
-    "step", "run", "set_delta_nfr_hook", "validate_canon",
-
-    "attach_standard_observer", "coherencia_global", "orden_kuramoto",
-    "GAMMA_REGISTRY", "eval_gamma", "kuramoto_R_psi",
-    "enforce_canonical_grammar", "on_applied_glifo",
-    "GLYPHS_CANONICAL", "glyph_angle", "glyph_unit",
-    "sigma_vector_node", "sigma_vector_global",
-    "push_sigma_snapshot", "sigma_series", "sigma_rose",
-    "register_sigma_callback",
-    "register_metrics_callbacks",
-    "register_trace",
-    "Tg_global", "Tg_by_node",
-    "latency_series", "glifogram_series",
-    "glyph_top", "glyph_dwell_stats",
-    "export_history",
-    "aplicar_remesh_red_topologico",
-    "play", "seq", "block", "target", "wait", "THOL", "TARGET", "WAIT",
-    "cli_main", "build_graph", "get_preset", "NodeState",
-    "ejemplo_canonico_basico",
-    "create_nfr",
-    "Operador", "Emision", "Recepcion", "Coherencia", "Disonancia",
-    "Acoplamiento", "Resonancia", "Silencio", "Expansion", "Contraccion",
-    "Autoorganizacion", "Mutacion", "Transicion", "Recursividad",
-    "OPERADORES", "validate_sequence", "run_sequence",
-    "__version__",
-]
-
-
+"""Minimal public API for :mod:`tnfr`.
+
+This package only re-exports a handful of high level helpers.  Most
+functionality lives in submodules that should be imported directly, for
+example :mod:`tnfr.metrics`, :mod:`tnfr.observers` or the DSL utilities
+in :mod:`tnfr.tokens`, :mod:`tnfr.flatten` and :mod:`tnfr.execution`.
+Recommended entry points are:
+
+- ``step`` and ``run`` in :mod:`tnfr.dynamics`
+- ``preparar_red`` in :mod:`tnfr.ontosim`
+- ``create_nfr`` and ``run_sequence`` in :mod:`tnfr.structural`
+- ``cached_import`` and ``prune_failed_imports`` for optional dependencies
+"""
+
+from __future__ import annotations
+
+from .import_utils import cached_import, prune_failed_imports
+from .ontosim import preparar_red
+
+
+def _missing_dependency(name: str, exc: ImportError):
+    def _stub(*args, **kwargs):
+        raise ImportError(
+            f"{name} is unavailable because required dependencies could not be imported. "
+            f"Original error ({exc.__class__.__name__}): {exc}. "
+            "Install the missing packages (e.g. 'networkx' or grammar modules)."
+        ) from exc
+
+    return _stub
+
+
+try:  # pragma: no cover - exercised in import tests
+    from .dynamics import step, run
+except ImportError as exc:  # pragma: no cover - no missing deps in CI
+    step = _missing_dependency("step", exc)
+    run = _missing_dependency("run", exc)
+
+
+_HAS_RUN_SEQUENCE = False
+try:  # pragma: no cover - exercised in import tests
+    from .structural import create_nfr, run_sequence
+except ImportError as exc:  # pragma: no cover - no missing deps in CI
+    create_nfr = _missing_dependency("create_nfr", exc)
+    run_sequence = _missing_dependency("run_sequence", exc)
+else:
+    _HAS_RUN_SEQUENCE = True
+
+
+_metadata = cached_import("importlib.metadata")
+if _metadata is None:  # pragma: no cover
+    _metadata = cached_import("importlib_metadata")
+
+if _metadata is not None:  # pragma: no cover
+    version = _metadata.version  # type: ignore[attr-defined]
+    PackageNotFoundError = _metadata.PackageNotFoundError  # type: ignore[attr-defined]
+else:  # pragma: no cover
+
+    class PackageNotFoundError(Exception):
+        pass
+
+    def version(_: str) -> str:
+        raise PackageNotFoundError
+
+
+try:
+    __version__ = version("tnfr")
+except PackageNotFoundError:  # pragma: no cover
+    tomllib = cached_import("tomllib")
+    if tomllib is not None:
+        from pathlib import Path
+
+        try:
+            with (Path(__file__).resolve().parents[2] / "pyproject.toml").open(
+                "rb",
+            ) as f:
+                __version__ = tomllib.load(f)["project"]["version"]
+        except (OSError, KeyError, ValueError):  # pragma: no cover
+            __version__ = "0+unknown"
+    else:  # pragma: no cover
+        __version__ = "0+unknown"
+
+__all__ = [
+    "__version__",
+    "step",
+    "run",
+    "preparar_red",
+    "create_nfr",
+]
+
+if _HAS_RUN_SEQUENCE:
+    __all__.append("run_sequence")