feat: State.Builder mimic the State API to help mypy

Author: fgmacedo

statemachine/state.py

@@ -27,10 +27,6 @@ def __new__(  # type: ignore [misc]
         return State(name=name, substates=substates, **kwargs)
 
 
-class NestedStateBuilder(metaclass=NestedStateFactory):
-    pass
-
-
 class State:
     """
     A State in a :ref:`StateMachine` describes a particular behavior of the machine.
@@ -111,7 +107,29 @@ class State:
     """
 
     class Builder(metaclass=NestedStateFactory):
-        pass
+
+        # Mimic the :ref:`State` public API to help linters discover the result of the Builder
+        # class.
+
+        @classmethod
+        def to(cls, *args: "State", **kwargs) -> "TransitionList":  # pragma: no cover
+            """Create transitions to the given target states.
+
+            .. note: This method is only a type hint for mypy.
+                The actual implementation belongs to the :ref:`State` class.
+            """
+            return TransitionList()
+
+        @classmethod
+        def from_(
+            cls, *args: "State", **kwargs
+        ) -> "TransitionList":  # pragma: no cover
+            """Create transitions from the given target states (reversed).
+
+            .. note: This method is only a type hint for mypy.
+                The actual implementation belongs to the :ref:`State` class.
+            """
+            return TransitionList()
 
     def __init__(
         self,

tests/examples/microwave_inheritance_machine.py

@@ -50,7 +50,6 @@ class on(State.Builder):
                 cooking.to(idle, cond="open.is_active")
                 cooking.to.itself(internal=True, on="increment_timer")
 
-            assert isinstance(on, State)  # so mypy stop complaining
             turn_off = on.to(off)
             turn_on = off.to(on)
             on.to(off, cond="cook_time_is_over")  # eventless transition

tests/examples/traffic_light_nested_machine.py

@@ -27,7 +27,6 @@ class red(State.Builder, enter="reset_elapsed"):
 
         ped_countdown = walk.to(wait) | wait.to(stop)
 
-    assert isinstance(red, State)
     timer = green.to(yellow) | yellow.to(red) | red.to(green)
     power_outage = red.blinking.from_()
     power_restored = red.from_()