REFACT(plot): rename installed_plotter --> active_plotter

Author: ankostis

CHANGES.rst

@@ -21,19 +21,19 @@ v6.0.0 (13 Apr 2020, @ankostis): New Plotting Device...
 + ENH/REFACT(PLOT):
 
   + REFACT/BREAK: plots are now fully configurable with :term:`plot styles`
-    through the use of :term:`installed plotter`.
+    through the use of :term:`installed plotter <active plotter>`.
   + ENH: Render operation nodes with Graphviz *HTML-Table Labels*.
 
     .. graphtik::
       :hide:
 
       >>> from graphtik import compose, operation, varargs
-      >>> from graphtik.plot import get_installed_plotter
+      >>> from graphtik.plot import get_active_plotter
       >>> netop = compose('', operation(print, name='print-something', needs=varargs("any"), provides="str")())
       >>> netop.net.graph.graph['label'] = None
       >>> dot = netop.plot(
       ...     name=None,
-      ...     plotter=get_installed_plotter().with_styles(kw_legend=None),
+      ...     plotter=get_active_plotter().with_styles(kw_legend=None),
       ... )
 
   + ENH: Convey graph, node & edge ("non-private") attributes from the *networkx* graph

docs/source/arch.rst

@@ -357,27 +357,27 @@ Architecture
 
     plotter
         A :class:`.Plotter` is responsible for rendering `plottable`\s as images.
-        It is the `installed plotter` that does that, unless overridden in a
+        It is the `active plotter` that does that, unless overridden in a
         :meth:`.Plottable.plot()` call.
         Plotters can be customized by :ref:`various means <plot-customizations>`,
         such `plot styles`.
 
-    installed plotter
-    default installed plotter
+    active plotter
+    default active plotter
         The `plotter` currently installed "in-context" of the respective `graphtik
         configuration` - this term implies also any :ref:`plot-customizations`
-        done on the installed plotter (such as `plot styles`).
+        done on the active plotter (such as `plot styles`).
 
-        Installation happens by calling one of :func:`.installed_plotter_plugged()` or
-        :func:`.set_installed_plotter` functions.
+        Installation happens by calling one of :func:`.active_plotter_plugged()` or
+        :func:`.set_active_plotter` functions.
 
-        The **default** *installed plotter* is the plotter instance that this project
+        The **default** *active plotter* is the plotter instance that this project
         comes pre-configured with, ie, when no *plot-customizations* have yet happened.
 
     plot styles
         The attributes of :class:`.plot.Style` class.
         The actual styles in-use are those in the :attr:`.Plotter.style` attribute
-        of the `installed plotter`.
+        of the `active plotter`.
 
 
 .. default-role:: obj

docs/source/conf.py

@@ -105,8 +105,8 @@
 graphtik_save_dot_files = True
 
 # Plot graphtik SVGs with links to docs.
-plot.set_installed_plotter(
-    plot.get_installed_plotter().with_styles(
+plot.set_active_plotter(
+    plot.get_active_plotter().with_styles(
         py_item_url_format="../reference.html#%(dot_path)s"
     )
 )

docs/source/plotting.rst

@@ -324,18 +324,18 @@ Plot customizations
    You may customize the styles and/or *plotter* behavior with various methods,
    ordered by breadth of the effects (most broadly effecting method at the top):
 
-   1. Get and modify in-place the styles of the :term:`default installed plotter`,
+   1. Get and modify in-place the styles of the :term:`default active plotter`,
       like that::
 
-         get_installed_plotter().style.kw_op["fillcolor"] = "purple"
+         get_active_plotter().style.kw_op["fillcolor"] = "purple"
 
       - This will affect all :meth:`.Plottable.plot()` calls for a python session.
       - You cannot change the *plotter* instance with this method - only styles
         (and monkeypatching plotter's methods).
 
    2. Create a new :class:`.Plotter` with customized :attr:`.Plotter.style`, or
       clone and customize the styles of an existing plotter by the use of
-      its :meth:`.Plotter.with_styles` method, and make that the new *installed plotter*.
+      its :meth:`.Plotter.with_styles` method, and make that the new *active plotter*.
 
       - This will affect all calls in :class:`context <contextvars.ContextVar>`.
       - If customizing style constants is not enough, you may subclass :class:`.Plotter`
@@ -344,7 +344,7 @@ Plot customizations
    3. Take any *plotter*, customize its clone, and then call :meth:`.Plottable.plot()`,
       with something like that::
 
-         netop.plot(plotter=get_installed_plotter().with_styles(kw_legend=None))
+         netop.plot(plotter=get_active_plotter().with_styles(kw_legend=None))
 
 
    This project dogfoods (2) in its own :file:`docs/source/conf.py` sphinx file.

graphtik/__init__.py

@@ -39,8 +39,8 @@
     tasks_marshalled,
 )
 
-## SEE ALSO: `.plot.installed_plotter_plugged()`, `.plot.set_installed_plotter()` &
-#  `.plot.get_installed_plotter()` configs, not imported, unless plot is needed..
+## SEE ALSO: `.plot.active_plotter_plugged()`, `.plot.set_active_plotter()` &
+#  `.plot.get_active_plotter()` configs, not imported, unless plot is needed..
 
 from .modifiers import *  # noqa, on purpose to include any new modifiers
 from .netop import compose

graphtik/base.py

@@ -441,15 +441,15 @@ def plot(
             If it evaluates to true, opens the  diagram in a  matplotlib window.
             If it equals `-1`, it plots but does not open the Window.
         :param plotter:
-            an instance to handle plotting; if none, the :term:`installed plotter`
+            an instance to handle plotting; if none, the :term:`active plotter`
             is used by default.
         :param name:
             if not given, dot-lang graph would is named "G"; necessary to be unique
             when referring to generated CMAPs.
             No need to quote it, handled by the plotter, downstream.
         :param str graph:
             (optional) A :class:`nx.Digraph` with overrides to merge with the graph provided
-            by underlying plottables (translated by the :term:`installed plotter`).
+            by underlying plottables (translated by the :term:`active plotter`).
 
             It may contain "public" or "private *graph*, *node* & *edge* attributes:
 
@@ -576,11 +576,11 @@ def plot(
         del kw["self"]
         plot_args = PlotArgs(**kw)
 
-        from .plot import Plotter, get_installed_plotter
+        from .plot import Plotter, get_active_plotter
 
         if plotter and not isinstance(plotter, Plotter):
             raise ValueError(f"Invalid `plotter` argument given: {plotter}")
-        plot_args = plot_args._replace(plotter=plotter or get_installed_plotter())
+        plot_args = plot_args._replace(plotter=plotter or get_active_plotter())
 
         plot_args = self.prepare_plot_args(plot_args)
         assert plot_args.graph, plot_args

graphtik/config.py

@@ -1,6 +1,14 @@
 # Copyright 2016, Yahoo Inc.
 # Licensed under the terms of the Apache License, Version 2.0. See the LICENSE file associated with the project for terms.
-""":term:`configurations` for network execution, and utilities on them."""
+"""
+:term:`configurations` for network execution, and utilities on them.
+
+.. seealso:: methods :func:`.plot.active_plotter_plugged()`, :func:`.plot.set_active_plotter()`,
+    :func:`.plot.get_active_plotter()`
+
+    Plot configrations were not defined here, not to pollute import space early,
+    until they are actually needed.
+"""
 import ctypes
 from contextlib import contextmanager
 from contextvars import ContextVar
@@ -47,7 +55,9 @@ def _tristate_armed(context_var: ContextVar, enabled):
 
 
 debug = partial(_tristate_armed, _debug)
-"""Like :func:`set_debug()` as a context-manager to reset old value. """
+"""
+Like :func:`set_debug()` as a context-manager, resetting back to old value.
+"""
 is_debug = partial(_getter, _debug)
 """see :func:`set_debug()`"""
 set_debug = partial(_tristate_set, _debug)
@@ -84,7 +94,9 @@ def is_abort():
 
 
 evictions_skipped = partial(_tristate_armed, _skip_evictions)
-"""Like :func:`set_skip_evictions()` as a context-manager to reset old value. """
+"""
+Like :func:`set_skip_evictions()` as a context-manager, resetting back to old value.
+"""
 is_skip_evictions = partial(_getter, _skip_evictions)
 """see :func:`set_skip_evictions()`"""
 set_skip_evictions = partial(_tristate_set, _skip_evictions)
@@ -100,7 +112,9 @@ def is_abort():
 
 @contextmanager
 def execution_pool_plugged(pool: "Optional[Pool]"):
-    """Like :func:`set_execution_pool()` as a context-manager to reset old value. """
+    """
+    Like :func:`set_execution_pool()` as a context-manager, resetting back to old value.
+    """
     resetter = _execution_pool.set(pool)
     try:
         yield
@@ -124,7 +138,9 @@ def get_execution_pool() -> "Optional[Pool]":
 
 
 tasks_in_parallel = partial(_tristate_armed, _parallel_tasks)
-"""Like :func:`set_parallel_tasks()` as a context-manager to reset old value. """
+"""
+Like :func:`set_parallel_tasks()` as a context-manager, resetting back to old value.
+"""
 is_parallel_tasks = partial(_getter, _parallel_tasks)
 """see :func:`set_parallel_tasks()`"""
 set_parallel_tasks = partial(_tristate_set, _parallel_tasks)
@@ -141,7 +157,9 @@ def get_execution_pool() -> "Optional[Pool]":
 
 
 tasks_marshalled = partial(_tristate_armed, _marshal_tasks)
-"""Like :func:`set_marshal_tasks()` as a context-manager to reset old value. """
+"""
+Like :func:`set_marshal_tasks()` as a context-manager, resetting back to old value.
+"""
 is_marshal_tasks = partial(_getter, _marshal_tasks)
 """see :func:`set_marshal_tasks()`"""
 set_marshal_tasks = partial(_tristate_set, _marshal_tasks)
@@ -160,7 +178,9 @@ def get_execution_pool() -> "Optional[Pool]":
 
 
 operations_endured = partial(_tristate_armed, _endure_operations)
-"""Like :func:`set_endure_operations()` as a context-manager to reset old value. """
+"""
+Like :func:`set_endure_operations()` as a context-manager, resetting back to old value.
+"""
 is_endure_operations = partial(_getter, _endure_operations)
 """see :func:`set_endure_operations()`"""
 set_endure_operations = partial(_tristate_set, _endure_operations)
@@ -178,7 +198,9 @@ def get_execution_pool() -> "Optional[Pool]":
 
 
 operations_reschedullled = partial(_tristate_armed, _reschedule_operations)
-"""Like :func:`set_reschedule_operations()` as a context-manager to reset old value. """
+"""
+Like :func:`set_reschedule_operations()` as a context-manager, resetting back to old value.
+"""
 is_reschedule_operations = partial(_getter, _reschedule_operations)
 """see :func:`set_reschedule_operations()`"""
 set_reschedule_operations = partial(_tristate_set, _reschedule_operations)

graphtik/plot.py

@@ -1,7 +1,7 @@
 # Copyright 2016, Yahoo Inc.
 # Licensed under the terms of the Apache License, Version 2.0. See the LICENSE file associated with the project for terms.
 """
-Plotting of graphtik graphs (see also plot-classes on :mod:`.base` module).
+Plotting of graph graphs handled by :term:`active plotter`.
 
 Separate from `graphtik.base` to avoid too many imports too early.
 from contextlib import contextmanager
@@ -320,7 +320,7 @@ class Style:
 
     .. NOTE::
         Changing class attributes AFTER the module has loaded WON'T change themes;
-        Either patch directly the :attr:`Plotter.style` of :term:`installed plotter`),
+        Either patch directly the :attr:`Plotter.style` of :term:`active plotter`),
         or pass a new styles to a new plotter, as described in :ref:`plot-customizations`.
 
     """
@@ -500,7 +500,7 @@ def resolve_refs(self, values: dict = None) -> None:
         Rebase any refs in styles, and deep copy (for free) as instance attributes.
 
         :raises:
-            Nothing(!), not to CRASH :term:`default installed plotter` on import-time.
+            Nothing(!), not to CRASH :term:`default active plotter` on import-time.
             Ref-errors are log-ERROR reported, and the item with the ref is skipped.
         """
 
@@ -1030,11 +1030,11 @@ def legend(
     Generate a legend for all plots (see :meth:`.Plottable.plot()` for args)
 
     :param plotter:
-        override the :term:`installed plotter`
+        override the :term:`active plotter`
 
     See :meth:`Plotter.render_pydot` for the rest arguments.
     """
-    plotter = plotter or get_installed_plotter()
+    plotter = plotter or get_active_plotter()
     return plotter.legend(filename, show, jupyter_render)
 
 
@@ -1043,24 +1043,24 @@ def supported_plot_formats() -> List[str]:
     return [".%s" % f for f in pydot.Dot().formats]
 
 
-_installed_plotter: ContextVar[Plotter] = ContextVar(
-    "installed_plotter", default=Plotter()
-)
+_active_plotter: ContextVar[Plotter] = ContextVar("active_plotter", default=Plotter())
 
 
 @contextmanager
-def installed_plotter_plugged(plotter: Plotter) -> None:
-    """Like :func:`set_installed_plotter()` as a context-manager to reset old value. """
+def active_plotter_plugged(plotter: Plotter) -> None:
+    """
+    Like :func:`set_active_plotter()` as a context-manager, resetting back to old value.
+    """
     if not isinstance(plotter, Plotter):
         raise ValueError(f"Cannot install invalid plotter: {plotter}")
-    resetter = _installed_plotter.set(plotter)
+    resetter = _active_plotter.set(plotter)
     try:
         yield
     finally:
-        _installed_plotter.reset(resetter)
+        _active_plotter.reset(resetter)
 
 
-def set_installed_plotter(plotter: Plotter):
+def set_active_plotter(plotter: Plotter):
     """
     The default instance to render :term:`plottable`\\s,
 
@@ -1071,13 +1071,13 @@ def set_installed_plotter(plotter: Plotter):
     """
     if not isinstance(plotter, Plotter):
         raise ValueError(f"Cannot install invalid plotter: {plotter}")
-    return _installed_plotter.set(plotter)
+    return _active_plotter.set(plotter)
 
 
-def get_installed_plotter() -> Plotter:
-    """Get the previously installed  :class:`.Plotter` instance or default one."""
-    plotter = _installed_plotter.get()
+def get_active_plotter() -> Plotter:
+    """Get the previously active  :class:`.plotter` instance or default one."""
+    plotter = _active_plotter.get()
     if not isinstance(plotter, Plotter):
-        raise ValueError(f"Missing or invalid installed plotter: {plotter}")
+        raise ValueError(f"Missing or invalid active plotter: {plotter}")
 
     return plotter

test/test_plot.py

@@ -16,8 +16,8 @@
 from graphtik.plot import (
     Plotter,
     Style,
-    get_installed_plotter,
-    installed_plotter_plugged,
+    get_active_plotter,
+    active_plotter_plugged,
 )
 
 
@@ -349,9 +349,9 @@ def test_plotter_customizations(pipeline, monkeypatch):
     dot = str(pipeline.plot())
     assert url in dot
 
-    ## New installed_plotter
+    ## New active_plotter
     #
-    with installed_plotter_plugged(Plotter(style=Style(kw_legend={"URL": None}))):
+    with active_plotter_plugged(Plotter(style=Style(kw_legend={"URL": None}))):
         dot = str(pipeline.plot())
         assert url not in dot
 
@@ -365,7 +365,7 @@ def test_plotter_customizations(pipeline, monkeypatch):
     assert url in dot
 
     url2 = "http://example.2.org"
-    with installed_plotter_plugged(Plotter(style=Style(kw_legend={"URL": url2}))):
+    with active_plotter_plugged(Plotter(style=Style(kw_legend={"URL": url2}))):
         dot = str(pipeline.plot())
         assert url2 in dot
         assert url not in dot
@@ -465,7 +465,7 @@ def test_node_dot_str0(dot_str_pipeline):
 
 
 def test_node_dot_str1(dot_str_pipeline, monkeypatch):
-    style = get_installed_plotter().style
+    style = get_active_plotter().style
     monkeypatch.setattr(style, "py_item_url_format", "abc#%s")
     monkeypatch.setattr(style, "op_link_target", "_self")
     monkeypatch.setattr(style, "fn_link_target", "bad")