refactor: introduce Formatter facade with decorator-based format registry

Replace duplicated if/elif chains in StateChart.__format__ and
StateMachineMetaclass.__format__ with a Formatter class that uses
a decorator-based registry following the Open/Closed Principle.

Adding a new format now requires only a decorated function — no
changes to __format__, factory.py, or statemachine.py.

Author: fgmacedo

statemachine/contrib/diagram/__init__.py

@@ -3,6 +3,7 @@
 from urllib.request import urlopen
 
 from .extract import extract
+from .formatter import formatter as formatter
 from .renderers.dot import DotRenderer
 from .renderers.dot import DotRendererConfig
 from .renderers.mermaid import MermaidRenderer
@@ -175,8 +176,8 @@ def write_image(qualname, out, events=None, fmt=None):
     If `events` is provided, the machine is instantiated and each event is sent
     before rendering, so the diagram highlights the current active state.
 
-    If `fmt` is provided, it overrides the output format: ``"mermaid"`` writes
-    Mermaid source text, ``"md"``/``"rst"`` write a transition table.
+    If `fmt` is provided, it overrides the output format (any registered text
+    format such as ``"mermaid"``, ``"dot"``, ``"md"``, ``"rst"``).
     Use ``out="-"`` to write to stdout.
     """
     import sys
@@ -190,15 +191,8 @@ def write_image(qualname, out, events=None, fmt=None):
     else:
         machine = smclass
 
-    if fmt in ("mermaid", "md", "rst"):
-        if fmt == "mermaid":
-            text = MermaidGraphMachine(machine).get_mermaid()
-        else:
-            from .renderers.table import TransitionTableRenderer
-
-            ir = extract(machine)
-            text = TransitionTableRenderer().render(ir, fmt=fmt)
-
+    if fmt is not None:
+        text = formatter.render(machine, fmt)
         if out == "-":
             sys.stdout.write(text)
         else:
@@ -234,9 +228,9 @@ def main(argv=None):
     )
     parser.add_argument(
         "--format",
-        choices=["mermaid", "md", "rst"],
+        choices=formatter.supported_formats(),
         default=None,
-        help="Output format: mermaid source, markdown table, or RST table.",
+        help="Output as text format instead of Graphviz image.",
     )
 
     args = parser.parse_args(argv)

statemachine/contrib/diagram/formatter.py

@@ -0,0 +1,129 @@
+"""Unified facade for rendering state machines in multiple text formats.
+
+The :class:`Formatter` class provides a decorator-based registry where each
+renderer declares the format names it handles.  Adding a new format only
+requires writing a renderer function and decorating it — no changes to
+``__format__``, ``factory.py``, or ``statemachine.py``.
+
+A module-level :data:`formatter` instance is the single public entry point::
+
+    from statemachine.contrib.diagram import formatter
+
+    print(formatter.render(sm, "mermaid"))
+
+    @formatter.register_format("plantuml")
+    def _render_plantuml(machine):
+        ...
+"""
+
+from typing import TYPE_CHECKING
+from typing import Callable
+from typing import Dict
+from typing import List
+
+if TYPE_CHECKING:
+    from typing import Union
+
+    from statemachine.statemachine import StateChart
+
+    MachineRef = Union["StateChart", "type[StateChart]"]
+
+
+class Formatter:
+    """Unified facade for rendering state machines in multiple text formats."""
+
+    def __init__(self) -> None:
+        self._formats: Dict[str, "Callable[[MachineRef], str]"] = {}
+
+    def register_format(
+        self, *names: str
+    ) -> "Callable[[Callable[[MachineRef], str]], Callable[[MachineRef], str]]":
+        """Decorator factory that registers a renderer under one or more format names.
+
+        Usage::
+
+            @formatter.register_format("md", "markdown")
+            def _render_md(machine_or_class):
+                ...
+        """
+
+        def decorator(
+            fn: "Callable[[MachineRef], str]",
+        ) -> "Callable[[MachineRef], str]":
+            for name in names:
+                self._formats[name] = fn
+            return fn
+
+        return decorator
+
+    def render(self, machine_or_class: "MachineRef", fmt: str) -> str:
+        """Render a state machine in the given text format.
+
+        Args:
+            machine_or_class: A ``StateChart`` instance or class.
+            fmt: Format name (e.g., ``"mermaid"``, ``"dot"``, ``"md"``).
+                Empty string falls back to ``repr()``.
+
+        Raises:
+            ValueError: If ``fmt`` is not registered.
+        """
+        if fmt == "":
+            return repr(machine_or_class)
+
+        renderer_fn = self._formats.get(fmt)
+        if renderer_fn is None:
+            primary = sorted({self._primary_name(fn) for fn in set(self._formats.values())})
+            raise ValueError(
+                f"Unsupported format: {fmt!r}. Use {', '.join(repr(n) for n in primary)}."
+            )
+        return renderer_fn(machine_or_class)
+
+    def supported_formats(self) -> List[str]:
+        """Return sorted list of all registered format names (including aliases)."""
+        return sorted(self._formats)
+
+    def _primary_name(self, fn: "Callable[[MachineRef], str]") -> str:
+        """Return the first registered name for a given renderer function."""
+        for name, registered_fn in self._formats.items():
+            if registered_fn is fn:
+                return name
+        return "?"  # pragma: no cover
+
+
+formatter = Formatter()
+"""Module-level :class:`Formatter` instance — the single public entry point."""
+
+
+# ---------------------------------------------------------------------------
+# Built-in format registrations
+# ---------------------------------------------------------------------------
+
+
+@formatter.register_format("dot")
+def _render_dot(machine_or_class: "MachineRef") -> str:
+    from statemachine.contrib.diagram import DotGraphMachine
+
+    return DotGraphMachine(machine_or_class).get_graph().to_string()  # type: ignore[no-any-return]
+
+
+@formatter.register_format("mermaid")
+def _render_mermaid(machine_or_class: "MachineRef") -> str:
+    from statemachine.contrib.diagram import MermaidGraphMachine
+
+    return MermaidGraphMachine(machine_or_class).get_mermaid()
+
+
+@formatter.register_format("md", "markdown")
+def _render_md(machine_or_class: "MachineRef") -> str:
+    from statemachine.contrib.diagram.extract import extract
+    from statemachine.contrib.diagram.renderers.table import TransitionTableRenderer
+
+    return TransitionTableRenderer().render(extract(machine_or_class), fmt="md")
+
+
+@formatter.register_format("rst")
+def _render_rst(machine_or_class: "MachineRef") -> str:
+    from statemachine.contrib.diagram.extract import extract
+    from statemachine.contrib.diagram.renderers.table import TransitionTableRenderer
+
+    return TransitionTableRenderer().render(extract(machine_or_class), fmt="rst")

statemachine/factory.py

@@ -93,28 +93,9 @@ def __init__(
         cls._setup()
 
     def __format__(cls, fmt: str) -> str:
-        if fmt == "mermaid":
-            from .contrib.diagram import MermaidGraphMachine
-
-            return MermaidGraphMachine(cls).get_mermaid()
-        elif fmt == "dot":
-            from .contrib.diagram import DotGraphMachine
-
-            return DotGraphMachine(cls).get_graph().to_string()  # type: ignore[no-any-return]
-        elif fmt in ("md", "markdown"):
-            from .contrib.diagram.extract import extract
-            from .contrib.diagram.renderers.table import TransitionTableRenderer
-
-            return TransitionTableRenderer().render(extract(cls), fmt="md")  # type: ignore[arg-type]
-        elif fmt == "rst":
-            from .contrib.diagram.extract import extract
-            from .contrib.diagram.renderers.table import TransitionTableRenderer
-
-            return TransitionTableRenderer().render(extract(cls), fmt="rst")  # type: ignore[arg-type]
-        elif fmt == "":
-            return repr(cls)
-        else:
-            raise ValueError(f"Unsupported format: {fmt!r}. Use 'dot', 'mermaid', 'md', or 'rst'.")
+        from .contrib.diagram.formatter import formatter
+
+        return formatter.render(cls, fmt)  # type: ignore[arg-type]
 
     def _initials_by_document_order(  # noqa: C901
         cls, states: List[State], parent: "State | None" = None, order: int = 1

statemachine/statemachine.py

@@ -240,28 +240,9 @@ def __repr__(self):
         )
 
     def __format__(self, fmt: str) -> str:
-        if fmt == "mermaid":
-            from .contrib.diagram import MermaidGraphMachine
-
-            return MermaidGraphMachine(self).get_mermaid()
-        elif fmt == "dot":
-            from .contrib.diagram import DotGraphMachine
-
-            return DotGraphMachine(self).get_graph().to_string()  # type: ignore[no-any-return]
-        elif fmt in ("md", "markdown"):
-            from .contrib.diagram.extract import extract
-            from .contrib.diagram.renderers.table import TransitionTableRenderer
-
-            return TransitionTableRenderer().render(extract(self), fmt="md")
-        elif fmt == "rst":
-            from .contrib.diagram.extract import extract
-            from .contrib.diagram.renderers.table import TransitionTableRenderer
-
-            return TransitionTableRenderer().render(extract(self), fmt="rst")
-        elif fmt == "":
-            return repr(self)
-        else:
-            raise ValueError(f"Unsupported format: {fmt!r}. Use 'dot', 'mermaid', 'md', or 'rst'.")
+        from .contrib.diagram.formatter import formatter
+
+        return formatter.render(self, fmt)
 
     def __getstate__(self):
         state = {k: v for k, v in self.__dict__.items() if not isinstance(v, InstanceState)}

tests/test_contrib_diagram.py

@@ -1328,6 +1328,121 @@ def test_format_invalid_class_raises(self):
             f"{TrafficLightMachine:invalid}"
 
 
+class TestFormatter:
+    """Tests for the Formatter facade (render, register_format, supported_formats)."""
+
+    def test_render_mermaid(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        result = formatter.render(TrafficLightMachine, "mermaid")
+        assert "stateDiagram-v2" in result
+
+    def test_render_dot(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        result = formatter.render(TrafficLightMachine, "dot")
+        assert result.startswith("digraph TrafficLightMachine {")
+
+    def test_render_md(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        result = formatter.render(TrafficLightMachine, "md")
+        assert "| State" in result
+
+    def test_render_markdown_alias(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        assert formatter.render(TrafficLightMachine, "markdown") == formatter.render(
+            TrafficLightMachine, "md"
+        )
+
+    def test_render_rst(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        result = formatter.render(TrafficLightMachine, "rst")
+        assert "+---" in result
+
+    def test_render_empty_repr_instance(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        sm = TrafficLightMachine()
+        assert formatter.render(sm, "") == repr(sm)
+
+    def test_render_empty_repr_class(self):
+        from statemachine.contrib.diagram import formatter
+
+        from tests.examples.traffic_light_machine import TrafficLightMachine
+
+        assert formatter.render(TrafficLightMachine, "") == repr(TrafficLightMachine)
+
+    def test_render_invalid_raises(self):
+        from statemachine.contrib.diagram import formatter
+
+        with pytest.raises(ValueError, match="Unsupported format"):
+            formatter.render(object(), "invalid")
+
+    def test_supported_formats(self):
+        from statemachine.contrib.diagram import formatter
+
+        fmts = formatter.supported_formats()
+        assert "dot" in fmts
+        assert "mermaid" in fmts
+        assert "md" in fmts
+        assert "markdown" in fmts
+        assert "rst" in fmts
+
+    def test_register_custom_format(self):
+        from statemachine.contrib.diagram import formatter
+
+        @formatter.register_format("_test_custom")
+        def _render_custom(machine_or_class):
+            return "custom output"
+
+        try:
+            assert formatter.render(object(), "_test_custom") == "custom output"
+        finally:
+            formatter._formats.pop("_test_custom", None)
+
+    def test_register_format_with_aliases(self):
+        from statemachine.contrib.diagram import formatter
+
+        @formatter.register_format("_test_alias", "_test_alias2")
+        def _render_alias_test(machine_or_class):
+            return "alias output"
+
+        try:
+            assert formatter.render(object(), "_test_alias") == "alias output"
+            assert formatter.render(object(), "_test_alias2") == "alias output"
+        finally:
+            formatter._formats.pop("_test_alias", None)
+            formatter._formats.pop("_test_alias2", None)
+
+    def test_error_message_lists_primary_formats(self):
+        from statemachine.contrib.diagram import formatter
+
+        with pytest.raises(ValueError, match="'dot'") as exc_info:
+            formatter.render(object(), "nonexistent")
+        msg = str(exc_info.value)
+        # Should list primary names, not aliases
+        assert "'mermaid'" in msg
+        assert "'md'" in msg
+        assert "'rst'" in msg
+        # "markdown" is an alias, should not appear in error message
+        assert "'markdown'" not in msg
+
+
 class TestDirectiveMermaidFormat:
     """Tests for the :format: mermaid Sphinx directive option."""