numbox 0.3.1__py3-none-any.whl → 0.3.3__py3-none-any.whl

numbox/__init__.py

@@ -1 +1 @@
-__version__ = '0.3.1'
+__version__ = '0.3.3'

numbox/core/variable/variable.py

@@ -92,6 +92,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 +104,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):
@@ -238,7 +241,7 @@ class CompiledGraph:
             for var_name, variable in variables.items():
                 if var_name not in provided:
                     raise KeyError(
-                        f"Missing value for external variable '{source_name}.{var_name}'"
+                        f"Missing value for external variable '{_make_qual_name(source_name, var_name)}'"
                     )
                 values.get(variable).value = provided[var_name]
 
@@ -274,12 +277,13 @@ class CompiledGraph:
             if node.variable.formula is None:
                 continue
             args = tuple(values.get(input_).value for input_ in node.inputs)
-            # assert _null not in args, f"Uninitialized input for {node.variable}, args = {args}"
+            assert not any(
+                [arg is _null for arg in args]
+            ), f"Uninitialized input for {node.variable}, args = {args}"
             cache_key = (node.variable, args)
-            if node.variable.cacheable:
-                if cache_key in values.cache:
-                    values.get(node.variable).value = values.cache[cache_key]
-                    continue
+            if node.variable.cacheable and cache_key in values.cache:
+                values.get(node.variable).value = values.cache[cache_key]
+                continue
             result = node.variable.formula(*args)
             if node.variable.cacheable:
                 values.cache[cache_key] = result
@@ -348,6 +352,9 @@ class Graph:
         self.compiled_graphs = {}
 
     def compile(self, required: List[str] | str) -> CompiledGraph:
+        """
+        :required: list of qualified variables names that need to be calculated.
+        """
         if isinstance(required, str):
             required = [required]
         required_tup = tuple(sorted(required))
@@ -426,3 +433,37 @@ class Graph:
             variable_source = variable.source
             required_external_variables[variable_source][variable_name] = variable
         return required_external_variables
+
+    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.1.dist-info → numbox-0.3.3.dist-info}/LICENSE

@@ -1,6 +1,6 @@
 MIT License (with Citation Clause)
 
-Copyright (c) 2025 Mikhail Goykhman
+Copyright (c) 2026 Mikhail Goykhman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{numbox-0.3.1.dist-info → numbox-0.3.3.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.1
 Name: numbox
-Version: 0.3.1
+Version: 0.3.3
 Author: Mikhail Goykhman
 License: MIT License (with Citation Clause)
         
-        Copyright (c) 2025 Mikhail Goykhman
+        Copyright (c) 2026 Mikhail Goykhman
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal

{numbox-0.3.1.dist-info → numbox-0.3.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-numbox/__init__.py,sha256=TZkGuMIRSRmUY3XCIs5owt2o60vXyqYMHWIkhx65uYE,22
+numbox/__init__.py,sha256=on4Bj4mGEjEjyUkQExxprhOoEopcv_sPapsEnNxyelE,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=GoCsB1hUDJJzZByK1OK13RZn4M-maBDjXfnbvRFjcS8,16371
+numbox/core/variable/variable.py,sha256=yvklS5vEsad2RttxkcJ-4glejc2iLyv4ia24AZrIIRs,18117
 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.1.dist-info/LICENSE,sha256=YYgNvjH_p6-1NsdrIqGJnr1GUbZzA_8DxsP6vVfM6nY,1446
-numbox-0.3.1.dist-info/METADATA,sha256=L2Ol4D5QRR_K8j31xvFgbdJtxFiFLDJG2MPWrmS81Zk,2996
-numbox-0.3.1.dist-info/WHEEL,sha256=WnJ8fYhv8N4SYVK2lLYNI6N0kVATA7b0piVUNvqIIJE,91
-numbox-0.3.1.dist-info/top_level.txt,sha256=A67jOkfqidCSYYm6ifjN_WZyIiR1B27fjxv6nNbPvjc,7
-numbox-0.3.1.dist-info/RECORD,,
+numbox-0.3.3.dist-info/LICENSE,sha256=ZlmjEDrZFNHpGxy_7HThWRlyBvuOMchK__qgTdiO_Uk,1446
+numbox-0.3.3.dist-info/METADATA,sha256=JZUXJUW8WU5zLOAPRs_QvIkrkCCCz8x1n4QpWFyQV8I,2996
+numbox-0.3.3.dist-info/WHEEL,sha256=WnJ8fYhv8N4SYVK2lLYNI6N0kVATA7b0piVUNvqIIJE,91
+numbox-0.3.3.dist-info/top_level.txt,sha256=A67jOkfqidCSYYm6ifjN_WZyIiR1B27fjxv6nNbPvjc,7
+numbox-0.3.3.dist-info/RECORD,,