feat: Generate StateMachine diagram from cmd line (#311)

Author: fgmacedo

docs/diagram.md

@@ -29,7 +29,7 @@ Graphviz. For example, on Debian-based systems (such as Ubuntu), you can use the
 
 ```
 
-## How to generate a diagram
+## How to generate a diagram at runtime
 
 
 ```py
@@ -81,6 +81,37 @@ The current state is also highlighted:
 ![OrderControl](images/order_control_machine_processing.png)
 
 
+## Generate from the command line
+
+You can also generate a diagram from the command line using the `statemachine.contrib.diagram` as a module.
+
+```bash
+❯ python -m statemachine.contrib.diagram --help
+usage: diagram.py [OPTION] <classpath> <out>
+
+Generate diagrams for StateMachine classes.
+
+positional arguments:
+  classpath   A fully-qualified dotted path to the StateMachine class.
+  out         File to generate the image using extension as the output format.
+
+optional arguments:
+  -h, --help  show this help message and exit
+```
+
+Example:
+
+```bash
+python -m statemachine.contrib.diagram tests.examples.traffic_light_machine.TrafficLightMachine m.png
+```
+
+```{note}
+Supported formats include: `dia`, `dot`, `fig`, `gif`, `jpg`, `pdf`, `png`, `ps`, `svg` and many others.
+Please see [pydot](https://github.com/pydot/pydot) and [Graphviz](https://graphviz.org/) for a
+complete list.
+```
+
+
 ## JupyterLab / Jupyter integration
 
 Machines instances are automatically displayed as a diagram when used on JupyterLab cells:

statemachine/contrib/diagram.py

@@ -1,5 +1,9 @@
+import sys
 import pydot
-from statemachine.factory import StateMachineMetaclass
+import importlib
+
+from ..factory import StateMachineMetaclass
+from ..statemachine import BaseStateMachine
 
 
 class DotGraphMachine(object):
@@ -25,7 +29,9 @@ def __init__(self, machine):
 
     def _get_graph(self):
         machine = self.machine
-        sm_class = machine if isinstance(machine, StateMachineMetaclass) else machine.__class__
+        sm_class = (
+            machine if isinstance(machine, StateMachineMetaclass) else machine.__class__
+        )
         return pydot.Dot(
             "list",
             graph_type="digraph",
@@ -95,17 +101,11 @@ def _state_as_node(self, state):
         return node
 
     def _transition_as_edge(self, transition):
-
         def _get_condition_repr(cond):
             name = getattr(cond.func, "__name__", cond.func)
             return name if cond.expected_value else "!{}".format(name)
 
-        cond = ", ".join(
-            [
-                _get_condition_repr(cond)
-                for cond in transition.cond
-            ]
-        )
+        cond = ", ".join([_get_condition_repr(cond) for cond in transition.cond])
         if cond:
             cond = "\n[{}]".format(cond)
         return pydot.Edge(
@@ -133,3 +133,52 @@ def get_graph(self):
 
     def __call__(self):
         return self.get_graph()
+
+
+def import_sm(qualname):
+    module_name, class_name = qualname.rsplit(".", 1)
+    module = importlib.import_module(module_name)
+    smclass = getattr(module, class_name, None)
+    if not smclass or not issubclass(smclass, BaseStateMachine):
+        raise ValueError("{} is not a subclass of StateMachine".format(class_name))
+
+    return smclass
+
+
+def write_image(qualname, out):
+    """
+    Given a `qualname`, that is the fully qualified dotted path to a StateMachine
+    classe, imports the class and generates a dot graph using the `pydot` lib.
+    Writes the graph representation to the filename 'out' that will
+    open/create and truncate such file and write on it a representation of
+    the graph defined by the statemachine, in the format specified by
+    the extension contained in the out path (out.ext).
+    """
+    smclass = import_sm(qualname)
+
+    graph = DotGraphMachine(smclass).get_graph()
+    out_extension = out.rsplit(".", 1)[1]
+    graph.write(out, format=out_extension)
+
+
+def main(argv=None):
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        usage="%(prog)s [OPTION] <classpath> <out>",
+        description="Generate diagrams for StateMachine classes.",
+    )
+    parser.add_argument(
+        "classpath", help="A fully-qualified dotted path to the StateMachine class."
+    )
+    parser.add_argument(
+        "out",
+        help="File to generate the image using extension as the output format.",
+    )
+
+    args = parser.parse_args(argv)
+    write_image(qualname=args.classpath, out=args.out)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

tests/test_contrib_diagram.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from statemachine.contrib.diagram import DotGraphMachine
+from statemachine.contrib.diagram import DotGraphMachine, main
 
 
 @pytest.fixture(params=[
@@ -37,3 +37,23 @@ def test_machine_dot(OrderControl):
 
     dot_str = dot.to_string()  # or dot.to_string()
     assert dot_str.startswith("digraph list {")
+
+
+class TestDiagramCmdLine:
+
+    def test_generate_image(self, tmp_path):
+        out = tmp_path / 'sm.svg'
+
+        main(["tests.examples.traffic_light_machine.TrafficLightMachine", str(out)])
+
+        assert out.read_text().startswith(
+            '<?xml version="1.0" encoding="UTF-8" standalone="no"?>\n<!DOCTYPE svg'
+        )
+
+    def test_generate_complain_about_bad_sm_path(self, capsys, tmp_path):
+        out = tmp_path / 'sm.svg'
+
+        with pytest.raises(ValueError) as e:
+            main(["tests.examples.traffic_light_machine.TrafficLightMachineXXX", str(out)])
+
+        assert e.match("TrafficLightMachineXXX is not a subclass of StateMachine")