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

tnfr/alias.py

@@ -7,32 +7,30 @@ 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
-
-ALIAS_VF = get_aliases("VF")
-ALIAS_DNFR = get_aliases("DNFR")
-ALIAS_THETA = get_aliases("THETA")
+from .constants.aliases import ALIAS_DNFR, ALIAS_THETA, ALIAS_VF
+from .types import FloatArray, NodeId
+from .utils import convert_value
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx  # type: ignore[import-untyped]
+    import networkx
 
 T = TypeVar("T")
 
@@ -132,6 +130,8 @@ class AliasAccessor(Generic[T]):
         log_level: int | None = None,
         conv: Callable[[Any], T] | None = None,
     ) -> Optional[T]:
+        """Return ``value`` for the first alias present in ``d``."""
+
         aliases, conv, default = self._prepare(aliases, conv, default)
         cache_key, key = self._resolve_cache_key(d, aliases)
         if key is not None:
@@ -168,6 +168,8 @@ class AliasAccessor(Generic[T]):
         value: Any,
         conv: Callable[[Any], T] | None = None,
     ) -> T:
+        """Write ``value`` under the first matching alias and cache the choice."""
+
         aliases, conv, _ = self._prepare(aliases, conv)
         cache_key, key = self._resolve_cache_key(d, aliases)
         if key is not None:
@@ -184,6 +186,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 +228,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 +256,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 +266,46 @@ 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,
+        values: FloatArray = np.fromiter(
+            (_value(n) for n in nodes_iter), float, count=size
         )
-    return [get_attr(G.nodes[n], aliases, default) for n in nodes_iter]
+        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 +327,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
 # -------------------------
 
 
@@ -388,9 +450,7 @@ def _update_cached_abs_max(
     cur_node = cast(Hashable | None, G.graph.get(node_key))
 
     if val >= cur:
-        return _compute_abs_max_result(
-            G, aliases, key=key, candidate=(n, val)
-        )
+        return _compute_abs_max_result(G, aliases, key=key, candidate=(n, val))
     if cur_node == n:
         return _compute_abs_max_result(G, aliases, key=key)
     return AbsMaxResult(max_value=cur, node=cur_node)
@@ -461,9 +521,7 @@ def set_scalar(
     return set_attr_and_cache(G, n, alias, value, cache=cache, extra=extra)
 
 
-def _increment_trig_version(
-    G: "networkx.Graph", _: Hashable, __: float
-) -> None:
+def _increment_trig_version(G: "networkx.Graph", _: Hashable, __: float) -> None:
     """Increment cached trig version to invalidate trig caches."""
     g = G.graph
     g["_trig_version"] = int(g.get("_trig_version", 0)) + 1
@@ -484,7 +542,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 +587,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",

tnfr/alias.pyi

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, MutableMapping
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, Hashable, TypeVar
+
+from .types import FloatArray, NodeId
+
+if TYPE_CHECKING:
+    import networkx as nx
+
+T = TypeVar("T")
+
+__all__: list[str]
+
+def __getattr__(name: str) -> Any: ...
+
+class AbsMaxResult:
+    max_value: float
+    node: Hashable | None
+
+SCALAR_SETTERS: dict[str, dict[str, Any]]
+
+def get_attr(
+    d: dict[str, Any],
+    aliases: Iterable[str],
+    default: T | None = ...,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+    conv: Callable[[Any], T] = ...,
+) -> T | None: ...
+def get_theta_attr(
+    d: Mapping[str, Any],
+    default: T | None = ...,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+    conv: Callable[[Any], T] = ...,
+) -> T | None: ...
+def collect_attr(
+    G: "nx.Graph",
+    nodes: Iterable[NodeId],
+    aliases: Iterable[str],
+    default: float = ...,
+    *,
+    np: ModuleType | None = ...,
+) -> FloatArray | list[float]: ...
+def collect_theta_attr(
+    G: "nx.Graph",
+    nodes: Iterable[NodeId],
+    default: float = ...,
+    *,
+    np: ModuleType | None = ...,
+) -> FloatArray | list[float]: ...
+def set_attr_generic(
+    d: dict[str, Any],
+    aliases: Iterable[str],
+    value: Any,
+    *,
+    conv: Callable[[Any], T],
+) -> T: ...
+def set_attr(
+    d: dict[str, Any],
+    aliases: Iterable[str],
+    value: Any,
+    conv: Callable[[Any], T] = ...,
+) -> T: ...
+def get_attr_str(
+    d: dict[str, Any],
+    aliases: Iterable[str],
+    default: str | None = ...,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+    conv: Callable[[Any], str] = ...,
+) -> str | None: ...
+def set_attr_str(d: dict[str, Any], aliases: Iterable[str], value: Any) -> str: ...
+def set_theta_attr(d: MutableMapping[str, Any], value: Any) -> float: ...
+def multi_recompute_abs_max(
+    G: "nx.Graph", alias_map: Mapping[str, tuple[str, ...]]
+) -> dict[str, float]: ...
+def set_attr_and_cache(
+    G: "nx.Graph",
+    n: Hashable,
+    aliases: tuple[str, ...],
+    value: float,
+    *,
+    cache: str | None = ...,
+    extra: Callable[["nx.Graph", Hashable, float], None] | None = ...,
+) -> AbsMaxResult | None: ...
+def set_attr_with_max(
+    G: "nx.Graph", n: Hashable, aliases: tuple[str, ...], value: float, *, cache: str
+) -> AbsMaxResult: ...
+def set_scalar(
+    G: "nx.Graph",
+    n: Hashable,
+    alias: tuple[str, ...],
+    value: float,
+    *,
+    cache: str | None = ...,
+    extra: Callable[["nx.Graph", Hashable, float], None] | None = ...,
+) -> AbsMaxResult | None: ...
+def set_vf(
+    G: "nx.Graph", n: Hashable, value: float, *, update_max: bool = ...
+) -> AbsMaxResult | None: ...
+def set_dnfr(G: "nx.Graph", n: Hashable, value: float) -> AbsMaxResult | None: ...
+def set_theta(G: "nx.Graph", n: Hashable, value: float) -> AbsMaxResult | None: ...