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

tnfr/units.py

@@ -0,0 +1,69 @@
+"""Structural unit conversion helpers.
+
+The TNFR engine tracks structural dynamics using the ``Hz_str`` unit.  A
+single configurable scale factor ``k`` bridges this canonical structural
+frequency with the conventional ``Hz`` base unit.  The factor is resolved
+according to the following invariants:
+
+* ``k`` is always read from the graph configuration via :func:`get_param` so
+  per-graph overrides take precedence over the package defaults.
+* The fallback value comes from :data:`tnfr.constants.DEFAULTS`, ensuring the
+  canonical 1 Hz_str↔Hz relationship is preserved when callers do not provide
+  explicit overrides.
+* ``k`` must remain strictly positive.  Invalid overrides raise
+  :class:`ValueError` to prevent incoherent conversions.
+
+All helpers defined here operate purely on ``GraphLike`` instances and only
+depend on :mod:`tnfr.constants` for configuration access, keeping the
+conversion logic transparent and side-effect free.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .constants import get_param
+from .types import GraphLike
+
+__all__ = ("get_hz_bridge", "hz_str_to_hz", "hz_to_hz_str")
+
+HZ_STR_BRIDGE_KEY: Final[str] = "HZ_STR_BRIDGE"
+
+
+def _coerce_bridge_factor(raw: object) -> float:
+    """Return ``raw`` coerced to a strictly positive floating point factor."""
+
+    try:
+        factor = float(raw)
+    except (TypeError, ValueError) as exc:  # pragma: no cover - defensive guard
+        raise TypeError(
+            "HZ_STR_BRIDGE must be a real number convertible to float"
+        ) from exc
+
+    if factor <= 0.0:
+        raise ValueError("HZ_STR_BRIDGE must be strictly positive")
+
+    return factor
+
+
+def get_hz_bridge(G: GraphLike) -> float:
+    """Return the ``Hz_str``→``Hz`` bridge factor for ``G``.
+
+    The helper always consults ``G.graph`` via :func:`get_param` so per-graph
+    overrides remain authoritative.
+    """
+
+    return _coerce_bridge_factor(get_param(G, HZ_STR_BRIDGE_KEY))
+
+
+def hz_str_to_hz(value: float, G: GraphLike) -> float:
+    """Convert ``value`` expressed in ``Hz_str`` into ``Hz`` using ``G``."""
+
+    return float(value) * get_hz_bridge(G)
+
+
+def hz_to_hz_str(value: float, G: GraphLike) -> float:
+    """Convert ``value`` expressed in ``Hz`` into ``Hz_str`` using ``G``."""
+
+    return float(value) / get_hz_bridge(G)
+

tnfr/units.pyi

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Final
+
+from .types import GraphLike
+
+__all__ = ("get_hz_bridge", "hz_str_to_hz", "hz_to_hz_str")
+
+HZ_STR_BRIDGE_KEY: Final[str]
+
+def get_hz_bridge(G: GraphLike) -> float: ...
+
+def hz_str_to_hz(value: float, G: GraphLike) -> float: ...
+
+def hz_to_hz_str(value: float, G: GraphLike) -> float: ...
+

tnfr/utils/__init__.py

@@ -5,11 +5,69 @@ from __future__ import annotations
 from typing import Any, Final
 
 from . import init as _init
-from ..cache import CacheManager
+from ..locking import get_lock
+
+WarnOnce = _init.WarnOnce
+cached_import = _init.cached_import
+warm_cached_import = _init.warm_cached_import
+LazyImportProxy = _init.LazyImportProxy
+get_logger = _init.get_logger
+get_nodenx = _init.get_nodenx
+get_numpy = _init.get_numpy
+prune_failed_imports = _init.prune_failed_imports
+warn_once = _init.warn_once
+_configure_root = _init._configure_root
+_reset_logging_state = _init._reset_logging_state
+_reset_import_state = _init._reset_import_state
+_warn_failure = _init._warn_failure
+_FAILED_IMPORT_LIMIT = _init._FAILED_IMPORT_LIMIT
+_DEFAULT_CACHE_SIZE = _init._DEFAULT_CACHE_SIZE
+EMIT_MAP = _init.EMIT_MAP
+
+from .cache import (
+    CacheCapacityConfig,
+    CacheLayer,
+    CacheManager,
+    CacheStatistics,
+    InstrumentedLRUCache,
+    ManagedLRUCache,
+    MappingCacheLayer,
+    RedisCacheLayer,
+    ShelveCacheLayer,
+    prune_lock_mapping,
+    DNFR_PREP_STATE_KEY,
+    DnfrPrepState,
+    DnfrCache,
+    NODE_SET_CHECKSUM_KEY,
+    ScopedCounterCache,
+    EdgeCacheManager,
+    cached_node_list,
+    cached_nodes_and_A,
+    clear_node_repr_cache,
+    configure_graph_cache_limits,
+    configure_global_cache_layers,
+    edge_version_cache,
+    edge_version_update,
+    ensure_node_index_map,
+    ensure_node_offset_map,
+    new_dnfr_cache,
+    _SeedHashCache,
+    _GRAPH_CACHE_MANAGER_KEY,
+    _graph_cache_manager,
+    build_cache_manager,
+    get_graph_version,
+    increment_edge_version,
+    increment_graph_version,
+    node_set_checksum,
+    reset_global_cache_manager,
+    stable_json,
+    _GRAPH_CACHE_LAYERS_KEY,
+)
 from .data import (
     MAX_MATERIALIZE_DEFAULT,
     STRING_TYPES,
     convert_value,
+    normalize_optional_int,
     ensure_collection,
     flatten_structure,
     is_non_string_sequence,
@@ -19,34 +77,30 @@ from .data import (
     normalize_materialize_limit,
     normalize_weights,
 )
+from .chunks import auto_chunk_size, resolve_chunk_size
 from .graph import (
     get_graph,
     get_graph_mapping,
     mark_dnfr_prep_dirty,
     supports_add_edge,
 )
-from .cache import (
-    EdgeCacheManager,
-    NODE_SET_CHECKSUM_KEY,
-    cached_node_list,
-    cached_nodes_and_A,
-    clear_node_repr_cache,
-    edge_version_cache,
-    edge_version_update,
-    ensure_node_index_map,
-    ensure_node_offset_map,
-    get_graph_version,
-    increment_edge_version,
-    increment_graph_version,
-    configure_graph_cache_limits,
-    node_set_checksum,
-    stable_json,
+from .numeric import (
+    angle_diff,
+    angle_diff_array,
+    clamp,
+    clamp01,
+    kahan_sum_nd,
+    similarity_abs,
+    within_range,
 )
 from .io import (
     DEFAULT_PARAMS,
     JsonDumpsParams,
+    StructuredFileError,
     clear_orjson_param_warnings,
     json_dumps,
+    read_structured_file,
+    safe_write,
 )
 
 __all__ = (
@@ -56,11 +110,13 @@ __all__ = (
     "warm_cached_import",
     "LazyImportProxy",
     "get_logger",
+    "get_lock",
     "get_nodenx",
     "get_numpy",
     "prune_failed_imports",
     "warn_once",
     "convert_value",
+    "normalize_optional_int",
     "normalize_weights",
     "normalize_counter",
     "normalize_materialize_limit",
@@ -71,22 +127,49 @@ __all__ = (
     "MAX_MATERIALIZE_DEFAULT",
     "negative_weights_warn_once",
     "mix_groups",
+    "angle_diff",
+    "angle_diff_array",
+    "clamp",
+    "clamp01",
+    "auto_chunk_size",
+    "resolve_chunk_size",
+    "CacheCapacityConfig",
+    "CacheLayer",
     "CacheManager",
+    "CacheStatistics",
+    "InstrumentedLRUCache",
+    "ManagedLRUCache",
+    "MappingCacheLayer",
+    "RedisCacheLayer",
+    "ShelveCacheLayer",
+    "prune_lock_mapping",
     "EdgeCacheManager",
+    "DNFR_PREP_STATE_KEY",
+    "DnfrPrepState",
+    "DnfrCache",
     "NODE_SET_CHECKSUM_KEY",
+    "ScopedCounterCache",
     "cached_node_list",
     "cached_nodes_and_A",
     "clear_node_repr_cache",
     "edge_version_cache",
     "edge_version_update",
+    "configure_global_cache_layers",
     "ensure_node_index_map",
     "ensure_node_offset_map",
+    "new_dnfr_cache",
     "get_graph_version",
     "increment_edge_version",
     "increment_graph_version",
     "configure_graph_cache_limits",
+    "build_cache_manager",
+    "_graph_cache_manager",
+    "_GRAPH_CACHE_MANAGER_KEY",
     "node_set_checksum",
     "stable_json",
+    "reset_global_cache_manager",
+    "_SeedHashCache",
+    "_GRAPH_CACHE_LAYERS_KEY",
     "get_graph",
     "get_graph_mapping",
     "mark_dnfr_prep_dirty",
@@ -95,8 +178,12 @@ __all__ = (
     "DEFAULT_PARAMS",
     "json_dumps",
     "clear_orjson_param_warnings",
-    "validate_window",
-    "run_validators",
+    "read_structured_file",
+    "safe_write",
+    "StructuredFileError",
+    "kahan_sum_nd",
+    "similarity_abs",
+    "within_range",
     "_configure_root",
     "_LOGGING_CONFIGURED",
     "_reset_logging_state",
@@ -108,23 +195,6 @@ __all__ = (
     "EMIT_MAP",
 )
 
-WarnOnce = _init.WarnOnce
-cached_import = _init.cached_import
-warm_cached_import = _init.warm_cached_import
-LazyImportProxy = _init.LazyImportProxy
-get_logger = _init.get_logger
-get_nodenx = _init.get_nodenx
-get_numpy = _init.get_numpy
-prune_failed_imports = _init.prune_failed_imports
-warn_once = _init.warn_once
-_configure_root = _init._configure_root
-_reset_logging_state = _init._reset_logging_state
-_reset_import_state = _init._reset_import_state
-_warn_failure = _init._warn_failure
-_FAILED_IMPORT_LIMIT = _init._FAILED_IMPORT_LIMIT
-_DEFAULT_CACHE_SIZE = _init._DEFAULT_CACHE_SIZE
-EMIT_MAP = _init.EMIT_MAP
-
 #: Mapping of dynamically proxied names to the runtime types they expose.
 #:
 #: ``IMPORT_LOG`` and ``_IMPORT_STATE`` refer to the
@@ -137,22 +207,11 @@ _DYNAMIC_EXPORT_TYPES: Final[dict[str, type[object]]] = {
     "_LOGGING_CONFIGURED": bool,
 }
 _DYNAMIC_EXPORTS: Final[frozenset[str]] = frozenset(_DYNAMIC_EXPORT_TYPES)
-_VALIDATOR_EXPORTS = {"validate_window", "run_validators"}
-
-
 def __getattr__(name: str) -> Any:  # pragma: no cover - trivial delegation
     if name in _DYNAMIC_EXPORTS:
         return getattr(_init, name)
-    if name in _VALIDATOR_EXPORTS:
-        if name == "validate_window":
-            from .validators import validate_window as _validate_window
-
-            return _validate_window
-        from .validators import run_validators as _run_validators
-
-        return _run_validators
     raise AttributeError(name)
 
 
 def __dir__() -> list[str]:  # pragma: no cover - trivial delegation
-    return sorted(set(globals()) | _DYNAMIC_EXPORTS | _VALIDATOR_EXPORTS)
+    return sorted(set(globals()) | set(_DYNAMIC_EXPORTS))

tnfr/utils/__init__.pyi

@@ -2,28 +2,52 @@ from __future__ import annotations
 
 from typing import Any, Final
 
-from ..cache import CacheManager
+from threading import Lock
+
 from .cache import (
-    EdgeCacheManager,
+    CacheCapacityConfig,
+    CacheLayer,
+    CacheManager,
+    CacheStatistics,
+    InstrumentedLRUCache,
+    ManagedLRUCache,
+    MappingCacheLayer,
+    RedisCacheLayer,
+    ShelveCacheLayer,
+    prune_lock_mapping,
+    DNFR_PREP_STATE_KEY,
+    DnfrPrepState,
+    DnfrCache,
     NODE_SET_CHECKSUM_KEY,
+    ScopedCounterCache,
+    EdgeCacheManager,
     cached_node_list,
     cached_nodes_and_A,
     clear_node_repr_cache,
     configure_graph_cache_limits,
+    configure_global_cache_layers,
     edge_version_cache,
     edge_version_update,
     ensure_node_index_map,
     ensure_node_offset_map,
+    new_dnfr_cache,
+    _SeedHashCache,
+    _GRAPH_CACHE_MANAGER_KEY,
+    _graph_cache_manager,
+    build_cache_manager,
     get_graph_version,
     increment_edge_version,
     increment_graph_version,
     node_set_checksum,
+    reset_global_cache_manager,
     stable_json,
+    _GRAPH_CACHE_LAYERS_KEY,
 )
 from .data import (
     MAX_MATERIALIZE_DEFAULT,
     STRING_TYPES,
     convert_value,
+    normalize_optional_int,
     ensure_collection,
     flatten_structure,
     is_non_string_sequence,
@@ -33,21 +57,31 @@ from .data import (
     normalize_materialize_limit,
     normalize_weights,
 )
+from .chunks import auto_chunk_size, resolve_chunk_size
 from .graph import (
     get_graph,
     get_graph_mapping,
     mark_dnfr_prep_dirty,
     supports_add_edge,
 )
+from .numeric import (
+    angle_diff,
+    angle_diff_array,
+    clamp,
+    clamp01,
+    kahan_sum_nd,
+    similarity_abs,
+    within_range,
+)
 from .init import (
-    EMIT_MAP,
-    IMPORT_LOG,
-    LazyImportProxy,
-    WarnOnce,
     _DEFAULT_CACHE_SIZE,
     _FAILED_IMPORT_LIMIT,
     _IMPORT_STATE,
     _LOGGING_CONFIGURED,
+    EMIT_MAP,
+    IMPORT_LOG,
+    LazyImportProxy,
+    WarnOnce,
     _configure_root,
     _reset_import_state,
     _reset_logging_state,
@@ -63,11 +97,12 @@ from .init import (
 from .io import (
     DEFAULT_PARAMS,
     JsonDumpsParams,
+    StructuredFileError,
     clear_orjson_param_warnings,
     json_dumps,
+    read_structured_file,
+    safe_write,
 )
-from .validators import run_validators, validate_window
-
 __all__ = (
     "IMPORT_LOG",
     "WarnOnce",
@@ -75,11 +110,13 @@ __all__ = (
     "warm_cached_import",
     "LazyImportProxy",
     "get_logger",
+    "get_lock",
     "get_nodenx",
     "get_numpy",
     "prune_failed_imports",
     "warn_once",
     "convert_value",
+    "normalize_optional_int",
     "normalize_weights",
     "normalize_counter",
     "normalize_materialize_limit",
@@ -90,22 +127,49 @@ __all__ = (
     "MAX_MATERIALIZE_DEFAULT",
     "negative_weights_warn_once",
     "mix_groups",
+    "angle_diff",
+    "angle_diff_array",
+    "clamp",
+    "clamp01",
+    "auto_chunk_size",
+    "resolve_chunk_size",
+    "CacheCapacityConfig",
+    "CacheLayer",
     "CacheManager",
+    "CacheStatistics",
+    "InstrumentedLRUCache",
+    "ManagedLRUCache",
+    "MappingCacheLayer",
+    "RedisCacheLayer",
+    "ShelveCacheLayer",
+    "prune_lock_mapping",
     "EdgeCacheManager",
+    "DNFR_PREP_STATE_KEY",
+    "DnfrPrepState",
+    "DnfrCache",
     "NODE_SET_CHECKSUM_KEY",
+    "ScopedCounterCache",
     "cached_node_list",
     "cached_nodes_and_A",
     "clear_node_repr_cache",
     "edge_version_cache",
     "edge_version_update",
+    "configure_global_cache_layers",
     "ensure_node_index_map",
     "ensure_node_offset_map",
+    "new_dnfr_cache",
     "get_graph_version",
     "increment_edge_version",
     "increment_graph_version",
     "configure_graph_cache_limits",
+    "build_cache_manager",
+    "_graph_cache_manager",
+    "_GRAPH_CACHE_MANAGER_KEY",
     "node_set_checksum",
     "stable_json",
+    "reset_global_cache_manager",
+    "_SeedHashCache",
+    "_GRAPH_CACHE_LAYERS_KEY",
     "get_graph",
     "get_graph_mapping",
     "mark_dnfr_prep_dirty",
@@ -114,8 +178,12 @@ __all__ = (
     "DEFAULT_PARAMS",
     "json_dumps",
     "clear_orjson_param_warnings",
-    "validate_window",
-    "run_validators",
+    "read_structured_file",
+    "safe_write",
+    "StructuredFileError",
+    "kahan_sum_nd",
+    "similarity_abs",
+    "within_range",
     "_configure_root",
     "_LOGGING_CONFIGURED",
     "_reset_logging_state",
@@ -127,7 +195,8 @@ __all__ = (
     "EMIT_MAP",
 )
 
-_DYNAMIC_EXPORTS: Final[frozenset[str]]
+def get_lock(name: str, /) -> Lock: ...
 
+_DYNAMIC_EXPORTS: Final[frozenset[str]]
 
 def __getattr__(name: str) -> Any: ...