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

tnfr/__init__.py

@@ -4,88 +4,312 @@ 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",),
+    },
+    "create_math_nfr": {
+        "submodules": (
+            "tnfr.structural",
+            "tnfr.constants",
+            "tnfr.dynamics",
+            "tnfr.operators.definitions",
+            "tnfr.operators.registry",
+            "tnfr.validation",
+            "tnfr.mathematics",
+        ),
+        "third_party": (
+            "networkx",
+            "numpy",
+        ),
+    },
+    "run_sequence": {
+        "submodules": (
+            "tnfr.structural",
+            "tnfr.constants",
+            "tnfr.dynamics",
+            "tnfr.operators.definitions",
+            "tnfr.operators.registry",
+            "tnfr.validation",
+        ),
+        "third_party": ("networkx",),
+    },
+    "get_hz_bridge": {
+        "submodules": (
+            "tnfr.units",
+            "tnfr.constants",
+        ),
+        "third_party": ("networkx",),
+    },
+    "hz_str_to_hz": {
+        "submodules": (
+            "tnfr.units",
+            "tnfr.constants",
+        ),
+        "third_party": ("networkx",),
+    },
+    "hz_to_hz_str": {
+        "submodules": (
+            "tnfr.units",
+            "tnfr.constants",
+        ),
+        "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 _is_internal_import_error(exc: ImportError) -> bool:
+    missing_name = getattr(exc, "name", None) or ""
+    if missing_name.startswith("tnfr"):
+        return True
 
-def _missing_dependency(name: str, exc: ImportError):
-    def _stub(*args, **kwargs):
+    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."""
+
 
+def _validate_export_dependencies() -> None:
+    """Ensure exported helpers and their manifest entries stay in sync."""
 
-_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
+    if "__all__" not in globals():
+        # Defensive guard for unusual import orders (should never trigger).
+        return
 
+    issues: list[str] = []
+    manifest = EXPORT_DEPENDENCIES
+    export_names = [name for name in __all__ if name != "__version__"]
+    manifest_names = set(manifest)
 
-_metadata = cached_import("importlib.metadata")
-if _metadata is None:  # pragma: no cover
-    _metadata = cached_import("importlib_metadata")
+    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
 
-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
+        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
 
-    class PackageNotFoundError(Exception):
-        pass
+        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"
+                )
 
-    def version(_: str) -> str:
-        raise PackageNotFoundError
+    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"
+                )
 
-try:
-    __version__ = version("tnfr")
-except PackageNotFoundError:  # pragma: no cover
-    tomllib = cached_import("tomllib")
-    if tomllib is not None:
-        from pathlib import Path
+        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_STRUCTURAL_EXPORTS = _assign_exports(
+    "structural", ("create_nfr", "run_sequence", "create_math_nfr")
+)
+
+
+_assign_exports("units", ("get_hz_bridge", "hz_str_to_hz", "hz_to_hz_str"))
+
+
+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",
+    "get_hz_bridge",
+    "hz_str_to_hz",
+    "hz_to_hz_str",
 ]
 
-if _HAS_RUN_SEQUENCE:
-    __all__.append("run_sequence")
+if _HAS_STRUCTURAL_EXPORTS:
+    __all__.extend(["run_sequence", "create_math_nfr"])
+
+
+_validate_export_dependencies()

tnfr/__init__.pyi

@@ -0,0 +1,33 @@
+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,10 @@
+"""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/_generated_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '7.0.0'
+__version_tuple__ = version_tuple = (7, 0, 0)
+
+__commit_id__ = commit_id = None

tnfr/_version.py

@@ -0,0 +1,49 @@
+"""Runtime version discovery for :mod:`tnfr`."""
+
+from __future__ import annotations
+
+import os
+from importlib import metadata
+from typing import Final
+
+__all__ = ["__version__"]
+
+
+def _read_version() -> str:
+    """Resolve the published package version while preserving TNFR invariants."""
+
+    env_version = os.environ.get("TNFR_VERSION")
+    if env_version:
+        return env_version
+
+    try:
+        return metadata.version("tnfr")
+    except metadata.PackageNotFoundError:
+        pass
+
+    try:  # pragma: no cover - only present in built distributions
+        from . import _generated_version  # type: ignore
+    except ImportError:  # pragma: no cover - optional artifact
+        pass
+    else:
+        generated = getattr(_generated_version, "version", None)
+        if isinstance(generated, str) and generated:
+            return generated
+        legacy = getattr(_generated_version, "__version__", None)
+        if isinstance(legacy, str) and legacy:
+            return legacy
+
+    try:
+        from setuptools_scm import get_version
+    except Exception:  # pragma: no cover - optional dependency
+        pass
+    else:
+        try:
+            return get_version(relative_to=__file__)
+        except LookupError:
+            pass
+
+    return "0.0.0"
+
+
+__version__: Final[str] = _read_version()

tnfr/_version.pyi

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