feat: add pyright support, Generic[TModel], remove __getattr__ catch-all (#566)

fgmacedo · web-flow · commit a214e04554e1 · 2026-02-15T09:13:23.000-03:00
* feat: add pyright support, Generic[TModel] for typed models, remove __getattr__ catch-all - Add pyright as dev dependency + pre-commit hook, configured with basic type checking targeting Python 3.9 - Make StateChart generic over TModel so `sm.model` gets proper type inference and IDE autocompletion when a model class is provided - Remove TYPE_CHECKING `__getattr__` stubs from both StateChart and StateMachineMetaclass — type checkers now detect misspelled attributes and unresolved references on subclasses - Add explicit type declarations for metaclass-set attributes (name, id, states, states_map, initial_state, final_states) with docstrings - Add return type annotations throughout (send, raise_, enabled_events, activate_initial_state, Event.__call__, run_async_from_sync, etc.) - Fix all 38 baseline pyright errors with proper types, assertions for weakref derefs, and targeted type: ignore for genuinely dynamic APIs (pydot, partial attributes, conditional function definitions) - Update tests/examples to use configuration_values for enum-based state checks instead of relying on dynamic attribute access - Document typed models in docs/models.md and docs/releases/3.0.0.md Closes #515
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -25,6 +25,12 @@ repos:
     types: [python]
     language: system
     pass_filenames: false
+  - id: pyright
+    name: Pyright
+    entry: uv run pyright statemachine/
+    types: [python]
+    language: system
+    pass_filenames: false
   - id: pytest
     name: Pytest
     entry: uv run pytest -n auto
diff --git a/docs/models.md b/docs/models.md
@@ -25,3 +25,45 @@ provided to the built-in {ref}`StateChart`, such as implementing all {ref}`actio
 {ref}`guards` on your domain model and keeping only the definition of {ref}`states` and
 {ref}`transitions` on the {ref}`StateChart`.
 ```
+
+## Typed models
+
+`StateChart` supports a generic type parameter so that type checkers (mypy, pyright) and IDEs
+can infer the type of `sm.model` and provide code completion.
+
+Declare your model class and pass it as a type parameter to `StateChart`:
+
+```python
+>>> from statemachine import State, StateChart
+
+>>> class OrderModel:
+...     order_id: str = ""
+...     total: float = 0.0
+...     def confirm(self):
+...         return f"Order {self.order_id} confirmed: ${self.total}"
+
+>>> class OrderWorkflow(StateChart["OrderModel"]):
+...     draft = State(initial=True)
+...     confirmed = State(final=True)
+...     confirm = draft.to(confirmed, on="on_confirm")
+...     def on_confirm(self):
+...         return self.model.confirm()
+
+>>> model = OrderModel()
+>>> model.order_id = "A-123"
+>>> model.total = 49.90
+>>> sm = OrderWorkflow(model=model)
+
+>>> sm.send("confirm")
+'Order A-123 confirmed: $49.9'
+
+```
+
+With this declaration, `sm.model` is typed as `OrderModel` instead of `Any`, so
+`sm.model.order_id`, `sm.model.total`, and `sm.model.confirm()` all get full
+autocompletion and type checking in your IDE.
+
+```{note}
+When no type parameter is given (e.g. `class MySM(StateChart)`), the model defaults
+to `Any`, preserving full backward compatibility.
+```
diff --git a/docs/releases/3.0.0.md b/docs/releases/3.0.0.md
@@ -346,6 +346,41 @@ flag `validate_disconnected_states: bool = True` that can be used to disable thi
 It's already disabled when parsing SCXML files.
 
 
+### Typed models with `Generic[TModel]`
+
+`StateChart` now supports a generic type parameter for the model, enabling full type
+inference and IDE autocompletion on `sm.model`:
+
+```py
+>>> from statemachine import State, StateChart
+
+>>> class MyModel:
+...     name: str = ""
+...     value: int = 0
+
+>>> class MySM(StateChart["MyModel"]):
+...     idle = State(initial=True)
+...     active = State(final=True)
+...     go = idle.to(active)
+
+>>> sm = MySM(model=MyModel())
+>>> sm.model.name
+''
+
+```
+
+With this declaration, type checkers infer `sm.model` as `MyModel` (not `Any`), so
+accessing `sm.model.name` or `sm.model.value` gets full autocompletion and type safety.
+When no type parameter is given, `StateChart` defaults to `StateChart[Any]` for backward
+compatibility. See {ref}`domain models` for details.
+
+### Improved type checking with pyright
+
+The library now supports [pyright](https://github.com/microsoft/pyright) in addition to mypy.
+Type annotations have been improved throughout the codebase, and a catch-all `__getattr__`
+that previously returned `Any` has been removed — type checkers can now detect misspelled
+attribute names and unresolved references on `StateChart` subclasses.
+
 ### Weighted (probabilistic) transitions
 
 A new contrib module `statemachine.contrib.weighted` provides `weighted_transitions()`,
diff --git a/pyproject.toml b/pyproject.toml
@@ -56,6 +56,7 @@ dev = [
     "babel >=2.16.0; python_version >='3.8'",
     "pytest-xdist>=3.6.1",
     "pytest-timeout>=2.3.1",
+    "pyright>=1.1.400",
 ]
 
 [build-system]
@@ -201,3 +202,6 @@ fixture-parentheses = true
 mark-parentheses = true
 
 [tool.pyright]
+pythonVersion = "3.9"
+typeCheckingMode = "basic"
+include = ["statemachine"]
diff --git a/statemachine/__init__.py b/statemachine/__init__.py
@@ -3,9 +3,10 @@
 from .state import State
 from .statemachine import StateChart
 from .statemachine import StateMachine
+from .statemachine import TModel
 
 __author__ = """Fernando Macedo"""
 __email__ = "fgmacedo@gmail.com"
 __version__ = "2.6.0"
 
-__all__ = ["StateChart", "StateMachine", "State", "HistoryState", "Event"]
+__all__ = ["StateChart", "StateMachine", "State", "HistoryState", "Event", "TModel"]
diff --git a/statemachine/callbacks.py b/statemachine/callbacks.py
@@ -96,8 +96,8 @@ def __init__(
             name = func.func.__name__ if is_partial else func.__name__
             self.attr_name = name if not self.is_event or self.is_bounded else f"_{name}_"
             if not self.is_bounded:
-                func.attr_name = self.attr_name
-                func.is_event = is_event
+                func.attr_name = self.attr_name  # type: ignore[union-attr]
+                func.is_event = is_event  # type: ignore[union-attr]
         else:
             self.reference = SpecReference.NAME
             self.attr_name = func
@@ -270,7 +270,7 @@ class CallbacksExecutor:
     """A list of callbacks that can be executed in order."""
 
     def __init__(self):
-        self.items: List[CallbackWrapper] = deque()
+        self.items: "deque[CallbackWrapper]" = deque()
         self.items_already_seen = set()
 
     def __iter__(self):
diff --git a/statemachine/contrib/diagram.py b/statemachine/contrib/diagram.py
@@ -69,7 +69,7 @@ def _initial_node(self, state):
             width=0.2,
             height=0.2,
         )
-        node.set_fillcolor("black")
+        node.set_fillcolor("black")  # type: ignore[attr-defined]
         return node
 
     def _initial_edge(self, initial_node, state):
@@ -89,7 +89,7 @@ def _initial_edge(self, initial_node, state):
     def _actions_getter(self):
         if isinstance(self.machine, StateChart):
 
-            def getter(grouper):
+            def getter(grouper):  # pyright: ignore[reportRedeclaration]
                 return self.machine._callbacks.str(grouper.key)
         else:
 
@@ -162,10 +162,10 @@ def _state_as_node(self, state):
             isinstance(self.machine, StateChart)
             and state.value in self.machine.configuration_values
         ):
-            node.set_penwidth(self.state_active_penwidth)
-            node.set_fillcolor(self.state_active_fillcolor)
+            node.set_penwidth(self.state_active_penwidth)  # type: ignore[attr-defined]
+            node.set_fillcolor(self.state_active_fillcolor)  # type: ignore[attr-defined]
         else:
-            node.set_fillcolor("white")
+            node.set_fillcolor("white")  # type: ignore[attr-defined]
         return node
 
     def _transition_as_edges(self, transition):
diff --git a/statemachine/dispatcher.py b/statemachine/dispatcher.py
@@ -194,7 +194,7 @@ def callable_method(a_callable) -> Callable:
 
     if sig.is_coroutine:
 
-        async def signature_adapter(*args: Any, **kwargs: Any) -> Any:
+        async def signature_adapter(*args: Any, **kwargs: Any) -> Any:  # pyright: ignore[reportRedeclaration]
             ba = sig_bind_expected(*args, **kwargs)
             return await a_callable(*ba.args, **ba.kwargs)
     else:
diff --git a/statemachine/event.py b/statemachine/event.py
@@ -1,4 +1,5 @@
 from typing import TYPE_CHECKING
+from typing import Any
 from typing import List
 from typing import cast
 from uuid import uuid4
@@ -11,6 +12,7 @@
 
 if TYPE_CHECKING:
     from .statemachine import StateChart
+    from .transition import Transition
     from .transition_list import TransitionList
 
 
@@ -57,7 +59,7 @@ class Event(AddCallbacksMixin, str):
 
     def __new__(
         cls,
-        transitions: "str | TransitionList | None" = None,
+        transitions: "str | Transition | TransitionList | None" = None,
         id: "str | None" = None,
         name: "str | None" = None,
         delay: float = 0,
@@ -82,7 +84,7 @@ def __new__(
         else:
             instance.name = ""
         if transitions:
-            instance._transitions = transitions
+            instance._transitions = transitions  # type: ignore[assignment]
         instance._has_real_id = _has_real_id
         instance._sm = _sm
         return instance
@@ -144,7 +146,7 @@ def build_trigger(self, *args, machine: "StateChart", send_id: "str | None" = No
 
         return trigger_data
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, *args, **kwargs) -> Any:
         """Send this event to the current state machine.
 
         Triggering an event on a state machine means invoking or sending a signal, initiating the
@@ -155,7 +157,7 @@ def __call__(self, *args, **kwargs):
         # an SM instance. Such SM instance is provided by `__get__` method when
         # used as a property descriptor.
         self.put(*args, **kwargs)
-        return self._sm._processing_loop()  # type: ignore
+        return self._sm._processing_loop()  # type: ignore[union-attr]
 
     def split(  # type: ignore[override]
         self, sep: "str | None" = None, maxsplit: int = -1
diff --git a/statemachine/events.py b/statemachine/events.py
@@ -35,8 +35,8 @@ def add(self, events):
         return self
 
     def match(self, event: "str | None"):
-        if event is None and self.is_empty:
-            return True
+        if event is None:
+            return self.is_empty
         return any(e.match(event) for e in self)
 
     def _replace(self, old, new):
diff --git a/statemachine/factory.py b/statemachine/factory.py
@@ -1,8 +1,8 @@
 import warnings
-from typing import TYPE_CHECKING
 from typing import Any
 from typing import Dict
 from typing import List
+from typing import Optional
 from typing import Tuple
 
 from . import registry
@@ -49,7 +49,7 @@ def __init__(
         cls._strict_states = strict_states
         cls._events: Dict[Event, None] = {}  # used Dict to preserve order and avoid duplicates
         cls._protected_attrs: set = set()
-        cls._events_to_update: Dict[Event, Event | None] = {}
+        cls._events_to_update: Dict[Event, Optional[Event]] = {}
         cls._specs = CallbackSpecList()
         cls.prepare = cls._specs.grouper(CallbackGroup.PREPARE).add(
             "prepare_event", priority=CallbackPriority.GENERIC, is_convention=True
@@ -86,11 +86,6 @@ def __init__(
         cls._check()
         cls._setup()
 
-    if TYPE_CHECKING:
-        """Makes mypy happy with dynamic created attributes"""
-
-        def __getattr__(self, attribute: str) -> Any: ...
-
     def _initials_by_document_order(  # noqa: C901
         cls, states: List[State], parent: "State | None" = None, order: int = 1
     ):
diff --git a/statemachine/io/scxml/actions.py b/statemachine/io/scxml/actions.py
@@ -159,6 +159,8 @@ def _eval(expr: str, **kwargs) -> Any:
 
 
 class CallableAction:
+    action: Any
+
     def __init__(self):
         self.__qualname__ = f"{self.__class__.__module__}.{self.__class__.__name__}"
 
@@ -373,7 +375,7 @@ def create_send_action_callable(action: SendAction) -> Callable:  # noqa: C901
 
     def send_action(*args, **kwargs):
         machine: StateChart = kwargs["machine"]
-        event = action.event or _eval(action.eventexpr, **kwargs)
+        event = action.event or _eval(action.eventexpr, **kwargs)  # type: ignore[arg-type]
         target = action.target if action.target else None
 
         if action.type and action.type != "http://www.w3.org/TR/scxml/#SCXMLEventProcessor":
diff --git a/statemachine/io/scxml/processor.py b/statemachine/io/scxml/processor.py
@@ -97,7 +97,7 @@ def process_definition(self, definition, location: str):
                 if isinstance(  # pragma: no branch – always a list from lines above
                     initial_state["enter"], list
                 ):
-                    initial_state["enter"].insert(0, datamodel)
+                    initial_state["enter"].insert(0, datamodel)  # type: ignore[arg-type]
 
         self._add(
             location,
diff --git a/statemachine/registry.py b/statemachine/registry.py
@@ -1,3 +1,6 @@
+from typing import List
+from typing import Optional
+
 from .utils import qualname
 
 try:
@@ -29,6 +32,6 @@ def init_registry():
         _initialized = True
 
 
-def load_modules(modules=None):
-    for module in modules:
+def load_modules(modules: Optional[List[str]] = None) -> None:
+    for module in modules or []:
         autodiscover_modules(module)
diff --git a/statemachine/signature.py b/statemachine/signature.py
@@ -18,7 +18,9 @@
 
 def _make_key(method):
     method = method.func if isinstance(method, partial) else method
-    method = method.fget if isinstance(method, property) else method
+    if isinstance(method, property):  # pragma: no cover
+        assert method.fget is not None
+        method = method.fget
     if isinstance(method, MethodType):
         return hash(
             (
diff --git a/statemachine/spec_parser.py b/statemachine/spec_parser.py
@@ -201,6 +201,7 @@ def build_expression(node, variable_hook, operator_mapping):  # noqa: C901
         return reduce(custom_and, expressions)
     elif isinstance(node, ast.Call):
         # Handle function calls
+        assert isinstance(node.func, ast.Name)
         constructor = Functions.get(node.func.id)
         params = [arg.value for arg in node.args if isinstance(arg, ast.Constant)]
         return constructor(*params)
diff --git a/statemachine/state.py b/statemachine/state.py
diff --git a/statemachine/statemachine.py b/statemachine/statemachine.py
diff --git a/statemachine/states.py b/statemachine/states.py
diff --git a/statemachine/utils.py b/statemachine/utils.py
diff --git a/tests/examples/enum_campaign_machine.py b/tests/examples/enum_campaign_machine.py
diff --git a/tests/test_copy.py b/tests/test_copy.py
diff --git a/uv.lock b/uv.lock
