FIX(#13, plot): PY2 era BUG when writing plot-diagrams; give sample code in the into

.travis.yml

@@ -2,19 +2,26 @@ language: python
 
 python:
   - "2.7"
-  - "3.4"
   - "3.5"
+  - "3.6"
+  - "3.7"
+
+addons:
+  apt:
+    packages:
+      - graphviz
+
 
 install:
   - pip install Sphinx sphinx_rtd_theme codecov packaging
   - "python -c $'import os, packaging.version as version\\nv = version.parse(os.environ.get(\"TRAVIS_TAG\", \"1.0\")).public\\nwith open(\"VERSION\", \"w\") as f: f.write(v)'"
-  - python setup.py install
+  - pip install -e .[test]
   - cd docs
   - make clean html
   - cd ..
 
 script:
-  - python setup.py nosetests --with-coverage --cover-package=graphkit
+  - pytest -v --cov=graphkit
 
 deploy:
   provider: pypi

README.md

@@ -51,6 +51,19 @@ print(out)
 
 As you can see, any function can be used as an operation in GraphKit, even ones imported from system modules!
 
+For debugging, you may plot the workflow with one of these methods:
+
+```python
+   graph.net.plot(show=True)               # open a matplotlib window
+   graph.net.plot("path/to/workflow.png")  # supported files: .png .dot .jpg .jpeg .pdf .svg
+```
+
+> **NOTE**: For plots, `graphviz` must be in your PATH, and `pydot` & `matplotlib` python packages installed.
+> You may install both when installing *graphkit* with its `plot` extras:
+> ```python
+> pip install graphkit[plot]
+> ```
+
 # License
 
 Code licensed under the Apache License, Version 2.0 license. See LICENSE file for terms.

docs/source/index.rst

@@ -69,6 +69,18 @@ Here's a Python script with an example GraphKit computation graph that produces
 
 As you can see, any function can be used as an operation in GraphKit, even ones imported from system modules!
 
+For debugging, you may plot the workflow with one of these methods::
+
+   graph.net.plot(show=True)               # open a matplotlib window
+   graph.net.plot("path/to/workflow.png")  # supported files: .png .dot .jpg .jpeg .pdf .svg
+
+.. NOTE:: 
+  For plots, ``graphviz`` must be in your PATH, and ``pydot` & ``matplotlib`` python packages installed.
+  You may install both when installing *graphkit* with its `plot` extras::
+
+      pip install graphkit[plot]
+
+
 License
 -------
 

graphkit/base.py

@@ -171,8 +171,35 @@ def set_execution_method(self, method):
         assert method in options
         self._execution_method = method
 
-    def plot(self, filename=None, show=False):
-        self.net.plot(filename=filename, show=show)
+    def plot(self, filename=None, show=False, jupyter=None,
+            inputs=None, outputs=None, solution=None):
+        """
+        :param str filename:
+            Write diagram into a file.
+            Common extensions are ``.png .dot .jpg .jpeg .pdf .svg``
+            call :func:`plot.supported_plot_formats()` for more.
+        :param show:
+            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 jupyter:
+            If it evaluates to true, return an SVG suitable to render 
+            in *jupyter notebook cells* (`ipython` must be installed).
+        :param inputs:
+            an optional name list, any nodes in there are plotted
+            as a "house"
+        :param outputs:
+            an optional name list, any nodes in there are plotted
+            as an "inverted-house"
+        :param solution:
+            an optional dict with values to annotate nodes
+            (currently content not shown, but node drawn as "filled")
+
+        :return:
+            An instance of the :mod`pydot` graph
+
+        See :func:`graphkit.plot.plot_graph()` for the plot legend and example code.
+        """
+        return self.net.plot(filename, show, jupyter, inputs, outputs, solution)
 
     def __getstate__(self):
         state = Operation.__getstate__(self)

graphkit/network.py

@@ -2,12 +2,11 @@
 # Licensed under the terms of the Apache License, Version 2.0. See the LICENSE file associated with the project for terms.
 
 import time
-import os
 import networkx as nx
 
-from io import StringIO
 
 from .base import Operation
+from .modifiers import optional
 
 
 class DataPlaceholderNode(str):
@@ -375,77 +374,40 @@ def _compute_sequential_method(self, named_inputs, outputs):
             return {k: cache[k] for k in iter(cache) if k in outputs}
 
 
-    def plot(self, filename=None, show=False):
+    def plot(self, filename=None, show=False, jupyter=None,
+             inputs=None, outputs=None, solution=None):
         """
-        Plot the graph.
+        Plot a *Graphviz* graph and return it, if no other argument provided.
 
-        params:
         :param str filename:
-            Write the output to a png, pdf, or graphviz dot file. The extension
-            controls the output format.
-
-        :param boolean show:
-            If this is set to True, use matplotlib to show the graph diagram
-            (Default: False)
-
-        :returns:
-            An instance of the pydot graph
-
+            Write diagram into a file.
+            Common extensions are ``.png .dot .jpg .jpeg .pdf .svg``
+            call :func:`plot.supported_plot_formats()` for more.
+        :param show:
+            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 jupyter:
+            If it evaluates to true, return an SVG suitable to render 
+            in *jupyter notebook cells* (`ipython` must be installed).
+        :param inputs:
+            an optional name list, any nodes in there are plotted
+            as a "house"
+        :param outputs:
+            an optional name list, any nodes in there are plotted
+            as an "inverted-house"
+        :param solution:
+            an optional dict with values to annotate nodes
+            (currently content not shown, but node drawn as "filled")
+
+        :return:
+            An instance of the :mod`pydot` graph
+
+        See :func:`graphkit.plot.plot_graph()` for the plot legend and example code.
         """
-        import pydot
-        import matplotlib.pyplot as plt
-        import matplotlib.image as mpimg
-
-        assert self.graph is not None
-
-        def get_node_name(a):
-            if isinstance(a, DataPlaceholderNode):
-                return a
-            return a.name
-
-        g = pydot.Dot(graph_type="digraph")
-
-        # draw nodes
-        for nx_node in self.graph.nodes():
-            if isinstance(nx_node, DataPlaceholderNode):
-                node = pydot.Node(name=nx_node, shape="rect")
-            else:
-                node = pydot.Node(name=nx_node.name, shape="circle")
-            g.add_node(node)
-
-        # draw edges
-        for src, dst in self.graph.edges():
-            src_name = get_node_name(src)
-            dst_name = get_node_name(dst)
-            edge = pydot.Edge(src=src_name, dst=dst_name)
-            g.add_edge(edge)
-
-        # save plot
-        if filename:
-            basename, ext = os.path.splitext(filename)
-            with open(filename, "w") as fh:
-                if ext.lower() == ".png":
-                    fh.write(g.create_png())
-                elif ext.lower() == ".dot":
-                    fh.write(g.to_string())
-                elif ext.lower() in [".jpg", ".jpeg"]:
-                    fh.write(g.create_jpeg())
-                elif ext.lower() == ".pdf":
-                    fh.write(g.create_pdf())
-                elif ext.lower() == ".svg":
-                    fh.write(g.create_svg())
-                else:
-                    raise Exception("Unknown file format for saving graph: %s" % ext)
-
-        # display graph via matplotlib
-        if show:
-            png = g.create_png()
-            sio = StringIO(png)
-            img = mpimg.imread(sio)
-            plt.imshow(img, aspect="equal")
-            plt.show()
-
-        return g
+        from . import plot
+
+        return plot.plot_graph(self.graph, filename, show, jupyter,
+                          self.steps, inputs, outputs, solution)
 
 
 def ready_to_schedule_operation(op, has_executed, graph):
@@ -494,3 +456,10 @@ def get_data_node(name, graph):
         if node == name and isinstance(node, DataPlaceholderNode):
             return node
     return None
+
+
+def supported_plot_formats():
+    """return automatically all `pydot` extensions withlike ``.png``"""
+    import pydot
+
+    return [".%s" % f for f in pydot.Dot().formats]