BREAK(modifs): rename MAPPED-->KEYWORD

Author: ankostis

CHANGES.rst

@@ -90,6 +90,7 @@ Changelog
 
 v8.3.0.dev0 (XX May 2020, @ankostis): drop sol-finalize
 =======================================================
++ BREAK: rename ``mapped --> keyword``, which conveys the mot important meaning.
 + DROP Solution.finalized() method -- has stopped being used to reverse values
   since sfxed have been introduced (v7+).
 

docs/source/operations.rst

@@ -152,11 +152,11 @@ to the :func:`.operation` factory, specifically:
       :attr:`.FunctionalOperation.op_provides`, :attr:`.FunctionalOperation._fn_provides`
 
 Declarations of *needs* and *provides* is affected by :term:`modifier`\s like
-:func:`.mapped`:
+:func:`.keyword`:
 
 Map inputs to different function arguments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autofunction:: graphtik.modifiers.mapped
+.. autofunction:: graphtik.modifiers.keyword
    :noindex:
 
 Operations may execute with missing inputs
@@ -179,7 +179,7 @@ Aliased `provides`
 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:`.mapped` `modifiers` (above), or
+by annotating certain `needs` with :func:`.keyword` `modifiers` (above), or
 by :term:`alias`\sing certain `provides` to different names:
 
    >>> op = operation(str,

graphtik/__init__.py

@@ -15,7 +15,7 @@
 from .op import NO_RESULT, NO_RESULT_BUT_SFX, operation
 from .pipeline import NULL_OP, compose
 from .modifiers import (
-    mapped,
+    keyword,
     optional,
     sfx,
     sfxed,

graphtik/modifiers.py

@@ -18,7 +18,7 @@
 When printed, *modifiers* annotate regular or sideffect dependencies with
 these **diacritics**::
 
-    >   : mapped (fn_keyword)
+    >   : keyword (fn_keyword)
     ?   : optional (fn_keyword)
     *   : vararg
     +   : varargs
@@ -34,7 +34,7 @@
 _modifier_cstor_matrix = {
 # (7, kw, opt, sfxed, sfx): (STR, REPR, FUNC) OR None
 70000: None,
-71000: (       "%(dep)s",                  "'%(dep)s'(%(kw)s)"           , "mapped"),
+71000: (       "%(dep)s",                  "'%(dep)s'(%(kw)s)"           , "keyword"),
 71100: (       "%(dep)s",                  "'%(dep)s'(?%(kw)s)"          , "optional"),
 70200: (       "%(dep)s",                  "'%(dep)s'(*)"                , "vararg"),
 70300: (       "%(dep)s",                  "'%(dep)s'(+)"                , "varargs"),
@@ -75,7 +75,7 @@ class _Modifier(str):
 
     It is private, in the sense that users should use only:
 
-    - the factory functions :func:`.mapped`, :func:`optional` etc,
+    - the factory functions :func:`.keyword`, :func:`optional` etc,
     - the predicates :func:`is_optional()`, :func:`is_pure_sfx()` predicates, etc,
     - and the :func:`dep_renamed()`, :func:`dep_stripped()` conversion functions
 
@@ -101,7 +101,7 @@ class _Modifier(str):
     fn_kwarg: str
     #: required is None, regular optional or varargish?
     #: :func:`is_optional()` returns it.
-    #: All regulars are `mapped`.
+    #: All regulars are `keyword`.
     optional: _Optionals
     #: Has value only for sideffects: the pure-sideffect string or
     #: the existing :term:`sideffected` dependency.
@@ -235,11 +235,11 @@ def _modifier(
     return _Modifier(name, fn_kwarg, optional, sideffected, sfx_list, _repr, func)
 
 
-def mapped(name: str, fn_kwarg: str = None):
+def keyword(name: str, fn_kwarg: str = None):
     """
-    Annotate a :term:`needs` that (optionally) map `inputs` name --> argument-name.
+    Annotate a :term:`needs` that (optionally) maps `inputs` name --> *keyword* argument name.
 
-    The value of a mapped dependencies is passed in as *keyword argument*
+    The value of a *keyword* dependency is passed in as *keyword argument*
     to the underlying function.
 
     :param fn_kwarg:
@@ -261,11 +261,11 @@ def mapped(name: str, fn_kwarg: str = None):
 
     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),
-    you may *map* it with the 2nd argument of :func:`.mapped`:
+    you may *map* it with the 2nd argument of :func:`.keyword`:
 
-        >>> from graphtik import operation, compose, mapped
+        >>> from graphtik import operation, compose, keyword
 
-        >>> @operation(needs=['a', mapped("name-in-inputs", "b")], provides="sum")
+        >>> @operation(needs=['a', keyword("name-in-inputs", "b")], provides="sum")
         ... def myadd(a, *, b):
         ...    return a + b
         >>> myadd
@@ -284,7 +284,7 @@ def mapped(name: str, fn_kwarg: str = None):
 
         .. graphtik::
     """
-    # Must pass a truthy `fn_kwarg` bc cstor cannot not know its mapped.
+    # Must pass a truthy `fn_kwarg` bc cstor cannot not know its keyword.
     return _modifier(name, fn_kwarg=fn_kwarg or name)
 
 
@@ -294,7 +294,7 @@ def optional(name: str, fn_kwarg: str = None):
 
     received only if present in the `inputs` (when operation is invoked).
 
-    The value of an optional is passed in as a *keyword argument*
+    The value of an *optional* dependency is passed in as a *keyword argument*
     to the underlying function.
 
     :param fn_kwarg:
@@ -331,7 +331,7 @@ def optional(name: str, fn_kwarg: str = None):
         >>> graph(a=5)
         {'a': 5, 'sum': 5}
 
-    Like :func:`.mapped` you may map input-name to a different function-argument:
+    Like :func:`.keyword` you may map input-name to a different function-argument:
 
         >>> operation(needs=['a', optional("quasi-real", "b")],
         ...           provides="sum"
@@ -657,9 +657,9 @@ def sfxed_varargs(dependency: str, sfx0: str, *sfx_list: str):
 
 def is_mapped(dep) -> Optional[str]:
     """
-    Check if a :term:`dependency` is mapped (and get it).
+    Check if a :term:`dependency` is keyword (and get it).
 
-    All non-varargish optionals are "mapped" (including sideffected ones).
+    All non-varargish optionals are "keyword" (including sideffected ones).
 
     :return:
         the :attr:`fn_kwarg`
@@ -727,7 +727,7 @@ def dep_renamed(dep, ren):
     """
     Renames `dep` as `ren` or call `ren`` (if callable) to decide its name,
 
-    preserving any :func:`mapped` to old-name.
+    preserving any :func:`keyword` to old-name.
 
     For :term:`sideffected` it renames the dependency (not the *sfx-list*) --
     you have to do it that manually with a custom renamer-function, if ever

graphtik/plot.py

@@ -624,9 +624,8 @@ class Theme:
     #: Rendered if ``fn_kwarg`` exists in `nx_attrs`.
     kw_edge_mapping_fn_kwarg = {
         "fontsize": 11,  # default: 14
-        "label": make_template(
-            "<<I>(mapped)</I><BR/>{{ nx_attrs['fn_kwarg'] | eee }}>"
-        ),
+        "fontname": "italic",
+        "label": make_template("<&gt;{{ nx_attrs['fn_kwarg'] | eee }}>"),
     }
     kw_edge_pruned = {"color": Ref("pruned_color")}
     kw_edge_rescheduled = {"style": ["dashed"]}

test/test_modifiers.py

@@ -6,7 +6,7 @@
     dep_renamed,
     dep_singularized,
     dep_stripped,
-    mapped,
+    keyword,
     optional,
     sfx,
     sfxed,
@@ -26,9 +26,9 @@ def test_serialize_modifier(ser_method):
 @pytest.mark.parametrize(
     "mod, exp",
     [
-        (lambda: mapped("b", None), "b"),
-        (lambda: mapped("b", ""), "b"),
-        (lambda: mapped("b", "bb"), "b"),
+        (lambda: keyword("b", None), "b"),
+        (lambda: keyword("b", ""), "b"),
+        (lambda: keyword("b", "bb"), "b"),
         (lambda: optional("b"), "b"),
         (lambda: optional("b", "bb"), "b"),
         (lambda: vararg("c"), "c"),
@@ -51,9 +51,9 @@ def test_modifs_str(mod, exp):
 @pytest.mark.parametrize(
     "mod, exp",
     [
-        (lambda: mapped("b", None), "'b'(>)"),
-        (lambda: mapped("b", ""), "'b'(>)"),
-        (lambda: mapped("b", "bb"), "'b'(>'bb')"),
+        (lambda: keyword("b", None), "'b'(>)"),
+        (lambda: keyword("b", ""), "'b'(>)"),
+        (lambda: keyword("b", "bb"), "'b'(>'bb')"),
         (lambda: optional("b"), "'b'(?)"),
         (lambda: optional("b", "bb"), "'b'(?>'bb')"),
         (lambda: vararg("c"), "'c'(*)"),
@@ -81,9 +81,9 @@ def test_modifs_repr(mod, exp, ser_method):
 @pytest.mark.parametrize(
     "mod, exp",
     [
-        (mapped("b", None), "mapped('b')"),
-        (mapped("b", ""), "mapped('b')"),
-        (mapped("b", "bb"), "mapped('b', 'bb')"),
+        (keyword("b", None), "keyword('b')"),
+        (keyword("b", ""), "keyword('b')"),
+        (keyword("b", "bb"), "keyword('b', 'bb')"),
         (optional("b"), "optional('b')"),
         (optional("b", "bb"), "optional('b', 'bb')"),
         (vararg("c"), "vararg('c')"),
@@ -110,14 +110,14 @@ def test_modifs_cmd(mod, exp, ser_method):
 
 def test_recreation():
     assert optional(optional("a")) == optional("a")
-    assert mapped(mapped("a", 1), 1) == mapped("a", 1)
+    assert keyword(keyword("a", 1), 1) == keyword("a", 1)
     assert vararg(vararg("a")) == vararg("a")
     assert varargs(varargs("a")) == varargs("a")
 
 
 def test_recreation_repr():
     assert repr(optional(optional("a"))) == repr(optional("a"))
-    assert repr(mapped(mapped("a", 1), 1)) == repr(mapped("a", 1))
+    assert repr(keyword(keyword("a", 1), 1)) == repr(keyword("a", 1))
     assert repr(vararg(vararg("a"))) == repr(vararg("a"))
     assert repr(varargs(varargs("a"))) == repr(varargs("a"))
 
@@ -141,9 +141,9 @@ def test_sideffected_bad(call, exp):
     "mod, exp",
     [
         ("b", "'p.b'"),
-        (mapped("b", None), "'p.b'(>'b')"),
-        (mapped("b", ""), "'p.b'(>'b')"),
-        (mapped("b", "bb"), "'p.b'(>'bb')"),
+        (keyword("b", None), "'p.b'(>'b')"),
+        (keyword("b", ""), "'p.b'(>'b')"),
+        (keyword("b", "bb"), "'p.b'(>'bb')"),
         (optional("b"), "'p.b'(?>'b')"),
         (optional("b", "bb"), "'p.b'(?>'bb')"),
         (vararg("c"), "'p.c'(*)"),
@@ -172,7 +172,7 @@ def test_modifs_rename_fn(mod, exp):
     "mod, exp",
     [
         (lambda: "s", "'D'"),
-        (lambda: mapped("b", "bb"), "'D'(>'bb')"),
+        (lambda: keyword("b", "bb"), "'D'(>'bb')"),
         (lambda: optional("b"), "'D'(?>'b')"),
         (lambda: optional("b", "bb"), "'D'(?>'bb')"),
         (lambda: vararg("c"), "'D'(*)"),