FEAT(FNOP+.tc+plot+doc) KW(Provides) RENAME Rets-dict

Author: ankostis

docs/source/operations.rst

@@ -154,8 +154,8 @@ to the :func:`.operation` factory, specifically:
 Declarations of *needs* and *provides* is affected by :term:`modifier`\s like
 :func:`.keyword`:
 
-Map inputs to different function arguments
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Map inputs(& outputs) to differently named function arguments (& results)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. autofunction:: graphtik.modifier.keyword
    :noindex:
 
@@ -174,22 +174,29 @@ Calling functions with varargs (``*args``)
 
 .. _aliases:
 
-Aliased `provides`
-^^^^^^^^^^^^^^^^^^
+Interface differently named dependencies: aliases & keyword modifier
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Sometimes, you need to interface functions & operations where they name a
-:term:`dependency` differently.
-This is doable without introducing "pipe-through" interface operation, either
-by annotating certain `needs` with :func:`.keyword` *modifier* (above), or
-by :term:`alias`\sing certain `provides` to different names:
+:term:`dependency` differently.  There are 4 different ways to accomplish that:
 
-   >>> op = operation(str,
-   ...                name="`provides` with `aliases`",
-   ...                needs="anything",
-   ...                provides="real thing",
-   ...                aliases=("real thing", "phony"))
 
-.. graphtik::
+1. Introduce some :term:`"pipe-through" operation <conveyor operation>`
+   (see the example in :ref:`conveyor-function`, below).
+
+2. Annotate certain `needs` with :func:`.keyword` *modifier*
+   (exemplified in the modifier).
+
+3. For a :term:`returns dictionary` operation, annotate certain `provides`
+   with a :func:`.keyword` *modifier* (exemplified in the modifier).
+
+4. :term:`Alias <alias>` (clone) certain `provides` to different names:
+
+       >>> op = operation(str,
+       ...                name="cloning `provides` with an `alias`",
+       ...                provides="real thing",
+       ...                aliases=("real thing", "clone"))
 
+   .. graphtik::
 
 .. _conveyor-function:
 

graphtik/fnop.py

@@ -689,7 +689,14 @@ def _zip_results_returns_dict(self, results, is_rescheduled) -> dict:
                 f"\n  {debug_var_tip}"
             )
 
-        fn_required = fn_expected = self._fn_provides
+        fn_required = self._fn_provides
+        if fn_required:
+            renames = {get_keyword(i): i for i in fn_required}  # +1 useless key: None
+            renames.pop(None, None)
+            fn_expected = fn_required = [get_keyword(i) or i for i in fn_required]
+        else:
+            fn_expected = fn_required = renames = ()
+
         if is_rescheduled:
             # Canceled sfx(ed) are welcomed.
             fn_expected = iset([*fn_expected, *(i for i in self.provides if is_sfx(i))])
@@ -725,6 +732,9 @@ def _zip_results_returns_dict(self, results, is_rescheduled) -> dict:
                     f" {list(missmatched)}\n  {self}\n  {debug_var_tip}"
                 )
 
+        if renames:
+            results = {renames.get(k, k): v for k, v in results.items()}
+
         return results
 
     def _zip_results_plain(self, results, is_rescheduled) -> dict:

graphtik/modifier.py

@@ -471,10 +471,11 @@ def keyword(
     name: str, keyword: str = None, accessor: Accessor = None, jsonp=None
 ) -> _Modifier:
     """
-    Annotate a :term:`needs` that (optionally) maps `inputs` name --> *keyword* argument name.
+    Annotate a :term:`dependency` that maps to a different name in the underlying function.
 
-    The value of a *keyword* dependency is passed in as *keyword argument*
-    to the underlying function.
+    - The value of a *keyword* `needs` dependency is passed in as *keyword argument*
+      to the underlying function.
+    - For *keyword* to work in `provides`, the operation must be a :term:`returns dictionary`.
 
     :param keyword:
         The argument-name corresponding to this named-input.
@@ -507,30 +508,50 @@ def keyword(
 
     **Example:**
 
-    In case the name of the function arguments is different from the name in the
-    `inputs` (or just because the name in the `inputs` is not a valid argument-name),
+    In case the name of a function input argument is different from the name in the
+    :term:`graph` (or just because the name in the `inputs` is not a valid argument-name),
     you may *map* it with the 2nd argument of :func:`.keyword`:
 
         >>> from graphtik import operation, compose, keyword
 
-        >>> @operation(needs=['a', keyword("name-in-inputs", "b")], provides="sum")
-        ... def myadd(a, *, b):
-        ...    return a + b
-        >>> myadd
-        FnOp(name='myadd',
-                            needs=['a', 'name-in-inputs'(>'b')],
-                            provides=['sum'],
-                            fn='myadd')
+        >>> @operation(needs=[keyword("name-in-inputs", "fn_name")], provides="result")
+        ... def foo(*, fn_name):  # it works also with non-positional args
+        ...    return fn_name
+        >>> foo
+        FnOp(name='foo',
+             needs=['name-in-inputs'(>'fn_name')],
+             provides=['result'],
+             fn='foo')
 
-        >>> graph = compose('mygraph', myadd)
-        >>> graph
-        Pipeline('mygraph', needs=['a', 'name-in-inputs'], provides=['sum'], x1 ops: myadd)
+        >>> pipe = compose('map a need', foo)
+        >>> pipe
+        Pipeline('map a need', needs=['name-in-inputs'], provides=['result'], x1 ops: foo)
 
-        >>> sol = graph.compute({"a": 5, "name-in-inputs": 4})['sum']
-        >>> sol
-        9
+        >>> sol = pipe.compute({"name-in-inputs": 4})
+        >>> sol['result']
+        4
 
         .. graphtik::
+
+    You can do the same thing to the results of a :term:`returns dictionary` operation:
+
+        >>> op = operation(lambda: {"fn key": 1},
+        ...                name="renaming `provides` with a `keyword`",
+        ...                provides=keyword("graph key", "fn key"),
+        ...                returns_dict=True)
+        >>> op
+        FnOp(name='renaming `provides` with a `keyword`',
+             provides=['graph key'(>'fn key')],
+             fn{}='<lambda>')
+
+    .. graphtik::
+
+    .. hint::
+        Mapping `provides` names wouldn't make sense for regular operations, since
+        these are defined arbitrarily at the operation level.
+        OTOH, the result names of :term:`returns dictionary` operation are decided
+        by the underlying function, which may lie beyond the control of the user
+        (e.g. from a 3rd-party object).
     """
     # Must pass a truthy `keyword` bc cstor cannot not know its keyword.
     return _modifier(name, keyword=keyword or name, accessor=accessor, jsonp=jsonp)

test/test_op.py

@@ -180,6 +180,18 @@ def test_returns_dict_extra():
     assert len(res) == 2  # check it did not mutate results
 
 
+def test_returns_dict_keyword_renames():
+    res = {"1": 1, "2": 2}
+    op = operation(lambda: res, provides=keyword("11", "1"), returns_dict=True)
+    assert op.compute({}) == {"11": 1}
+    assert len(res) == 2  # check it did not mutate results
+
+    res = {"1": 1, "11": 11}
+    op = operation(lambda: res, provides=keyword("11", "1"), returns_dict=True)
+    assert op.compute({}) == {"11": 1}  # original '11' was discarded
+    assert len(res) == 2  # check it did not mutate results
+
+
 @pytest.fixture(params=[None, ["a", "b"]])
 def asked_outputs(request):
     return request.param