feat: add SVG text format and use formatter in Sphinx directive

- Register "svg" format in Formatter (DOT → SVG decoded as str)
- Refactor Sphinx directive to use formatter.render() for both SVG
  and Mermaid instead of calling DotGraphMachine/MermaidGraphMachine
  directly
- Update _prepare_svg and _resolve_target to work with str (not bytes)

Author: fgmacedo

statemachine/contrib/diagram/formatter.py

@@ -106,6 +106,14 @@ def _render_dot(machine_or_class: "MachineRef") -> str:
     return DotGraphMachine(machine_or_class).get_graph().to_string()  # type: ignore[no-any-return]
 
 
+@formatter.register_format("svg")
+def _render_svg(machine_or_class: "MachineRef") -> str:
+    from statemachine.contrib.diagram import DotGraphMachine
+
+    svg_bytes: bytes = DotGraphMachine(machine_or_class).get_graph().create_svg()  # type: ignore[attr-defined]
+    return svg_bytes.decode("utf-8")
+
+
 @formatter.register_format("mermaid")
 def _render_mermaid(machine_or_class: "MachineRef") -> str:
     from statemachine.contrib.diagram import MermaidGraphMachine

statemachine/contrib/diagram/sphinx_ext.py

@@ -39,7 +39,7 @@ def _parse_events(value: str) -> list[str]:
 
 
 # Match the outer <svg ...>...</svg> element, stripping XML prologue/DOCTYPE.
-_SVG_TAG_RE = re.compile(rb"(<svg\b.*</svg>)", re.DOTALL)
+_SVG_TAG_RE = re.compile(r"(<svg\b.*</svg>)", re.DOTALL)
 
 # Match fixed width/height attributes (e.g. width="702pt" height="170pt").
 _SVG_WIDTH_RE = re.compile(r'\bwidth="([^"]*(?:pt|px))"')
@@ -79,7 +79,7 @@ def run(self) -> list[nodes.Node]:
         qualname = self.arguments[0]
 
         try:
-            from statemachine.contrib.diagram import DotGraphMachine
+            from statemachine.contrib.diagram import formatter
             from statemachine.contrib.diagram import import_sm
 
             sm_class = import_sm(qualname)
@@ -101,11 +101,10 @@ def run(self) -> list[nodes.Node]:
         output_format = self.options.get("format", "").strip().lower()
 
         if output_format == "mermaid":
-            return self._run_mermaid(machine, qualname)
+            return self._run_mermaid(machine, formatter, qualname)
 
         try:
-            graph = DotGraphMachine(machine).get_graph()
-            svg_bytes: bytes = graph.create_svg()  # type: ignore[attr-defined]
+            svg_text = formatter.render(machine, "svg")
         except Exception as exc:
             return [
                 self.state_machine.reporter.warning(
@@ -114,12 +113,12 @@ def run(self) -> list[nodes.Node]:
                 )
             ]
 
-        svg_tag, intrinsic_width, intrinsic_height = self._prepare_svg(svg_bytes)
+        svg_tag, intrinsic_width, intrinsic_height = self._prepare_svg(svg_text)
         svg_styles = self._build_svg_styles(intrinsic_width, intrinsic_height)
         svg_tag = svg_tag.replace("<svg ", f"<svg {svg_styles} ", 1)
 
         alt_text = html_mod.escape(self.options.get("alt", qualname.rsplit(".", 1)[-1]))
-        target = self._resolve_target(svg_bytes)
+        target = self._resolve_target(svg_text)
 
         img_html = f'<div role="img" aria-label="{alt_text}">{svg_tag}</div>'
         if target:
@@ -149,12 +148,10 @@ def run(self) -> list[nodes.Node]:
 
         return [raw_node]
 
-    def _run_mermaid(self, machine: object, qualname: str) -> list[nodes.Node]:
+    def _run_mermaid(self, machine: object, formatter: Any, qualname: str) -> list[nodes.Node]:
         """Render a Mermaid diagram using sphinxcontrib-mermaid's node type."""
         try:
-            from statemachine.contrib.diagram import MermaidGraphMachine
-
-            mermaid_src = MermaidGraphMachine(machine).get_mermaid()
+            mermaid_src = formatter.render(machine, "mermaid")
         except Exception as exc:
             return [
                 self.state_machine.reporter.warning(
@@ -190,10 +187,10 @@ def _run_mermaid(self, machine: object, qualname: str) -> list[nodes.Node]:
             self.add_name(node)
         return [node]
 
-    def _prepare_svg(self, svg_bytes: bytes) -> tuple[str, str, str]:
+    def _prepare_svg(self, svg_text: str) -> tuple[str, str, str]:
         """Extract the ``<svg>`` element and its intrinsic dimensions."""
-        match = _SVG_TAG_RE.search(svg_bytes)
-        svg_tag = match.group(1).decode("utf-8") if match else svg_bytes.decode("utf-8")
+        match = _SVG_TAG_RE.search(svg_text)
+        svg_tag = match.group(1) if match else svg_text
 
         width_match = _SVG_WIDTH_RE.search(svg_tag)
         height_match = _SVG_HEIGHT_RE.search(svg_tag)
@@ -235,7 +232,7 @@ def _build_svg_styles(self, intrinsic_width: str, intrinsic_height: str) -> str:
 
         return f'style="{"; ".join(parts)}"'
 
-    def _resolve_target(self, svg_bytes: bytes) -> str:
+    def _resolve_target(self, svg_text: str) -> str:
         """Return the href for the wrapper ``<a>`` tag, if any.
 
         When ``:target:`` is given without a value (or as empty string), the
@@ -258,8 +255,8 @@ def _resolve_target(self, svg_bytes: bytes) -> str:
         outdir = os.path.join(self.env.app.outdir, "_images")
         os.makedirs(outdir, exist_ok=True)
         outpath = os.path.join(outdir, filename)
-        with open(outpath, "wb") as f:
-            f.write(svg_bytes)
+        with open(outpath, "w", encoding="utf-8") as f:
+            f.write(svg_text)
 
         return f"/_images/{filename}"
 

tests/test_contrib_diagram.py

@@ -889,47 +889,47 @@ def _make_directive(self, options=None):
         return directive
 
     def test_strips_xml_prologue(self):
-        svg_bytes = (
-            b'<?xml version="1.0"?>\n<!DOCTYPE svg>\n'
-            b'<svg width="100pt" height="50pt" viewBox="0 0 100 50">'
-            b"<circle/></svg>"
+        svg_text = (
+            '<?xml version="1.0"?>\n<!DOCTYPE svg>\n'
+            '<svg width="100pt" height="50pt" viewBox="0 0 100 50">'
+            "<circle/></svg>"
         )
         directive = self._make_directive()
-        svg_tag, _, _ = directive._prepare_svg(svg_bytes)
+        svg_tag, _, _ = directive._prepare_svg(svg_text)
 
         assert not svg_tag.startswith("<?xml")
         assert svg_tag.startswith("<svg")
         assert "</svg>" in svg_tag
 
     def test_extracts_intrinsic_dimensions(self):
-        svg_bytes = b'<svg width="702pt" height="170pt"><rect/></svg>'
+        svg_text = '<svg width="702pt" height="170pt"><rect/></svg>'
         directive = self._make_directive()
-        _, w, h = directive._prepare_svg(svg_bytes)
+        _, w, h = directive._prepare_svg(svg_text)
 
         assert w == "702pt"
         assert h == "170pt"
 
     def test_removes_fixed_dimensions(self):
-        svg_bytes = b'<svg width="702pt" height="170pt" viewBox="0 0 702 170"><rect/></svg>'
+        svg_text = '<svg width="702pt" height="170pt" viewBox="0 0 702 170"><rect/></svg>'
         directive = self._make_directive()
-        svg_tag, _, _ = directive._prepare_svg(svg_bytes)
+        svg_tag, _, _ = directive._prepare_svg(svg_text)
 
         assert 'width="702pt"' not in svg_tag
         assert 'height="170pt"' not in svg_tag
         assert "viewBox" in svg_tag
 
     def test_handles_no_dimensions(self):
-        svg_bytes = b'<svg viewBox="0 0 100 50"><rect/></svg>'
+        svg_text = '<svg viewBox="0 0 100 50"><rect/></svg>'
         directive = self._make_directive()
-        _, w, h = directive._prepare_svg(svg_bytes)
+        _, w, h = directive._prepare_svg(svg_text)
 
         assert w == ""
         assert h == ""
 
     def test_handles_px_dimensions(self):
-        svg_bytes = b'<svg width="200px" height="100px"><rect/></svg>'
+        svg_text = '<svg width="200px" height="100px"><rect/></svg>'
         directive = self._make_directive()
-        _, w, h = directive._prepare_svg(svg_bytes)
+        _, w, h = directive._prepare_svg(svg_text)
 
         assert w == "200px"
         assert h == "100px"
@@ -1030,15 +1030,15 @@ def _make_directive(self, options=None, tmp_path=None):
 
     def test_no_target_option(self):
         directive = self._make_directive()
-        assert directive._resolve_target(b"<svg/>") == ""
+        assert directive._resolve_target("<svg/>") == ""
 
     def test_explicit_target_url(self):
         directive = self._make_directive({"target": "https://example.com/diagram.svg"})
-        assert directive._resolve_target(b"<svg/>") == "https://example.com/diagram.svg"
+        assert directive._resolve_target("<svg/>") == "https://example.com/diagram.svg"
 
     def test_empty_target_generates_file(self, tmp_path):
         directive = self._make_directive({"target": ""}, tmp_path=tmp_path)
-        svg_data = b"<svg><rect/></svg>"
+        svg_data = "<svg><rect/></svg>"
         result = directive._resolve_target(svg_data)
 
         assert result.startswith("/_images/statemachine-")
@@ -1048,21 +1048,21 @@ def test_empty_target_generates_file(self, tmp_path):
         images_dir = tmp_path / "_images"
         svg_files = list(images_dir.glob("statemachine-*.svg"))
         assert len(svg_files) == 1
-        assert svg_files[0].read_bytes() == svg_data
+        assert svg_files[0].read_text(encoding="utf-8") == svg_data
 
     def test_empty_target_deterministic_filename(self, tmp_path):
         """Same qualname + events produces the same filename."""
         directive1 = self._make_directive({"target": "", "events": "go"}, tmp_path=tmp_path)
         directive2 = self._make_directive({"target": "", "events": "go"}, tmp_path=tmp_path)
-        result1 = directive1._resolve_target(b"<svg>1</svg>")
-        result2 = directive2._resolve_target(b"<svg>2</svg>")
+        result1 = directive1._resolve_target("<svg>1</svg>")
+        result2 = directive2._resolve_target("<svg>2</svg>")
         assert result1 == result2
 
     def test_different_events_different_filename(self, tmp_path):
         """Different events produce different filenames."""
         d1 = self._make_directive({"target": "", "events": "a"}, tmp_path=tmp_path)
         d2 = self._make_directive({"target": "", "events": "b"}, tmp_path=tmp_path)
-        assert d1._resolve_target(b"<svg/>") != d2._resolve_target(b"<svg/>")
+        assert d1._resolve_target("<svg/>") != d2._resolve_target("<svg/>")
 
 
 class TestDirectiveRun:
@@ -1347,6 +1347,33 @@ def test_render_dot(self):
         result = formatter.render(TrafficLightMachine, "dot")
         assert result.startswith("digraph TrafficLightMachine {")
 
+    def test_render_svg(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        result = formatter.render(TrafficLightMachine, "svg")
+        assert isinstance(result, str)
+        assert "<svg" in result
+        assert "green" in result
+
+    def test_render_svg_instance(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        sm = TrafficLightMachine()
+        result = formatter.render(sm, "svg")
+        assert "<svg" in result
+        # Active state should be highlighted
+        assert "turquoise" in result
+
+    def test_format_svg(self):
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        result = f"{TrafficLightMachine:svg}"
+        assert "<svg" in result
+
     def test_render_md(self):
         from statemachine.contrib.diagram import formatter
 
@@ -1398,6 +1425,7 @@ def test_supported_formats(self):
 
         fmts = formatter.supported_formats()
         assert "dot" in fmts
+        assert "svg" in fmts
         assert "mermaid" in fmts
         assert "md" in fmts
         assert "markdown" in fmts