numbox 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

numbox/__init__.py

@@ -1 +1 @@
-__version__ = '0.3.2'
+__version__ = '0.3.4'

numbox/core/variable/variable.py

@@ -3,7 +3,7 @@ import warnings
 from collections import defaultdict
 from dataclasses import dataclass, field
 from typing import (
-    Any, Callable, Dict, List, Mapping, Set, Tuple, TypeAlias, Union
+    Any, Callable, Dict, Iterator, List, Mapping, Set, Tuple, TypeAlias, Union
 )
 
 
@@ -23,7 +23,7 @@ _null = _Null()
 QUAL_SEP = "."
 
 
-def _make_qual_name(namespace_name: str, var_name: str) -> str:
+def make_qual_name(namespace_name: str, var_name: str) -> str:
     """ Each `Variable` instance is best contained in a
      mapping namespace, with the given `namespace_name`.
      This function thereby returns qualified name of the
@@ -55,6 +55,9 @@ class External:
             self._vars[name] = variable
         return variable
 
+    def __iter__(self) -> Iterator['Variable']:
+        return iter(self._vars.values())
+
 
 @dataclass(frozen=True)
 class Variable:
@@ -92,6 +95,8 @@ class Variable:
     these variables.
     :param formula: (optional) function that calculates value
     of this `Variable` from its sources.
+    :param metadata: any possible metadata associated with
+    this variable.
     :param cacheable: (default `False`) when `True`, the
     corresponding `Value` (see below) will be cached during
     calculation by the `id` of the corresponding Python object
@@ -102,6 +107,7 @@ class Variable:
     source: str = field(default="")
     inputs: Mapping[str, str] = field(default_factory=lambda: {})
     formula: Callable = field(default=None)
+    metadata: str | None = field(default=None)
     cacheable: bool = field(default=False)
 
     def __hash__(self):
@@ -111,7 +117,7 @@ class Variable:
         return isinstance(other, Variable) and self.name == other.name and self.source == other.source
 
     def qual_name(self) -> str:
-        return _make_qual_name(self.source, self.name)
+        return make_qual_name(self.source, self.name)
 
 
 class Variables:
@@ -140,6 +146,9 @@ class Variables:
         """
         return self.variables[variable_name]
 
+    def __iter__(self) -> Iterator[Variable]:
+        return iter(self.variables.values())
+
 
 @dataclass
 class Value:
@@ -169,8 +178,8 @@ class CompiledNode:
     inputs: List[Variable]
 
     def __post_init__(self):
-        if self.variable.formula is None and self.inputs:
-            raise RuntimeError(f"{self.variable} contains inputs but no formula, how come?")
+        if self.variable.formula and not self.inputs:
+            raise RuntimeError(f"{self.variable} contains formula but no inputs, how come?")
 
     def __hash__(self):
         return hash((self.variable.source, self.variable.name))
@@ -209,7 +218,6 @@ class CompiledGraph:
         source and then from the name of the variable within that
         source to the variable's actual value.
         :param values: runtime storage of all values, instance of `Values`.
-        :return:
         """
         self._assign_external_values(external_values, values)
         self._calculate(self.ordered_nodes, values)
@@ -238,7 +246,7 @@ class CompiledGraph:
             for var_name, variable in variables.items():
                 if var_name not in provided:
                     raise KeyError(
-                        f"Missing value for external variable '{_make_qual_name(source_name, var_name)}'"
+                        f"Missing value for external variable '{make_qual_name(source_name, var_name)}'"
                     )
                 values.get(variable).value = provided[var_name]
 
@@ -295,7 +303,7 @@ class CompiledGraph:
         for src, vals in changed.items():
             for name, val in vals.items():
                 variable = self.required_external_variables.get(src, {}).get(name)
-                qual = _make_qual_name(src, name)
+                qual = make_qual_name(src, name)
                 if variable is None:
                     try:
                         variable = next(n.variable for n in self.ordered_nodes if n.variable.qual_name() == qual)
@@ -409,7 +417,7 @@ class Graph:
             if isinstance(source, External):
                 used_external_vars.add(variable)
             for input_name, input_source in variable.inputs.items():
-                visit(_make_qual_name(input_source, input_name))
+                visit(make_qual_name(input_source, input_name))
             visiting.remove(qual_name)
             visited.add(qual_name)
             ordered_variables.append(variable)
@@ -430,3 +438,71 @@ class Graph:
             variable_source = variable.source
             required_external_variables[variable_source][variable_name] = variable
         return required_external_variables
+
+    def _build_reverse_dependencies(self) -> Dict[str, set[str]]:
+        """
+        Utility to calculate set of qualified names of variables
+        impacted by each of the encountered inputs.
+        """
+        reverse = defaultdict(set)
+        for source_name, source in self.registry.items():
+            for variable in source:
+                var_qual = make_qual_name(source_name, variable.name)
+                for input_name, input_source in variable.inputs.items():
+                    input_qual = make_qual_name(input_source, input_name)
+                    reverse[input_qual].add(var_qual)
+        return reverse
+
+    def dependents_of(self, qual_names: List[str] | Set[str] | str) -> Set[str]:
+        """
+        Return qualified names of `Variable`s that directly or indirectly
+        depend on any of `qual_names`.
+        """
+        if isinstance(qual_names, str):
+            qual_names = {qual_names}
+        else:
+            qual_names = set(qual_names)
+        reverse = self._build_reverse_dependencies()
+        result = set(qual_names)
+        stack = list(qual_names)
+        while stack:
+            current = stack.pop()
+            for dep in reverse.get(current, ()):
+                if dep not in result:
+                    result.add(dep)
+                    stack.append(dep)
+        return result
+
+    def explain(self, qual_name: str, direct: bool = True) -> str:
+        """
+        Follow the dependencies chain to explain how the given
+        variable is derived.
+        :param qual_name: qualified name of the `Variable`.
+        :param direct: when `True` (default), begin explanation
+        with `qual_name`.
+        """
+        derived = set()
+        derivation = []
+
+        def collect(qual_name_: str):
+            if qual_name_ in derived:
+                return
+            derived.add(qual_name_)
+            source_name, variable_name = qual_name_.split(QUAL_SEP)
+            variable_source = self.registry[source_name]
+            variable = variable_source[variable_name]
+            inputs_qual_names = []
+            for input_name, input_source in variable.inputs.items():
+                inputs_qual_names.append(make_qual_name(input_source, input_name))
+                collect(make_qual_name(input_source, input_name))
+            if isinstance(variable_source, External):
+                derivation.append(f"'{variable_name}' comes from external source '{source_name}'\n")
+            else:
+                derivation.append(
+                    f"""'{qual_name_}' depends on {tuple(sorted(inputs_qual_names))} via \n\n{variable.metadata}"""
+                )
+
+        collect(qual_name)
+        derivation = reversed(derivation) if direct else derivation
+        derivation_txt = "\n" + "\n".join(derivation)
+        return derivation_txt

{numbox-0.3.2.dist-info → numbox-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: numbox
-Version: 0.3.2
+Version: 0.3.4
 Author: Mikhail Goykhman
 License: MIT License (with Citation Clause)
         

{numbox-0.3.2.dist-info → numbox-0.3.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-numbox/__init__.py,sha256=bqu4G7Is-8Were-hMi-SthEalL7QW-PAbKWGZ9pVB6U,22
+numbox/__init__.py,sha256=Yyz9rKJSsP7kA7oh3l-XTxOFzEuuSR9Ly7oYXA1hfFM,22
 numbox/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 numbox/core/configurations.py,sha256=0bCmxXL-QMwtvyIDhpXLeT-1KJMf_QpH0wLuEvYLGxQ,68
 numbox/core/any/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -15,7 +15,7 @@ numbox/core/bindings/utils.py,sha256=OATfF4k8e5oPa9_wlHHkLQhY_DhrPNKYdeeGu9Nj5yg
 numbox/core/proxy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 numbox/core/proxy/proxy.py,sha256=Wt7yzswDmeQXt0yjcTcnLi2coneowSHWXy_IFpZZJMU,3612
 numbox/core/variable/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-numbox/core/variable/variable.py,sha256=Y1nB9wqt91BkWCKRyQNe1jFR0aic57HNnylTGp9h1nI,16518
+numbox/core/variable/variable.py,sha256=vmkecU_1_OUJov1cg0bT3fU7zxu1L7cGMBWD3_0cvQM,19621
 numbox/core/work/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 numbox/core/work/builder.py,sha256=d0DRwJoyskp-6tYQyV1VE-v9eX99qJbQJ_FdAFrjuiE,6273
 numbox/core/work/builder_utils.py,sha256=z8au1x10AwnzQ0_MAbQ6DnKTp3u9HeYZ1jyfkUMYjVg,1213
@@ -35,8 +35,8 @@ numbox/utils/meminfo.py,sha256=ykFi8Vt0WcHI3ztgMwvpn6NqaflDSQGL8tjI01jrzm0,1759
 numbox/utils/standard.py,sha256=SPsQcyLZw21RaNCdfkIGE_QBaVnMtZjJY4F40_GGuak,347
 numbox/utils/timer.py,sha256=5_d690Fb3L2axJBRxtoB0qe23exBosNR4qu6cno4QfY,641
 numbox/utils/void_type.py,sha256=IkZsjNeAIShYJtvWbvERdHnl_mbF1rCRWiM3gp6II8U,404
-numbox-0.3.2.dist-info/LICENSE,sha256=ZlmjEDrZFNHpGxy_7HThWRlyBvuOMchK__qgTdiO_Uk,1446
-numbox-0.3.2.dist-info/METADATA,sha256=j7WYDDW5WT6aBnyXtsqpwKPXWKGYQq9Vu8_NNyC44q4,2996
-numbox-0.3.2.dist-info/WHEEL,sha256=WnJ8fYhv8N4SYVK2lLYNI6N0kVATA7b0piVUNvqIIJE,91
-numbox-0.3.2.dist-info/top_level.txt,sha256=A67jOkfqidCSYYm6ifjN_WZyIiR1B27fjxv6nNbPvjc,7
-numbox-0.3.2.dist-info/RECORD,,
+numbox-0.3.4.dist-info/LICENSE,sha256=ZlmjEDrZFNHpGxy_7HThWRlyBvuOMchK__qgTdiO_Uk,1446
+numbox-0.3.4.dist-info/METADATA,sha256=E3a0zMbjM0vjbO2DVN9zaZOuW1D09A20spTbIZK2imM,2996
+numbox-0.3.4.dist-info/WHEEL,sha256=WnJ8fYhv8N4SYVK2lLYNI6N0kVATA7b0piVUNvqIIJE,91
+numbox-0.3.4.dist-info/top_level.txt,sha256=A67jOkfqidCSYYm6ifjN_WZyIiR1B27fjxv6nNbPvjc,7
+numbox-0.3.4.dist-info/RECORD,,