FEAT(plot): offer with_XXX() methods on Plotter/Style

+ doc: dogfood in instructions & sample op in changes.

Author: ankostis

.vscode/cspell.json

@@ -53,6 +53,7 @@
         "doctesting",
         "doctests",
         "dogfood",
+        "dogfoods",
         "dynaimage",
         "errgraph",
         "exemethod",

CHANGES.rst

@@ -28,12 +28,12 @@ v6.0.0 (13 Apr 2020, @ankostis): New Plotting Device...
       :hide:
 
       >>> from graphtik import compose, operation, varargs
-      >>> from graphtik import plot
+      >>> from graphtik.plot import get_installed_plotter
       >>> netop = compose('', operation(print, name='print-something', needs=varargs("any"), provides="str")())
       >>> netop.net.graph.graph['label'] = None
       >>> dot = netop.plot(
-      ...        plotter=plot.Plotter(style=plot.Style(kw_legend=None)),
-      ...        name=None
+      ...     name=None,
+      ...     plotter=get_installed_plotter().with_styles(kw_legend=None),
       ... )
 
   + ENH: Convey graph, node & edge ("non-private") attributes from the *networkx* graph

docs/source/conf.py

@@ -105,10 +105,11 @@
 graphtik_save_dot_files = True
 
 # Plot graphtik SVGs with links to docs.
-#
-plotter = plot.get_installed_plotter().copy()
-plotter.style.py_item_url_format = "../reference.html#%(dot_path)s"
-plot.set_installed_plotter(plotter)
+plot.set_installed_plotter(
+    plot.get_installed_plotter().with_styles(
+        py_item_url_format="../reference.html#%(dot_path)s"
+    )
+)
 
 github_slug = "pygraphkit/graphtik"
 try:

docs/source/plotting.rst

@@ -329,21 +329,25 @@ Plot customizations
 
          get_installed_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.
+      - 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` (or :meth:`clone <.Plotter.copy>` the default plotter)
-      to customize its styles, and make it the new *installed plotter*,
-      affecting all calls in :class:`context <contextvars.ContextVar>`.
+   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*.
 
-      If customizing style constants is not enough, you may subclass :class:`.Plotter`
-      and install it.
+      - This will affect all calls in :class:`context <contextvars.ContextVar>`.
+      - If customizing style constants is not enough, you may subclass :class:`.Plotter`
+        and install it.
 
-   3. Do as above (new *plotter*), but pass the customized plotter when calling
-      :meth:`.Plottable.plot()`.
+   3. Take any *plotter*, customize its clone, and then call :meth:`.Plottable.plot()`,
+      with something like that::
 
-   This project does (2) in its own :file:`docs/source/conf.py` sphinx file.
+         netop.plot(plotter=get_installed_plotter().with_styles(kw_legend=None))
+
+
+   This project dogfoods (2) in its own :file:`docs/source/conf.py` sphinx file.
    In particular, it configures the base-url of operation node links
    (by default, nodes do not link to any url).
 

graphtik/plot.py

@@ -472,12 +472,21 @@ class Style:
         "target": "_top",
     }
 
-    def __init__(self, **kw):
+    def __init__(self, _prototype: "Style" = None, **kw):
         """
         Deep-copy class-attributes (to avoid sideffects) and apply user-overrides,
 
         retargeting any :class:`Ref` on my self (from class's 'values).
+
+        :param _prototype:
+            If given, class-attributes are ignored, deep-copying "public" properties
+            only from this instance (and apply on top any `kw`).
         """
+        if _prototype is None:
+            _prototype = type(self)
+        else:
+            assert isinstance(_prototype, Style), _prototype
+
         values = {
             k: v
             for k, v in vars(type(self)).items()
@@ -515,6 +524,10 @@ def remap_item(path, k, v):
             values = vars(self)
         vars(self).update(remap(values, remap_item))
 
+    def with_set(self, **kw) -> "Style":
+        """Returns a deep-clone modified by `kw`."""
+        return type(self)(_prototype=self, **kw)
+
 
 class Plotter:
     """
@@ -526,14 +539,16 @@ class Plotter:
         controlling theming values & dictionaries for plots.
     """
 
-    def __init__(self, style=None):
-        self.style = style or Style()
+    def __init__(self, style: Style = None):
+        self.style: Style = style or Style()
 
-    def copy(self) -> "Plotter":
-        """deep copy of all styles"""
-        clone = type(self)(self.style)
-        clone.__dict__ = remap(vars(self), lambda *a: True)
-        return clone
+    def with_styles(self, **kw) -> "Plotter":
+        """
+        Returns a cloned plotter with deep-coped styles modified as given.
+
+        See also :meth:`Style.with_set()`.
+        """
+        return type(self)(self.style.with_set(**kw))
 
     def plot(self, plot_args: PlotArgs):
         dot = self.build_pydot(plot_args)