REFACT(OP): operation() as BUILDER_PATTERN

+ drop: operation() does not inherit Operation
  (that was buggy design callling for mistakes)
+ enh: operation().withset() to function as builder.
+ refact: simplify repr() using f-strings * defaults.
+ refact: move (new) _validate() in FuncOp class.

Author: ankostis

CHANGES.rst

@@ -4,8 +4,11 @@ Graphtik Changelog
 
 TODO
 ====
+See also `gg:`1`.
+
 + [ ] use a "start-node" to insert input-values in solution
 + [ ] typo(test): overriden-->overriDDen
++ [ ] support functions with ``*args`` and ``**kwargs``.
 
 
 v2.0.1b0 (18 Oct 2019): better plan with perfect evictions 

docs/source/plotting.rst

@@ -83,12 +83,12 @@ with the folllowing properties, as a debug aid:
  'executed': set(),
  'network': Network(
     +--a
-    +--FunctionalOperation(name='screamer', needs=['a'], provides=['foo'])
+    +--FunctionalOperation(name='screamer', needs=['a'], provides=['foo'], fn='scream')
     +--foo),
- 'operation': FunctionalOperation(name='screamer', needs=['a'], provides=['foo']),
+ 'operation': FunctionalOperation(name='screamer', needs=['a'], provides=['foo'], fn='scream'),
  'outputs': None,
  'plan': ExecutionPlan(inputs=('a',), outputs=(), steps:
-  +--FunctionalOperation(name='screamer', needs=['a'], provides=['foo'])),
+  +--FunctionalOperation(name='screamer', needs=['a'], provides=['foo'], fn='scream')),
  'provides': ['foo'],
  'results': None,
  'solution': {'a': None}}

graphtik/base.py

@@ -14,6 +14,13 @@
 log = logging.getLogger(__name__)
 
 
+def aslist(i):
+    """utility used through out"""
+    if i and not isinstance(i, str):
+        return list(i)
+    return i
+
+
 def jetsam(ex, locs, *salvage_vars: str, annotation="jetsam", **salvage_mappings):
     """
     Annotate exception with salvaged values from locals() and raise!
@@ -174,6 +181,35 @@ def compute(self, named_inputs, outputs=None):
         """
         raise NotImplementedError("Abstract %r! cannot compute()!" % self)
 
+    def _validate(self):
+        from .modifiers import optional
+
+        if not self.name:
+            raise ValueError(f"Operation needs a name, got: {self.name}")
+
+        needs = self.needs
+        # Allow single value for needs parameter
+        if isinstance(needs, str) and not isinstance(needs, optional):
+            needs = [needs]
+        if not needs:
+            raise ValueError(f"Empty `needs` given: {needs!r}")
+        if not all(n for n in needs):
+            raise ValueError(f"One item in `needs` is null: {needs!r}")
+        if not isinstance(needs, (list, tuple)):
+            raise ValueError(f"Bad `needs`, not (list, tuple): {needs!r}")
+        self.needs = needs
+
+        # Allow single value for provides parameter
+        provides = self.provides
+        if isinstance(provides, str):
+            provides = [provides]
+        if provides and not all(n for n in provides):
+            raise ValueError(f"One item in `provides` is null: {provides!r}")
+        provides = provides or ()
+        if not isinstance(provides, (list, tuple)):
+            raise ValueError(f"Bad `provides`, not (list, tuple): {provides!r}")
+        self.provides = provides or ()
+
     def _after_init(self):
         """
         This method is a hook for you to override. It gets called after this
@@ -188,18 +224,10 @@ def __repr__(self):
         """
         Display more informative names for the Operation class
         """
-
-        def aslist(i):
-            if i and not isinstance(i, str):
-                return list(i)
-            return i
-
-        return u"%s(name='%s', needs=%s, provides=%s)" % (
-            self.__class__.__name__,
-            getattr(self, "name", None),
-            aslist(getattr(self, "needs", None)),
-            aslist(getattr(self, "provides", None)),
-        )
+        clsname = type(self).__name__
+        needs = aslist(self.needs)
+        provides = aslist(self.provides)
+        return f"{clsname}(name={self.name!r}, needs={needs!r}, provides={provides!r})"
 
 
 class NetworkOperation(Operation, plot.Plotter):

graphtik/functional.py

@@ -3,15 +3,31 @@
 import networkx as nx
 from boltons.setutils import IndexedSet as iset
 
-from .base import jetsam, NetworkOperation, Operation
+from .base import NetworkOperation, Operation, aslist, jetsam
 from .modifiers import optional, sideffect
 from .network import Network
 
 
 class FunctionalOperation(Operation):
+    """Use operation() to build instances of this class instead"""
     def __init__(self, fn=None, **kwargs):
         self.fn = fn
         Operation.__init__(self, **kwargs)
+        self._validate()
+
+    def __repr__(self):
+        """
+        Display more informative names for the Operation class
+        """
+        needs = aslist(self.needs)
+        provides = aslist(self.provides)
+        fn_name = self.fn and getattr(self.fn, "__name__", str(self.fn))
+        return f"FunctionalOperation(name={self.name!r}, needs={needs!r}, provides={provides!r}, fn={fn_name!r})"
+
+    def _validate(self):
+        super()._validate()
+        if not self.fn or not callable(self.fn):
+            raise ValueError(f"Operation was not provided with a callable: {self.fn}")
 
     def compute(self, named_inputs, outputs=None):
         try:
@@ -65,57 +81,63 @@ def __call__(self, *args, **kwargs):
         return self.fn(*args, **kwargs)
 
 
-class operation(Operation):
+class operation:
     """
-    This object represents an operation in a computation graph.  Its
-    relationship to other operations in the graph is specified via its
-    ``needs`` and ``provides`` arguments.
+    A builder for graph-operations wrapping functions.
 
     :param function fn:
         The function used by this operation.  This does not need to be
         specified when the operation object is instantiated and can instead
         be set via ``__call__`` later.
-
     :param str name:
         The name of the operation in the computation graph.
-
     :param list needs:
         Names of input data objects this operation requires.  These should
         correspond to the ``args`` of ``fn``.
-
     :param list provides:
         Names of output data objects this operation provides.
 
-    """
+    :return:
+        when called, it returns a :class:`FunctionalOperation`
 
-    def __init__(self, fn=None, **kwargs):
-        self.fn = fn
-        Operation.__init__(self, **kwargs)
+    **Example:**
+    
+    Here it is an example of it use with the "builder pattern"::
+
+        >>> from graphtik import operation
+
+        >>> opb = operation(name='add_op')
+        >>> opb.withset(needs=['a', 'b'])
+        operation(name='add_op', needs=['a', 'b'], provides=None, fn=None)
+        >>> opb.withset(provides='SUM', fn=sum)
+        operation(name='add_op', needs=['a', 'b'], provides='SUM', fn='sum')
+    
+    You may keep calling ``withset()`` till you invoke ``__call__()`` on the builder;
+    then you get te actual :class:`Operation` instance::
 
-    def _normalize_kwargs(self, kwargs):
+        >>> # Create `Operation` and overwrite function at the last moment.
+        >>> opb(sum)
+        FunctionalOperation(name='add_op', needs=['a', 'b'], provides=['SUM'], fn='sum')
+    """
 
-        # Allow single value for needs parameter
-        needs = kwargs["needs"]
-        if isinstance(needs, str) and not isinstance(needs, optional):
-            assert needs, "empty string provided for `needs` parameters"
-            kwargs["needs"] = [needs]
+    fn = name = needs = provides = None
 
-        # Allow single value for provides parameter
-        provides = kwargs.get("provides")
-        if isinstance(provides, str):
-            assert provides, "empty string provided for `needs` parameters"
-            kwargs["provides"] = [provides]
+    def __init__(self, fn=None, *, name=None, needs=None, provides=None):
+        self.withset(fn=fn, name=name, needs=needs, provides=provides)
 
-        assert kwargs["name"], "operation needs a name"
-        assert isinstance(kwargs["needs"], list), "no `needs` parameter provided"
-        assert isinstance(kwargs["provides"], list), "no `provides` parameter provided"
-        assert hasattr(
-            kwargs["fn"], "__call__"
-        ), "operation was not provided with a callable"
+    def withset(self, *, fn=None, name=None, needs=None, provides=None):
+        if fn is not None:
+            self.fn = fn
+        if name is not None:
+            self.name = name
+        if needs is not None:
+            self.needs = needs
+        if provides is not None:
+            self.provides = provides
 
-        return kwargs
+        return self
 
-    def __call__(self, fn=None, **kwargs):
+    def __call__(self, fn=None, *, name=None, needs=None, provides=None):
         """
         This enables ``operation`` to act as a decorator or as a functional
         operation, for example::
@@ -138,35 +160,18 @@ def myadd(a, b):
             composed into a computation graph.
         """
 
-        if fn is not None:
-            self.fn = fn
-
-        total_kwargs = {}
-        total_kwargs.update(vars(self))
-        total_kwargs.update(kwargs)
-        total_kwargs = self._normalize_kwargs(total_kwargs)
+        self.withset(fn=fn, name=name, needs=needs, provides=provides)
 
-        return FunctionalOperation(**total_kwargs)
+        return FunctionalOperation(**vars(self))
 
     def __repr__(self):
         """
         Display more informative names for the Operation class
         """
-
-        def aslist(i):
-            if i and not isinstance(i, str):
-                return list(i)
-            return i
-
-        func_name = getattr(self, "fn")
-        func_name = func_name and getattr(func_name, "__name__", None)
-        return u"%s(name='%s', needs=%s, provides=%s, fn=%s)" % (
-            self.__class__.__name__,
-            getattr(self, "name", None),
-            aslist(getattr(self, "needs", None)),
-            aslist(getattr(self, "provides", None)),
-            func_name,
-        )
+        needs = aslist(self.needs)
+        provides = aslist(self.provides)
+        fn_name = self.fn and getattr(self.fn, "__name__", str(self.fn))
+        return f"operation(name={self.name!r}, needs={needs!r}, provides={provides!r}, fn={fn_name!r})"
 
 
 class compose(object):

graphtik/modifiers.py

@@ -104,7 +104,7 @@ class sideffect(str):
         ...           name="upd_prices",
         ...           needs=["sales_df", "price"],
         ...           provides=[sideffect("price")])
-        operation(name='upd_prices', needs=['sales_df', 'price'], provides=['sideffect(price)'], fn=upd_prices)
+        operation(name='upd_prices', needs=['sales_df', 'price'], provides=['sideffect(price)'], fn='upd_prices')
 
     .. note::
         An ``operation`` with *sideffects* outputs only, have functions that return