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

tnfr/__init__.py

@@ -4,88 +4,267 @@ 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
+Exported helpers and their dependencies
+---------------------------------------
+The :data:`EXPORT_DEPENDENCIES` mapping enumerates which internal
+submodules and third-party packages are required to load each helper.
+The imports are grouped as follows:
+
+``step`` / ``run``
+    Provided by :mod:`tnfr.dynamics`.  These helpers rely on the
+    machinery defined within the :mod:`tnfr.dynamics` package (operator
+    orchestration, validation hooks and metrics integration) and require
+    the ``networkx`` package for graph handling.
+
+``prepare_network``
+    Defined in :mod:`tnfr.ontosim`.  Besides :mod:`tnfr.ontosim`
+    itself, the helper imports :mod:`tnfr.callback_utils`,
+    :mod:`tnfr.constants`, :mod:`tnfr.dynamics`, :mod:`tnfr.glyph_history`,
+    :mod:`tnfr.initialization` and :mod:`tnfr.utils` to assemble the
+    graph preparation pipeline.  It also requires ``networkx`` at import
+    time.
+
+``create_nfr`` / ``run_sequence``
+    Re-exported from :mod:`tnfr.structural`.  They depend on
+    :mod:`tnfr.structural`, :mod:`tnfr.constants`, :mod:`tnfr.dynamics`,
+    :mod:`tnfr.operators.definitions`, :mod:`tnfr.operators.registry` and
+    :mod:`tnfr.validation`, and additionally require the ``networkx``
+    package.
+
+``cached_import`` and ``prune_failed_imports`` remain available from
+``tnfr.utils`` for optional dependency management.
 """
 
 from __future__ import annotations
 
-from .import_utils import cached_import, prune_failed_imports
-from .ontosim import preparar_red
+import warnings
+from importlib import import_module, metadata
+from importlib.metadata import PackageNotFoundError
+from typing import Any, Callable, NoReturn
+
+
+EXPORT_DEPENDENCIES: dict[str, dict[str, tuple[str, ...]]] = {
+    "step": {
+        "submodules": ("tnfr.dynamics",),
+        "third_party": ("networkx",),
+    },
+    "run": {
+        "submodules": ("tnfr.dynamics",),
+        "third_party": ("networkx",),
+    },
+    "prepare_network": {
+        "submodules": (
+            "tnfr.ontosim",
+            "tnfr.callback_utils",
+            "tnfr.constants",
+            "tnfr.dynamics",
+            "tnfr.glyph_history",
+            "tnfr.initialization",
+            "tnfr.utils",
+        ),
+        "third_party": ("networkx",),
+    },
+    "create_nfr": {
+        "submodules": (
+            "tnfr.structural",
+            "tnfr.constants",
+            "tnfr.dynamics",
+            "tnfr.operators.definitions",
+            "tnfr.operators.registry",
+            "tnfr.validation",
+        ),
+        "third_party": ("networkx",),
+    },
+    "run_sequence": {
+        "submodules": (
+            "tnfr.structural",
+            "tnfr.constants",
+            "tnfr.dynamics",
+            "tnfr.operators.definitions",
+            "tnfr.operators.registry",
+            "tnfr.validation",
+        ),
+        "third_party": ("networkx",),
+    },
+}
+
+
+try:  # pragma: no cover - exercised in version resolution tests
+    __version__ = metadata.version("tnfr")
+except PackageNotFoundError:  # pragma: no cover - fallback tested explicitly
+    from ._version import __version__ as _fallback_version
+
+    __version__ = _fallback_version
 
 
-def _missing_dependency(name: str, exc: ImportError):
-    def _stub(*args, **kwargs):
+def _is_internal_import_error(exc: ImportError) -> bool:
+    missing_name = getattr(exc, "name", None) or ""
+    if missing_name.startswith("tnfr"):
+        return True
+
+    module_name = getattr(exc, "module", None) or ""
+    if module_name.startswith("tnfr"):
+        return True
+
+    missing_path = getattr(exc, "path", None) or ""
+    if missing_path:
+        normalized = missing_path.replace("\\", "/")
+        if "/tnfr/" in normalized or normalized.endswith("/tnfr"):
+            return True
+
+    message = str(exc)
+    lowered = message.lower()
+    mentions_base_package = "module 'tnfr'" in lowered or 'module "tnfr"' in lowered
+    if ("tnfr." in message or mentions_base_package) and (
+        "circular import" in lowered or "partially initialized module" in lowered
+    ):
+        return True
+
+    return False
+
+
+def _missing_dependency(
+    name: str, exc: ImportError, *, module: str | None = None
+) -> Callable[..., NoReturn]:
+    missing_name = getattr(exc, "name", None)
+
+    def _stub(*args: Any, **kwargs: Any) -> NoReturn:
         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
 
+    _stub.__tnfr_missing_dependency__ = {
+        "export": name,
+        "module": module,
+        "missing": missing_name,
+    }
     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)
+_MISSING_EXPORTS: dict[str, dict[str, Any]] = {}
+
 
+class ExportDependencyError(RuntimeError):
+    """Raised when the export dependency manifest is inconsistent."""
 
-_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
 
+def _validate_export_dependencies() -> None:
+    """Ensure exported helpers and their manifest entries stay in sync."""
 
-_metadata = cached_import("importlib.metadata")
-if _metadata is None:  # pragma: no cover
-    _metadata = cached_import("importlib_metadata")
+    if "__all__" not in globals():
+        # Defensive guard for unusual import orders (should never trigger).
+        return
 
-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
+    issues: list[str] = []
+    manifest = EXPORT_DEPENDENCIES
+    export_names = [name for name in __all__ if name != "__version__"]
+    manifest_names = set(manifest)
 
-    class PackageNotFoundError(Exception):
-        pass
+    for export_name in export_names:
+        if export_name not in manifest:
+            issues.append(
+                f"helper '{export_name}' is exported via __all__ but missing from EXPORT_DEPENDENCIES"
+            )
+            continue
 
-    def version(_: str) -> str:
-        raise PackageNotFoundError
+        entry = manifest[export_name]
+        if not isinstance(entry, dict):
+            issues.append(
+                f"helper '{export_name}' has a malformed manifest entry (expected mapping, got {type(entry)!r})"
+            )
+            continue
 
+        for key in ("submodules", "third_party"):
+            value = entry.get(key)
+            if not value:
+                issues.append(
+                    f"helper '{export_name}' is missing '{key}' dependencies in EXPORT_DEPENDENCIES"
+                )
 
-try:
-    __version__ = version("tnfr")
-except PackageNotFoundError:  # pragma: no cover
-    tomllib = cached_import("tomllib")
-    if tomllib is not None:
-        from pathlib import Path
+    missing_exports = manifest_names.difference(export_names).difference(_MISSING_EXPORTS)
+    for manifest_only in sorted(missing_exports):
+        entry = manifest[manifest_only]
+        if not isinstance(entry, dict):
+            issues.append(
+                f"helper '{manifest_only}' has a malformed manifest entry (expected mapping, got {type(entry)!r})"
+            )
+            continue
+
+        for key in ("submodules", "third_party"):
+            value = entry.get(key)
+            if not value:
+                issues.append(
+                    f"helper '{manifest_only}' is missing '{key}' dependencies in EXPORT_DEPENDENCIES"
+                )
+
+        issues.append(
+            f"helper '{manifest_only}' is listed in EXPORT_DEPENDENCIES but not exported via __all__"
+        )
+
+    if issues:
+        raise ExportDependencyError(
+            "Invalid TNFR export dependency manifest:\n- " + "\n- ".join(issues)
+        )
+
+
+def _assign_exports(module: str, names: tuple[str, ...]) -> bool:
+    try:  # pragma: no cover - exercised in import tests
+        mod = import_module(f".{module}", __name__)
+    except ImportError as exc:  # pragma: no cover - no missing deps in CI
+        if _is_internal_import_error(exc):
+            raise
+        for export_name in names:
+            stub = _missing_dependency(export_name, exc, module=module)
+            globals()[export_name] = stub
+            _MISSING_EXPORTS[export_name] = getattr(
+                stub, "__tnfr_missing_dependency__", {}
+            )
+        return False
+    else:
+        for export_name in names:
+            globals()[export_name] = getattr(mod, export_name)
+        return True
+
+
+_assign_exports("dynamics", ("step", "run"))
+
+
+_HAS_PREPARE_NETWORK = _assign_exports("ontosim", ("prepare_network",))
+
+
+_HAS_RUN_SEQUENCE = _assign_exports("structural", ("create_nfr", "run_sequence"))
+
+
+def _emit_missing_dependency_warning() -> None:
+    if not _MISSING_EXPORTS:
+        return
+    details = ", ".join(
+        f"{name} (missing: {info.get('missing') or 'unknown'})"
+        for name, info in sorted(_MISSING_EXPORTS.items())
+    )
+    warnings.warn(
+        "TNFR helpers disabled because dependencies are missing: " + details,
+        ImportWarning,
+        stacklevel=2,
+    )
+
+
+_emit_missing_dependency_warning()
 
-        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",
+    "prepare_network",
     "create_nfr",
 ]
 
 if _HAS_RUN_SEQUENCE:
     __all__.append("run_sequence")
+
+
+_validate_export_dependencies()

tnfr/__init__.pyi

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, NoReturn
+
+from .dynamics import run, step
+from .ontosim import prepare_network
+from .structural import create_nfr, run_sequence
+
+EXPORT_DEPENDENCIES: dict[str, dict[str, tuple[str, ...]]]
+"""Manifest describing required submodules and third-party packages."""
+
+_MISSING_EXPORTS: dict[str, dict[str, Any]]
+
+__version__: str
+__all__: list[str]
+
+
+class ExportDependencyError(RuntimeError):
+    """Raised when the export dependency manifest is inconsistent."""
+
+
+def _is_internal_import_error(exc: ImportError) -> bool: ...
+
+def _missing_dependency(
+    name: str,
+    exc: ImportError,
+    *,
+    module: str | None = ...,
+) -> Callable[..., NoReturn]: ...
+
+
+def _validate_export_dependencies() -> None: ...
+
+def _assign_exports(module: str, names: tuple[str, ...]) -> bool: ...
+
+def _emit_missing_dependency_warning() -> None: ...
+
+_HAS_PREPARE_NETWORK: bool
+_HAS_RUN_SEQUENCE: bool

tnfr/_compat.py

@@ -0,0 +1,11 @@
+"""Compatibility helpers for bridging typing features across Python versions."""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - exercised implicitly by importers
+    from typing import TypeAlias  # type: ignore[attr-defined]
+except (ImportError, AttributeError):  # pragma: no cover - Python < 3.10
+    from typing_extensions import TypeAlias  # type: ignore[assignment]
+
+__all__ = ["TypeAlias"]
+

tnfr/_version.py

@@ -0,0 +1,7 @@
+"""Package version for :mod:`tnfr`."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "6.0.0"

tnfr/_version.pyi

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

tnfr/alias.py

@@ -8,31 +8,32 @@ alias-based attribute access. Legacy wrappers ``alias_get`` and
 
 from __future__ import annotations
 from collections import defaultdict
-from collections.abc import Iterable, Sized
+from collections.abc import Iterable, Mapping, MutableMapping, Sized
 from dataclasses import dataclass
+from functools import lru_cache, partial
+from threading import Lock
+from types import ModuleType
 from typing import (
+    TYPE_CHECKING,
     Any,
     Callable,
-    TypeVar,
-    Optional,
     Generic,
     Hashable,
-    TYPE_CHECKING,
+    Optional,
+    TypeVar,
     cast,
 )
 
-from functools import lru_cache, partial
-from threading import Lock
-
 from .constants import get_aliases
-from .value_utils import convert_value
+from .types import FloatArray, NodeId
+from .utils import convert_value
 
 ALIAS_VF = get_aliases("VF")
 ALIAS_DNFR = get_aliases("DNFR")
 ALIAS_THETA = get_aliases("THETA")
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx  # type: ignore[import-untyped]
+    import networkx
 
 T = TypeVar("T")
 
@@ -184,6 +185,25 @@ class AliasAccessor(Generic[T]):
 _generic_accessor: AliasAccessor[Any] = AliasAccessor()
 
 
+def get_theta_attr(
+    d: Mapping[str, Any],
+    default: T | None = None,
+    *,
+    strict: bool = False,
+    log_level: int | None = None,
+    conv: Callable[[Any], T] = float,
+) -> T | None:
+    """Return ``theta``/``phase`` using the English alias set."""
+    return _generic_accessor.get(
+        cast(dict[str, Any], d),
+        ALIAS_THETA,
+        default,
+        strict=strict,
+        log_level=log_level,
+        conv=conv,
+    )
+
+
 def get_attr(
     d: dict[str, Any],
     aliases: Iterable[str],
@@ -207,12 +227,12 @@ def get_attr(
 
 def collect_attr(
     G: "networkx.Graph",
-    nodes: Iterable[Any],
+    nodes: Iterable[NodeId],
     aliases: Iterable[str],
     default: float = 0.0,
     *,
-    np=None,
-):
+    np: ModuleType | None = None,
+) -> FloatArray | list[float]:
     """Collect attribute values for ``nodes`` from ``G`` using ``aliases``.
 
     Parameters
@@ -235,7 +255,7 @@ def collect_attr(
         Collected attribute values in the same order as ``nodes``.
     """
 
-    def _nodes_iter_and_size(nodes: Iterable[Any]) -> tuple[Iterable[Any], int]:
+    def _nodes_iter_and_size(nodes: Iterable[NodeId]) -> tuple[Iterable[NodeId], int]:
         if nodes is G.nodes:
             return G.nodes, G.number_of_nodes()
         if isinstance(nodes, Sized):
@@ -245,13 +265,42 @@ def collect_attr(
 
     nodes_iter, size = _nodes_iter_and_size(nodes)
 
+    def _value(node: NodeId) -> float:
+        return float(get_attr(G.nodes[node], aliases, default))
+
     if np is not None:
-        return np.fromiter(
-            (get_attr(G.nodes[n], aliases, default) for n in nodes_iter),
-            float,
-            count=size,
-        )
-    return [get_attr(G.nodes[n], aliases, default) for n in nodes_iter]
+        values: FloatArray = np.fromiter((_value(n) for n in nodes_iter), float, count=size)
+        return values
+    return [_value(n) for n in nodes_iter]
+
+
+def collect_theta_attr(
+    G: "networkx.Graph",
+    nodes: Iterable[NodeId],
+    default: float = 0.0,
+    *,
+    np: ModuleType | None = None,
+) -> FloatArray | list[float]:
+    """Collect ``theta`` values honouring the English-only attribute contract."""
+
+    def _nodes_iter_and_size(nodes: Iterable[NodeId]) -> tuple[Iterable[NodeId], int]:
+        if nodes is G.nodes:
+            return G.nodes, G.number_of_nodes()
+        if isinstance(nodes, Sized):
+            return nodes, len(nodes)  # type: ignore[arg-type]
+        nodes_list = list(nodes)
+        return nodes_list, len(nodes_list)
+
+    nodes_iter, size = _nodes_iter_and_size(nodes)
+
+    def _value(node: NodeId) -> float:
+        return float(get_theta_attr(G.nodes[node], default))
+
+    if np is not None:
+        values: FloatArray = np.fromiter((_value(n) for n in nodes_iter), float, count=size)
+        return values
+
+    return [_value(n) for n in nodes_iter]
 
 
 def set_attr_generic(
@@ -273,8 +322,16 @@ get_attr_str = partial(get_attr, conv=str)
 set_attr_str = partial(set_attr_generic, conv=str)
 
 
+def set_theta_attr(d: MutableMapping[str, Any], value: Any) -> float:
+    """Assign ``theta``/``phase`` using the English attribute names."""
+    result = float(value)
+    d["theta"] = result
+    d["phase"] = result
+    return result
+
+
 # -------------------------
-# Máximos globales con caché
+# Cached global maxima
 # -------------------------
 
 
@@ -484,7 +541,7 @@ SCALAR_SETTERS: dict[str, dict[str, Any]] = {
     "theta": {
         "alias": ALIAS_THETA,
         "extra": _increment_trig_version,
-        "doc": "Set ``θ`` for node ``n`` and invalidate trig caches.",
+        "doc": "Set ``theta`` for node ``n`` and invalidate trig caches.",
     },
 }
 
@@ -529,14 +586,42 @@ for _name, _spec in SCALAR_SETTERS.items():
 del _name, _spec, _make_scalar_setter
 
 
+_set_theta_impl = cast(
+    Callable[["networkx.Graph", Hashable, float], AbsMaxResult | None],
+    globals()["set_theta"],
+)
+
+
+def _set_theta_with_compat(
+    G: "networkx.Graph", n: Hashable, value: float
+) -> AbsMaxResult | None:
+    nd = cast(MutableMapping[str, Any], G.nodes[n])
+    result = _set_theta_impl(G, n, value)
+    theta_val = get_theta_attr(nd, value)
+    if theta_val is not None:
+        float_theta = float(theta_val)
+        nd["theta"] = float_theta
+        nd["phase"] = float_theta
+    return result
+
+
+_set_theta_with_compat.__name__ = "set_theta"
+_set_theta_with_compat.__qualname__ = "set_theta"
+_set_theta_with_compat.__doc__ = _set_theta_impl.__doc__
+globals()["set_theta"] = _set_theta_with_compat
+
+
 __all__ = [
     "AbsMaxResult",
     "set_attr_generic",
     "get_attr",
+    "get_theta_attr",
     "collect_attr",
+    "collect_theta_attr",
     "set_attr",
     "get_attr_str",
     "set_attr_str",
+    "set_theta_attr",
     "set_attr_and_cache",
     "set_attr_with_max",
     "set_scalar",