BREAK/FEAT(OP, DOC): Unify OP-BUILDER ...

Specifically the last empty call at the end ``()`` is not needed (or possible)::
    operation(str, name=...)()
became simply like that::
    operation(str, name=...)

+ DOC: review and shorten `operations.rst`.
+ DROP: `operator` class--> function.
+ ENH: Fancy Op-decorator supports reasonab;le behavior.

Author: ankostis

CHANGES.rst

@@ -203,7 +203,7 @@ v6.0.0 (13 Apr 2020, @ankostis): New Plotting Device...
 
       >>> from graphtik import operation, varargs
       >>> from graphtik.plot import get_active_plotter
-      >>> op = operation(print, name='print-something', needs=varargs("any"), provides="str")()
+      >>> op = operation(print, name='print-something', needs=varargs("any"), provides="str")
       >>> dot = op.plot(plotter=get_active_plotter().with_styles(kw_legend=None))
 
   + ENH: Convey graph, node & edge ("non-private") attributes from the *networkx* graph
@@ -704,7 +704,7 @@ The first non pre-release for 2.x train.
 + break(jetsam): drop "graphtik_` prefix from annotated attribute
 
 + ENH(op): now ``operation()`` supported the "builder pattern" with
-  :meth:`.operation.withset()`.
+  ``.operation.withset()`` method.
 
 + REFACT: renamed internal package `functional --> nodes` and moved classes around,
   to break cycles easier, (``base`` works as supposed to), not to import early  everything,

docs/source/arch.rst

@@ -49,8 +49,7 @@ Architecture
         corresponding `network`\s.
 
         .. Tip::
-            - Use :class:`.operation` builder class to construct
-              :class:`.FunctionalOperation` instances.
+            - Use :func:`.operation` factory to construct :class:`.FunctionalOperation` instances.
             - Use :func:`~.graphtik.compose()` factory to prepare the `net` internally,
               and build :class:`.NetworkOperation` instances.
 

docs/source/composition.rst

@@ -267,7 +267,7 @@ Operations with partial outputs (*rescheduled*)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In case the actually produce `outputs` depend on some condition in the `inputs`,
 the `solution` has to :term:`reschedule` the plan amidst execution, and consider the
-actual `provides` delivered.
+actual `provides` delivered:
 
 
     >>> @operation(rescheduled=1,

docs/source/index.rst

@@ -78,8 +78,8 @@ Compose the ``abspow`` function along with ``mul`` & ``sub``  built-ins
 into a computation :term:`graph`:
 
    >>> graphop = compose("graphop",
-   ...    operation(needs=["a", "b"], provides=["ab"])(mul),
-   ...    operation(sub, needs=["a", "ab"], provides=["a_minus_ab"])(),
+   ...    operation(mul, needs=["a", "b"], provides=["ab"]),
+   ...    operation(sub, needs=["a", "ab"], provides=["a_minus_ab"]),
    ...    abs_qubed,
    ... )
    >>> graphop

docs/source/operations.rst

@@ -1,100 +1,79 @@
 Operations
 ==========
 
-At a high level, an operation is a node in a computation graph.
-Graphtik uses an :class:`.Operation` class to abstractly represent these computations.
-The class specifies the *requirements* for a function to participate
-in a computation graph; those are its input-data **needs**, and the output-data
-it **provides**.
+At a high level, an :term:`operation` is a function in a computation :term:`pipeline`,
+abstractly represented by the :class:`.Operation` class.
+This class specifies the :term:`dependencies <dependency>` of the *operation*
+in the *pipeline*.
 
-The :class:`.FunctionalOperation` provides a lightweight wrapper
-around an arbitrary function to define those specifications.
+The :class:`.FunctionalOperation` provides a concrete lightweight wrapper
+around any arbitrary function to define those *dependencies*.
+Instead of constructing it directly, prefer to instantiate it by calling
+the :func:`.operation()` factory.
 
-.. autoclass:: graphtik.op.FunctionalOperation
-   :members: __init__, __call__, compute
-   :noindex:
-
-The ``operation`` builder factory
----------------------------------
-
-There is a better way to instantiate an ``FunctionalOperation`` than simply constructing it:
-use the ``operation`` builder class:
-
-.. autoclass:: graphtik.operation
-   :members:  withset, __call__
-   :special-members:
-   :noindex:
 
 Operations are just functions
 ------------------------------
 
-At the heart of each ``operation`` is just a function, any arbitrary function.
-Indeed, you can instantiate an ``operation`` with a function and then call it
+At the heart of each `operation` is just a function, any arbitrary function.
+Indeed, you can wrap an existing function into an `operation`, and then call it
 just like the original function, e.g.:
 
    >>> from operator import add
    >>> from graphtik import operation
 
-   >>> add_op = operation(name='add_op', needs=['a', 'b'], provides=['a_plus_b'])(add)
+   >>> add_op = operation(add,
+   ...                    needs=['a', 'b'],
+   ...                    provides=['a_plus_b'])
+   >>> add_op
+   FunctionalOperation(name='add', needs=['a', 'b'], provides=['a_plus_b'], fn='add')
 
    >>> add_op(3, 4) == add(3, 4)
    True
 
+   But ``__call__()`` is just to facilitate quick experimentation - it does not
+   perform any checks or matching of *needs*/*provides* to function arguments
+   & results (which happen when :term:`pipeline`\s :term:`compute`).
+
+   The way Graphtik works is by invoking their :meth:`.Operation.compute()` method,
+   which, among others, allow to specify what results you desire to receive back
+   (read more on :ref:`graph-computations`).
+
 
 Specifying graph structure: ``provides`` and ``needs``
 ------------------------------------------------------
 
-Of course, each ``operation`` is more than just a function.
-It is a node in a computation graph, depending on other nodes in the graph for input data and
-supplying output data that may be used by other nodes in the graph (or as a graph output).
-This graph structure is specified via the ``provides`` and ``needs`` arguments
-to the ``operation`` constructor.  Specifically:
+Each :term:`operation` is a node in a computation :term:`graph`,
+depending and supplying data from and to other nodes (via the :term:`solution`),
+in order to :term:`compute`.
 
-* ``provides``: this argument names the outputs (i.e. the returned values) of a given ``operation``.
-  If multiple outputs are specified by ``provides``, then the return value of the function
-  comprising the ``operation`` must return an iterable.
+This graph structure is specified (mostly) via the ``provides`` and ``needs`` arguments
+to the :func:`.operation` factory, specifically:
 
-* ``needs``: this argument names data that is needed as input by a given ``operation``.
-  Each piece of data named in needs may either be provided by another ``operation``
-  in the same graph (i.e. specified in the ``provides`` argument of that ``operation``),
-  or it may be specified as a named input to a graph computation
-  (more on graph computations :ref:`here <graph-computations>`).
+``needs``
+   this argument names the list of (positionally ordered) :term:`inputs` data the `operation`
+   requires to receive from *solution*.
+   The list corresponds, roughly, to the arguments of the underlying function
+   (plus any :term:`sideffects`).
 
-When many operations are composed into a computation graph (see :ref:`graph-composition` for more on that),
-Graphtik matches up the values in their ``needs`` and ``provides`` to form the edges of that graph.
+   It can be a single string, in which case a 1-element iterable is assumed.
 
-Let's look again at the operations from the script in :ref:`quick-start`,
-for example:
+   :seealso: :term:`needs`, :term:`modifier`, :attr:`.FunctionalOperation.needs`,
+      :attr:`.FunctionalOperation.op_needs`, :attr:`.FunctionalOperation._fn_needs`
 
-   >>> from operator import mul, sub
-   >>> from functools import partial
-   >>> from graphtik import compose, operation
-
-   >>> # Computes |a|^p.
-   >>> def abspow(a, p):
-   ...   c = abs(a) ** p
-   ...   return c
+``provides``
+   this argument names the list of (positionally ordered) :term:`outputs` data
+   the operation provides into the *solution*.
+   The list corresponds, roughly, to the returned values of the `fn`
+   (plus any :term:`sideffects` & :term:`alias`\es).
 
-   >>> # Compose the mul, sub, and abspow operations into a computation graph.
-   >>> graphop = compose("graphop",
-   ...    operation(name="mul1", needs=["a", "b"], provides=["ab"])(mul),
-   ...    operation(name="sub1", needs=["a", "ab"], provides=["a_minus_ab"])(sub),
-   ...    operation(name="abspow1", needs=["a_minus_ab"], provides=["abs_a_minus_ab_cubed"])
-   ...    (partial(abspow, p=3))
-   ... )
+   It can be a single string, in which case a 1-element iterable is assumed.
 
-.. Tip::
-   Notice the use of :func:`functools.partial()` to set parameter ``p`` to a constant value.
-
-The ``needs`` and ``provides`` arguments to the operations in this script define
-a computation graph that looks like this (where the oval are *operations*,
-squares/houses are *data*):
-
-.. graphtik::
-
-.. Tip::
-  See :ref:`plotting` on how to make diagrams like this.
+   If they are more than one, the underlying function must return an iterable
+   with same number of elements (unless it :term:`returns dictionary`).
 
+   :seealso: :term:`provides`, :term:`modifier`, :attr:`.FunctionalOperation.provides`,
+      :attr:`.FunctionalOperation.op_provides`, :attr:`.FunctionalOperation._fn_provides`
 
 .. _aliases:
 
@@ -110,87 +89,113 @@ on the `provides` side:
    ...                name="`provides` with `aliases`",
    ...                needs="anything",
    ...                provides="real thing",
-   ...                aliases=("real thing", "phony"))()
+   ...                aliases=("real thing", "phony"))
 
 .. graphtik::
 
-Instantiating operations
-------------------------
 
-There are several ways to instantiate an ``operation``, each of which might be more suitable for different scenarios.
+Considerations for when building pipelines
+------------------------------------------
+When many operations are composed into a computation graph, Graphtik matches up
+the values in their *needs* and *provides* to form the edges of that graph
+(see :ref:`graph-composition` for more on that), like the operations from the script
+in :ref:`quick-start`:
 
-Decorator specification
-^^^^^^^^^^^^^^^^^^^^^^^
+   >>> from operator import mul, sub
+   >>> from functools import partial
+   >>> from graphtik import compose, operation
 
-If you are defining your computation graph and the functions that comprise it all in the same script,
-the decorator specification of ``operation`` instances might be particularly useful,
-as it allows you to assign computation graph structure to functions as they are defined.
-Here's an example:
+   >>> def abspow(a, p):
+   ...   """Compute |a|^p. """
+   ...   c = abs(a) ** p
+   ...   return c
 
-   >>> from graphtik import operation, compose
+   >>> # Compose the mul, sub, and abspow operations into a computation graph.
+   >>> graphop = compose("graphop",
+   ...    operation(mul, needs=["a", "b"], provides=["ab"]),
+   ...    operation(sub, needs=["a", "ab"], provides=["a_minus_ab"]),
+   ...    operation(name="abspow1", needs=["a_minus_ab"], provides=["abs_a_minus_ab_cubed"])
+   ...    (partial(abspow, p=3))
+   ... )
+   >>> graphop
+   NetworkOperation('graphop',
+                    needs=['a', 'b', 'ab', 'a_minus_ab'],
+                    provides=['ab', 'a_minus_ab', 'abs_a_minus_ab_cubed'],
+                    x3 ops: mul, sub, abspow1)
 
-   >>> @operation(name='foo_op', needs=['a', 'b', 'c'], provides='foo')
-   ... def foo(a, b, c):
-   ...   return c * (a + b)
 
-   >>> graphop = compose('foo_graph', foo)
+- Notice that if ``name`` is not given, it is deduced from the function name.
+- Notice the use of :func:`functools.partial()` to set parameter ``p`` to a constant value.
+- And this is done by calling once more the returned "decorator* from :func:`operation()`,
+  when called without a functions.
+
+The ``needs`` and ``provides`` arguments to the operations in this script define
+a computation graph that looks like this:
 
 .. graphtik::
+.. Tip::
+  See :ref:`plotting` on how to make diagrams like this.
 
+Builder pattern
+^^^^^^^^^^^^^^^
+There 2 ways to instantiate an :class:`.FunctionalOperation`\s, each one suitable
+for different scenarios, and so far we have only seen the 1st one:
 
-Functional specification
-^^^^^^^^^^^^^^^^^^^^^^^^
+We've seen that calling manually :func:`.operation()` allows putting into a pipeline
+functions that are defined elsewhere (e.g. in another module, or are system functions).
 
-If the functions underlying your computation graph operations are defined elsewhere
-than the script in which your graph itself is defined (e.g. they are defined in another module,
-or they are system functions), you can use the functional specification of ``operation`` instances:
+But that method is also useful if you want to create multiple operation instances
+with similar attributes, e.g. ``needs``:
 
-   >>> from operator import add, mul
-   >>> from graphtik import operation, compose
+   >>> op_factory = operation(needs=['a'])
 
-   >>> add_op = operation(name='add_op', needs=['a', 'b'], provides='sum')(add)
-   >>> mul_op = operation(name='mul_op', needs=['c', 'sum'], provides='product')(mul)
+Notice that we specified a `fn`, in order to get back a :class:`.FunctionalOperation`
+instance (and not a decorator).
 
-   >>> graphop = compose('add_mul_graph', add_op, mul_op)
+   >>> from functools import partial
 
-.. graphtik::
+   >>> def mypow(a, p=2):
+   ...    return a ** p
 
+   >>> pow_op2 = op_factory.withset(fn=mypow, provides="^2")
+   >>> pow_op3 = op_factory.withset(fn=partial(mypow, p=3), name='pow_3', provides='^3')
+   >>> pow_op0 = op_factory.withset(fn=lambda a: 1, name='pow_0', provides='^0')
 
-The functional specification is also useful if you want to create multiple ``operation``
-instances from the same function, perhaps with different parameter values, e.g.:
+   >>> graphop = compose('powers', pow_op2, pow_op3, pow_op0)
+   >>> graphop
+   NetworkOperation('powers', needs=['a'], provides=['^2', '^3', '^0'], x3 ops:
+      mypow, pow_3, pow_0)
 
-   >>> from functools import partial
 
-   >>> def mypow(a, p=2):
-   ...    return a ** p
+   >>> graphop(a=2)
+   {'a': 2, '^2': 4, '^3': 8, '^0': 1}
 
-   >>> pow_op1 = operation(name='pow_op1', needs=['a'], provides='a_squared')(mypow)
-   >>> pow_op2 = operation(name='pow_op2', needs=['a'], provides='a_cubed')(partial(mypow, p=3))
+.. graphtik::
 
-   >>> graphop = compose('two_pows_graph', pow_op1, pow_op2)
 
-A slightly different approach can be used here to accomplish the same effect
-by creating an operation "builder pattern":
+Decorator specification
+^^^^^^^^^^^^^^^^^^^^^^^
 
-   >>> def mypow(a, p=2):
-   ...    return a ** p
+If you are defining your computation graph and the functions that comprise it all in the same script,
+the decorator specification of ``operation`` instances might be particularly useful,
+as it allows you to assign computation graph structure to functions as they are defined.
+Here's an example:
 
-   >>> pow_op_factory = operation(mypow, needs=['a'], provides='a_squared')
+   >>> from graphtik import operation, compose
 
-   >>> pow_op1 = pow_op_factory(name='pow_op1')
-   >>> pow_op2 = pow_op_factory.withset(name='pow_op2', provides='a_cubed')(partial(mypow, p=3))
-   >>> pow_op3 = pow_op_factory(lambda a: 1, name='pow_op3')
+   >>> @operation(name='foo_op', needs=['a', 'b', 'c'], provides='foo')
+   ... def foo(a, b, c):
+   ...   return c * (a + b)
 
-   >>> graphop = compose('two_pows_graph', pow_op1, pow_op2, pow_op3)
-   >>> graphop(a=2)
-   {'a': 2, 'a_squared': 4, 'a_cubed': 1}
+   >>> graphop = compose('foo_graph', foo)
+
+.. graphtik::
 
-.. Note::
-   You cannot call again the factory to overwrite the *function*,
-   you have to use either the ``fn=`` keyword with ``withset()`` method or
-   call once more.
 
 
 Modifiers on `operation` `needs` and `provides`
 -----------------------------------------------
-see `mod:`.modifiers`.
+Annotations on a `dependency` such as `optionals` & `sideffects` modify their behavior,
+and eventually the :term:`pipeline`.
+
+Read `mod:`.modifiers` for more.

graphtik/netop.py

@@ -157,7 +157,7 @@ def __repr__(self):
         steps = (
             "".join(f"\n  +--{s}" for s in ops)
             if is_debug()
-            else ", ".join(s.name for s in ops)
+            else ", ".join(str(s.name) for s in ops)
         )
         return f"{clsname}({self.name!r}, needs={needs}, provides={provides}, x{len(ops)} ops: {steps})"