doc, typing

Author: ankostis

graphtik/base.py

@@ -4,7 +4,9 @@
 
 import abc
 import logging
-from typing import Mapping, Union
+from typing import Collection, Mapping, Union
+
+Items = Union[Collection, str, None]
 
 log = logging.getLogger(__name__)
 

graphtik/netop.py

@@ -5,12 +5,12 @@
 import logging
 import re
 from collections import abc
-from typing import Any, Callable, Collection, Mapping
+from typing import Any, Callable, Mapping
 
 import networkx as nx
 from boltons.setutils import IndexedSet as iset
 
-from .base import Plotter, aslist, astuple, jetsam
+from .base import Items, Plotter, aslist, astuple, jetsam
 from .modifiers import optional, sideffect
 from .network import Network, yield_operations
 from .op import FunctionalOperation, Operation, reparse_operation_data
@@ -98,8 +98,8 @@ def __repr__(self):
 
     def narrow(
         self,
-        inputs: Collection = None,
-        outputs: Collection = None,
+        inputs: Items = None,
+        outputs: Items = None,
         name=None,
         predicate: Callable[[Any, Mapping], bool] = None,
     ) -> "NetworkOperation":
@@ -264,8 +264,8 @@ def compose(
     name,
     op1,
     *operations,
-    needs=None,
-    provides=None,
+    needs: Items = None,
+    provides: Items = None,
     merge=False,
     node_props=None,
     method=None,
@@ -277,13 +277,11 @@ def compose(
 
     :param str name:
         A optional name for the graph being composed by this object.
-
     :param op1:
         syntactically force at least 1 operation
     :param operations:
         Each argument should be an operation instance created using
         ``operation``.
-
     :param bool merge:
         If ``True``, this compose object will attempt to merge together
         ``operation`` instances that represent entire computation graphs.
@@ -303,7 +301,6 @@ def compose(
         if ``"parallel"``, launches multi-threading.
         Set when invoking a composed graph or by
         :meth:`~NetworkOperation.set_execution_method()`.
-
     :param overwrites_collector:
         (optional) a mutable dict to be fillwed with named values.
         If missing, values are simply discarded.

graphtik/network.py

@@ -87,7 +87,7 @@
 import networkx as nx
 from boltons.setutils import IndexedSet as iset
 
-from .base import Plotter, aslist, astuple, jetsam
+from .base import Items, Plotter, aslist, astuple, jetsam
 from .modifiers import optional, sideffect
 from .op import Operation
 
@@ -138,7 +138,7 @@ def __repr__(self):
 
 class _EvictInstruction(str):
     """
-    Execution step to evict a computed value from the `solution`.
+    A step in the ExecutionPlan to evict a computed value from the `solution`.
 
     It's a step in :attr:`ExecutionPlan.steps` for the data-node `str` that
     frees its data-value from `solution` after it is no longer needed,
@@ -153,7 +153,7 @@ def __repr__(self):
 
 class _PinInstruction(str):
     """
-    Execution step to overwrite a computed value in the `solution` from the inputs,
+    A step in the ExecutionPlan to overwrite a computed value in the `solution` from the inputs,
 
     and to store the computed one in the ``overwrites`` instead
     (both `solution` & ``overwrites`` are local-vars in :meth:`~Network.compute()`).
@@ -266,9 +266,7 @@ def __repr__(self):
             "".join(steps),
         )
 
-    def validate(
-        self, inputs: Optional[abc.Collection], outputs: Optional[abc.Collection]
-    ):
+    def validate(self, inputs: Items, outputs: Items):
         """
         Scream on invalid inputs, outputs or no operations in graph.
 
@@ -674,8 +672,8 @@ def _apply_graph_predicate(self, graph, predicate):
 
     def _prune_graph(
         self,
-        inputs: Optional[Collection],
-        outputs: Optional[Collection],
+        inputs: Items,
+        outputs: Items,
         predicate: Callable[[Any, Mapping], bool] = None,
     ) -> Tuple[nx.DiGraph, Collection, Collection, Collection]:
         """
@@ -687,7 +685,6 @@ def _prune_graph(
 
         :param inputs:
             The names of all given inputs.
-
         :param outputs:
             The desired output names.  This can also be ``None``, in which
             case the necessary steps are all graph nodes that are reachable
@@ -793,8 +790,8 @@ def _prune_graph(
 
     def pruned(
         self,
-        inputs: Collection = None,
-        outputs: Collection = None,
+        inputs: Items = None,
+        outputs: Items = None,
         predicate: Callable[[Any, Mapping], bool] = None,
     ) -> "Network":
         """
@@ -824,7 +821,7 @@ def pruned(
         return Network(graph=pruned_dag)
 
     def _build_execution_steps(
-        self, pruned_dag, inputs: Optional[Collection], outputs: Optional[Collection]
+        self, pruned_dag, inputs: Collection, outputs: Optional[Collection]
     ) -> List:
         """
         Create the list of operation-nodes & *instructions* evaluating all
@@ -927,11 +924,7 @@ def add_step_once(step):
 
         return steps
 
-    def compile(
-        self,
-        inputs: Union[Collection, str] = None,
-        outputs: Union[Collection, str] = None,
-    ) -> ExecutionPlan:
+    def compile(self, inputs: Items = None, outputs: Items = None) -> ExecutionPlan:
         """
         Create or get from cache an execution-plan for the given inputs/outputs.
 

graphtik/op.py

@@ -5,11 +5,11 @@
 import abc
 import logging
 from collections import abc as cabc
-from typing import Callable, Collection, Mapping, Tuple, Union
+from typing import Callable, Mapping, Tuple, Union
 
 from boltons.setutils import IndexedSet as iset
 
-from .base import Plotter, aslist, astuple, jetsam
+from .base import Items, Plotter, aslist, astuple, jetsam
 from .modifiers import optional, sideffect, vararg, varargs
 
 log = logging.getLogger(__name__)
@@ -71,8 +71,8 @@ def __init__(
         self,
         fn: Callable,
         name,
-        needs: Union[Collection, str] = None,
-        provides: Union[Collection, str] = None,
+        needs: Items = None,
+        provides: Items = None,
         *,
         parents: Tuple = None,
         node_props: Mapping = None,
@@ -93,6 +93,10 @@ def __init__(
             but also kept for equality/hash check.
         :param node_props:
             added as-is into NetworkX graph
+        :param returns_dict:
+            if true, it means the `fn` returns a dictionary with all `provides`,
+            and no further processing is done on them
+            (i.e. the returned output-values are not zipped with `provides`)
         """
         ## Set op-data early, for repr() to work on errors.
         self.fn = fn
@@ -288,6 +292,8 @@ class operation:
         elements must be returned
     :param bool returns_dict:
         if true, it means the `fn` returns a dictionary with all `provides`,
+        and no further processing is done on them
+        (i.e. the returned output-values are not zipped with `provides`)
     :param node_props:
         added as-is into NetworkX graph
 
@@ -319,8 +325,8 @@ def __init__(
         fn: Callable = None,
         *,
         name=None,
-        needs=None,
-        provides=None,
+        needs: Items = None,
+        provides: Items = None,
         returns_dict=None,
         node_props: Mapping = None,
     ):
@@ -334,10 +340,10 @@ def __init__(
     def withset(
         self,
         *,
-        fn=None,
+        fn: Callable = None,
         name=None,
-        needs=None,
-        provides=None,
+        needs: Items = None,
+        provides: Items = None,
         returns_dict=None,
         node_props: Mapping = None,
     ) -> "operation":
@@ -358,11 +364,11 @@ def withset(
 
     def __call__(
         self,
-        fn=None,
+        fn: Callable = None,
         *,
         name=None,
-        needs=None,
-        provides=None,
+        needs: Items = None,
+        provides: Items = None,
         returns_dict=None,
         node_props: Mapping = None,
     ) -> FunctionalOperation:

graphtik/plot.py

@@ -6,7 +6,7 @@
 import json
 import logging
 import os
-from typing import Any, Callable, List, Mapping, Optional, Tuple, Union
+from typing import Any, Callable, List, Mapping, Tuple, Union
 
 import pydot
 
@@ -79,6 +79,7 @@ def _dot2svg(dot):
     .. TODO:
         Render in jupyter cells fullly on client-side without SVG, using lib:
         https://visjs.github.io/vis-network/docs/network/#importDot
+        Or with plotly https://plot.ly/~empet/14007.embed
 
     """
     pan_zoom_json, element_styles, container_styles = _parse_jupyter_render(dot)
@@ -324,7 +325,6 @@ def render_pydot(dot: pydot.Dot, filename=None, show=False, jupyter_render: str
 
     See :meth:`.Plotter.plot()` for sample code.
     """
-    # TODO: research https://plot.ly/~empet/14007.embed
     # Save plot
     #
     if filename:
@@ -359,7 +359,7 @@ def render_pydot(dot: pydot.Dot, filename=None, show=False, jupyter_render: str
     return dot
 
 
-def legend(filename=None, show=None, jupyter_render: Optional[Mapping] = None):
+def legend(filename=None, show=None, jupyter_render: Mapping = None):
     """Generate a legend for all plots (see :meth:`.Plotter.plot()` for args)"""
 
     _monkey_patch_for_jupyter(pydot)