REFACT(PLOT.jupyter): consolidate 3 plot-args into a dicvt

ankostis · ankostis · commit 5084c6dafc69 · 2019-11-23T23:42:18.000+02:00
+ redorder plot module.
diff --git a/docs/source/plotting.rst b/docs/source/plotting.rst
@@ -58,8 +58,9 @@ If you want the bare-bone diagram, plot network::
 
    You may increase the height of the SVG cell output with something like this::
 
-        graphop.plot(svg_element_styles="height: 600px; width: 100%")
+        graphop.plot(jupyter_render={"svg_element_styles": "height: 600px; width: 100%"})
 
+   Check :data:`.default_jupyter_render` for defaults.
 
 
 .. _debugging:
diff --git a/graphtik/base.py b/graphtik/base.py
@@ -4,15 +4,11 @@
 
 import abc
 import logging
-
+from typing import Mapping, Union
 
 log = logging.getLogger(__name__)
 
 
-def ifnone(item, default):
-    return default if item is None else item
-
-
 def aslist(i, argname, allowed_types=list):
     """Utility to accept singular strings as lists, and None --> []."""
     if not i:
@@ -132,6 +128,7 @@ def jetsam(ex, locs, *salvage_vars: str, annotation="jetsam", **salvage_mappings
     raise  # noqa #re-raise without ex-arg, not to insert my frame
 
 
+## Defined here, to avoid subclasses importig `plot` module.
 class Plotter(abc.ABC):
     """
     Classes wishing to plot their graphs should inherit this and ...
@@ -146,9 +143,7 @@ def plot(
         self,
         filename=None,
         show=False,
-        svg_pan_zoom_json=None,
-        svg_element_styles=None,
-        svg_container_styles=None,
+        jupyter_render: Union[None, Mapping, str] = None,
         **kws,
     ):
         """
@@ -180,16 +175,11 @@ def plot(
             an optional nested dict of Grapvhiz attributes for certain edges
         :param clusters:
             an optional mapping of nodes --> cluster-names, to group them
-        :param svg_pan_zoom_json:
-            arguments controlling the rendering of a zoomable SVG in
-            Jupyter notebooks, as defined in https://github.com/ariutta/svg-pan-zoom#how-to-use
-            Defaults apply if `None`; read about the defaults in :func:`.render_pydot()`.
-        :param svg_element_styles:
-            mostly for sizing the zoomable SVG in Jupyter notebooks.
-            Defaults apply if `None`; read about the defaults in :func:`.render_pydot()`, and
-            inspect & experiment on the html page of the notebook with browser tools.
-        :param svg_container_styles:
-            like `svg_element_styles`
+        :param jupyter_render:
+            a nested dictionary controlling the rendering of graph-plots in Jupyter cells,
+            if `None`, defaults to :data:`jupyter_render` (you may modify it in place
+            and apply for all future calls).
+
         :return:
             a `pydot.Dot <https://pypi.org/project/pydot/>`_ instance
 
@@ -202,6 +192,8 @@ def plot(
 
                     graphop.plot(svg_element_styles="height: 600px; width: 100%")
 
+                Check :data:`.default_jupyter_render` for defaults.
+
         Note that the `graph` argument is absent - Each Plotter provides
         its own graph internally;  use directly :func:`.render_pydot()` to provide
         a different graph.
@@ -279,12 +271,7 @@ def plot(
 
         dot = self._build_pydot(**kws)
         return render_pydot(
-            dot,
-            filename=filename,
-            show=show,
-            svg_pan_zoom_json=svg_pan_zoom_json,
-            svg_element_styles=svg_element_styles,
-            svg_container_styles=svg_container_styles,
+            dot, filename=filename, show=show, jupyter_render=jupyter_render
         )
 
     @abc.abstractmethod
diff --git a/graphtik/plot.py b/graphtik/plot.py
@@ -5,13 +5,113 @@
 import io
 import logging
 import os
+from typing import Any, Callable, Mapping, Optional, Tuple, Union
 
 import pydot
 
-from .base import ifnone
-
 log = logging.getLogger(__name__)
 
+#: A nested dictionary controlling the rendering of graph-plots in Jupyter cells,
+#:
+#: as those returned from :meth:`.Plotter.plot()` (currently as SVGs).
+#: Either modify it in place, or pass another one in the respective methods.
+#:
+#: The following keys are supported.
+#:
+#: :param svg_pan_zoom_json:
+#:     arguments controlling the rendering of a zoomable SVG in
+#:     Jupyter notebooks, as defined in https://github.com/ariutta/svg-pan-zoom#how-to-use
+#:     if `None`, defaults to string (also maps supported)::
+#:
+#:             "{controlIconsEnabled: true, zoomScaleSensitivity: 0.4, fit: true}"
+#:
+#: :param svg_element_styles:
+#:     mostly for sizing the zoomable SVG in Jupyter notebooks.
+#:     Inspect & experiment on the html page of the notebook with browser tools.
+#:     if `None`, defaults to string (also maps supported)::
+#:
+#:         "width: 100%; height: 300px;"
+#:
+#: :param svg_container_styles:
+#:     like `svg_element_styles`, if `None`, defaults to empty string (also maps supported).
+default_jupyter_render = {
+    "svg_pan_zoom_json": "{controlIconsEnabled: true, zoomScaleSensitivity: 0.4, fit: true}",
+    "svg_element_styles": "width: 100%; height: 300px;",
+    "svg_container_styles": "",
+}
+
+
+def _parse_jupyter_render(dot) -> Tuple[str, str, str]:
+    import json
+
+    jupy_cfg: Mapping[str, Any] = getattr(dot, "_jupyter_render", None)
+    if jupy_cfg is None:
+        jupy_cfg = default_jupyter_render
+
+    def parse_value(key: str, parser: Callable) -> str:
+        val: Union[Mapping, str] = jupy_cfg.get(key)
+        if not val:
+            val = ""
+        elif not isinstance(val, str):
+            val = parser(val)
+        return val
+
+    def styles_parser(d: Mapping) -> str:
+        return "".join(f"{key}: {val};\n" for key, val in d)
+
+    svg_container_styles = parse_value("svg_container_styles", styles_parser)
+    svg_element_styles = parse_value("svg_element_styles", styles_parser)
+    svg_pan_zoom_json = parse_value("svg_pan_zoom_json", json.dumps)
+
+    return svg_pan_zoom_json, svg_element_styles, svg_container_styles
+
+
+def _dot2svg(dot):
+    """
+    Monkey-patching for ``pydot.Dot._repr_html_()` for rendering in jupyter cells.
+
+    Original ``_repr_svg_()`` trick was suggested in https://github.com/pydot/pydot/issues/220.
+
+    .. Note::
+        Had to use ``_repr_html_()`` and not simply ``_repr_svg_()`` because
+        (due to https://github.com/jupyterlab/jupyterlab/issues/7497)
+
+
+    .. TODO:
+        Render in jupyter cells fullly on client-side without SVG, using lib:
+        https://visjs.github.io/vis-network/docs/network/#importDot
+
+    """
+    pan_zoom_json, element_styles, container_styles = _parse_jupyter_render(dot)
+    svg_txt = dot.create_svg().decode()
+    html = f"""
+        <div class="svg_container">
+            <style>
+                .svg_container {{
+                    {container_styles}
+                }}
+                .svg_container SVG {{
+                    {element_styles}
+                }}
+            </style>
+            <script src="http://ariutta.github.io/svg-pan-zoom/dist/svg-pan-zoom.min.js"></script>
+            <script type="text/javascript">
+                var scriptTag = document.scripts[document.scripts.length - 1];
+                var parentTag = scriptTag.parentNode;
+                svg_el = parentTag.querySelector(".svg_container svg");
+                svgPanZoom(svg_el, {pan_zoom_json});
+            </script>
+            {svg_txt}
+        </</>
+    """
+    return html
+
+
+def _monkey_patch_for_jupyter(pydot):
+    """Ensure Dot instance render in Jupyter notebooks. """
+    if not hasattr(pydot.Dot, "_repr_html_"):
+        pydot.Dot._repr_html_ = _dot2svg
+
 
 def _is_class_value_in_list(lst, cls, value):
     return any(isinstance(i, cls) and i == value for i in lst)
@@ -35,58 +135,6 @@ def _report_unmatched_user_props(user_props, kind):
         log.warning("Unmatched `%s_props`:\n  +--%s", kind, unmatched)
 
 
-def _monkey_patch_for_jupyter(pydot):
-    """
-    Make Dot instance render in Jupyter notebooks.
-
-    .. Note::
-        Had to use ``_repr_html_()`` and not simply ``_repr_svg_()`` because
-        (due to https://github.com/jupyterlab/jupyterlab/issues/7497)
-
-    Old ``_repr_svg_()`` trick was suggested in https://github.com/pydot/pydot/issues/220.
-
-    .. TODO:
-        Render fully client-side with:
-        https://visjs.github.io/vis-network/docs/network/#importDot
-    """
-    import re
-    import textwrap
-
-    if not hasattr(pydot.Dot, "_repr_html_"):
-
-        def make_svg(self):
-            ## Discard everything above and including `<svg>` element.
-            svg_txt = self.create_svg().decode()
-            m = re.search("<svg[^>]+>", svg_txt)
-            svg_txt = svg_txt[m.end() :]
-
-            html = f"""
-                <div class="svg_container">
-                    <style>
-                        .svg_container {{
-                            {self._svg_container_styles}
-                        }}
-                        .svg_container SVG {{
-                            {self._svg_element_styles}
-                        }}
-                    </style>
-                    <script src="http://ariutta.github.io/svg-pan-zoom/dist/svg-pan-zoom.min.js"></script>
-                    <script type="text/javascript">
-                        var scriptTag = document.scripts[document.scripts.length - 1];
-                        var parentTag = scriptTag.parentNode;
-                        svg_el = parentTag.querySelector(".svg_container svg");
-                        svgPanZoom(svg_el, {self._svg_pan_zoom_json});
-                    </script>
-                    <svg>
-                        {svg_txt}
-                </div>
-            """
-            return html
-
-        # monkey patch class
-        pydot.Dot._repr_html_ = make_svg
-
-
 def build_pydot(
     graph,
     steps=None,
@@ -258,14 +306,7 @@ def supported_plot_formats():
     return [".%s" % f for f in pydot.Dot().formats]
 
 
-def render_pydot(
-    dot,
-    filename=None,
-    show=False,
-    svg_pan_zoom_json: str = None,
-    svg_element_styles: str = None,
-    svg_container_styles: str = None,
-):
+def render_pydot(dot, filename=None, show=False, jupyter_render: str = None):
     """
     Plot a *Graphviz* dot in a matplotlib, in file or return it for Jupyter.
 
@@ -278,22 +319,10 @@ def render_pydot(
     :param show:
         If it evaluates to true, opens the  diagram in a  matplotlib window.
         If it equals `-1`, it returns the image but does not open the Window.
-    :param svg_pan_zoom_json:
-        arguments controlling the rendering of a zoomable SVG in
-        Jupyter notebooks, as defined in https://github.com/ariutta/svg-pan-zoom#how-to-use
-        if `None`, defaults to string::
-
-                {controlIconsEnabled: true, zoomScaleSensitivity: 0.4, fit: true}",
-
-    :param svg_element_styles:
-        mostly for sizing the zoomable SVG in Jupyter notebooks.
-        Inspect & experiment on the html page of the notebook with browser tools.
-        if `None`, defaults to string::
-
-            width: 100%; height: 300px;
-
-    :param svg_container_styles:
-        like `svg_element_styles`, if `None`, defaults to empty string.
+    :param jupyter_render:
+        a nested dictionary controlling the rendering of graph-plots in Jupyter cells.
+        If `None`, defaults to :data:`default_jupyter_render`
+        (you may modify those in place and they will apply for all future calls).
 
     :return:
         the matplotlib image if ``show=-1``, or the `dot`.
@@ -329,25 +358,13 @@ def render_pydot(
 
         return img
 
-    ## Set properties for rendering in Jupyter as zoomable SVG
-    #
-    dot._svg_pan_zoom_json = ifnone(
-        svg_pan_zoom_json,
-        "{controlIconsEnabled: true, zoomScaleSensitivity: 0.4, fit: true}",
-    )
-    dot._svg_element_styles = ifnone(svg_element_styles, "width: 100%; height: 300px;")
-    dot._svg_container_styles = ifnone(svg_container_styles, "")
+    ## Propagate any properties for rendering in Jupyter cells.
+    dot._jupyter_render = jupyter_render
 
     return dot
 
 
-def legend(
-    filename=None,
-    show=None,
-    svg_pan_zoom_json: str = None,
-    svg_element_styles: str = None,
-    svg_container_styles: str = None,
-):
+def legend(filename=None, show=None, jupyter_render: Optional[Mapping] = None):
     """Generate a legend for all plots (see :meth:`.Plotter.plot()` for args)"""
     import pydot
 
