python-statemachine 3.2.1__py3-none-any.whl → 3.2.2__py3-none-any.whl

statemachine/statemachine.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING
 from typing import Any
 from typing import Generic
 from typing import TypeVar
+from typing import cast
 
 from statemachine.orderedset import OrderedSet
 
@@ -146,7 +147,7 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         listeners: "list[object] | None" = None,
         **kwargs: Any,
     ):
-        self.model: TModel = model if model is not None else Model()  # type: ignore[assignment]
+        self.model: TModel = model if model is not None else cast(TModel, Model())
         """The external model object that holds domain state, or an internal
         :class:`Model` instance when none is provided.  See :ref:`domain models`."""
 
@@ -207,7 +208,7 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         instance_states: dict[Any, Any] = {}
         events = self.__class__._events
         for state in self.states_map.values():
-            ist = InstanceState(state, self)
+            ist = InstanceState(state, self, instance_states)
             instance_states[state.value] = ist
             if state.id not in events:
                 vars(self)[state.id] = ist
@@ -225,7 +226,11 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         return run_async_from_sync(result)
 
     def _processing_loop(self, caller_future: "Any | None" = None) -> Any:
-        result = self._engine.processing_loop(caller_future)
+        # Only the async engine gives an event a future, for its caller to await the result by.
+        if isinstance(self._engine, AsyncEngine):
+            result = self._engine.processing_loop(caller_future)
+        else:
+            result = self._engine.processing_loop()
         if not isawaitable(result):
             return result
         return run_async_from_sync(result)
@@ -259,7 +264,7 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
 
     def __setstate__(self, state: dict[str, Any]) -> None:
         listeners = state.pop("_listeners")
-        self.__dict__.update(state)  # type: ignore[attr-defined]
+        vars(self).update(state)
         self._callbacks = CallbacksRegistry()
         self._config = self._build_configuration()
         self._listeners = {}
@@ -273,11 +278,11 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         self._engine.start()
 
     def _get_initial_configuration(self):
-        initial_state_values = (
-            self.start_configuration_values
-            if self.start_configuration_values
-            else [self.initial_state.value]  # type: ignore[union-attr]
-        )
+        initial_state_values = self.start_configuration_values
+        if not initial_state_values:
+            # Only a machine with no states has no initial state, and none can be created.
+            assert self.initial_state is not None
+            initial_state_values = [self.initial_state.value]
         try:
             return [self.states_map[value] for value in initial_state_values]
         except KeyError as err:
@@ -362,7 +367,7 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         return f'<div class="statemachine">{self._repr_svg_()}</div>'
 
     def _repr_svg_(self):
-        return self._graph().create_svg().decode()  # type: ignore[attr-defined]
+        return format(self, "svg")
 
     def _graph(self):
         from .contrib.diagram import DotGraphMachine
@@ -460,18 +465,23 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         self,
         event: str,
         *args,
-        delay: float = 0,
+        delay: "float | None" = None,
         send_id: "str | None" = None,
-        internal: bool = False,
+        internal: "bool | None" = None,
         **kwargs,
     ) -> Any:
         """Send an :ref:`Event` to the state machine.
 
         :param event: The trigger for the state machine, specified as an event id string.
         :param args: Additional positional arguments to pass to the event.
-        :param delay: A time delay in milliseconds to process the event. Default is 0.
+        :param delay: A time delay in milliseconds to process the event. Defaults to the
+            event's declaration, or 0. An explicit ``0`` overrides a declared delay.
         :param send_id: An identifier for the event, used with ``cancel_event()`` to cancel
             delayed events.
+        :param internal: Put the event on the internal queue, so it runs within the current
+            macrostep. Defaults to the event's declaration. Honored from a callback; sent from
+            outside a step, the event goes to the external queue and its result is returned.
+            Cannot be combined with ``delay``.
         :param kwargs: Additional keyword arguments to pass to the event.
 
         .. seealso::
@@ -480,9 +490,10 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         """
         know_event = getattr(self, event, None)
         event_name = know_event.name if know_event else event
-        delay = (
-            delay if delay else know_event and know_event.delay or 0
-        )  # first the param, then the event, or 0
+        if delay is None:
+            delay = cast(float, know_event.delay if know_event else 0)
+        if internal is None:
+            internal = bool(know_event and know_event.internal)
         event_instance = BoundEvent(
             id=event, name=event_name, delay=delay, internal=internal, _sm=self
         )
@@ -492,13 +503,22 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         return run_async_from_sync(result)
 
     def raise_(
-        self, event: str, *args, delay: float = 0, send_id: "str | None" = None, **kwargs
+        self,
+        event: str,
+        *args,
+        delay: "float | None" = None,
+        send_id: "str | None" = None,
+        **kwargs,
     ) -> Any:
         """Send an :ref:`Event` to the state machine in the internal event queue.
 
         Events on the internal queue are processed immediately within the current
         macrostep, before any pending external events. This is equivalent to calling
-        ``send(..., internal=True)``.
+        ``send(..., internal=True)``: called from outside a callback, there is no macrostep
+        to join, so the event goes to the external queue and its result is returned. A
+        ``delay`` other than 0, given or declared on the event, is an
+        :class:`~statemachine.exceptions.InvalidDefinition`; pass ``delay=0`` to override a
+        declared one.
 
         .. seealso::
 
@@ -507,7 +527,10 @@ class StateChart(Generic[TModel], metaclass=StateMachineMetaclass):
         return self.send(event, *args, delay=delay, send_id=send_id, internal=True, **kwargs)
 
     def cancel_event(self, send_id: str):
-        """Cancel all the delayed events with the given ``send_id``."""
+        """Cancel all the delayed events with the given ``send_id``.
+
+        A caller awaiting one of them gets ``None``.
+        """
         self._engine.cancel_event(send_id)
 
     @property