python-statemachine 2.1.2__py3-none-any.whl → 2.3.0__py3-none-any.whl

statemachine/mixins.py

@@ -20,9 +20,7 @@ class MachineMixin:
         super().__init__(*args, **kwargs)
         if not self.state_machine_name:
             raise ValueError(
-                _("{!r} is not a valid state machine name.").format(
-                    self.state_machine_name
-                )
+                _("{!r} is not a valid state machine name.").format(self.state_machine_name)
             )
         machine_cls = registry.get_machine_cls(self.state_machine_name)
         setattr(

statemachine/signature.py

@@ -1,14 +1,16 @@
-import itertools
 from functools import partial
 from inspect import BoundArguments
 from inspect import Parameter
 from inspect import Signature
+from inspect import iscoroutinefunction
+from itertools import chain
 from types import MethodType
 from typing import Any
 
 
 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, MethodType):
         return hash(
             (
@@ -22,7 +24,6 @@ def _make_key(method):
 
 
 def signature_cache(user_function):
-
     cache = {}
     cache_get = cache.get
 
@@ -51,9 +52,16 @@ class SignatureAdapter(Signature):
 
         metadata_to_copy = method.func if isinstance(method, partial) else method
 
-        def method_wrapper(*args: Any, **kwargs: Any) -> Any:
-            ba = sig_bind_expected(*args, **kwargs)
-            return method(*ba.args, **ba.kwargs)
+        if iscoroutinefunction(method):
+
+            async def method_wrapper(*args: Any, **kwargs: Any) -> Any:
+                ba = sig_bind_expected(*args, **kwargs)
+                return await method(*ba.args, **ba.kwargs)
+        else:
+
+            async def method_wrapper(*args: Any, **kwargs: Any) -> Any:
+                ba = sig_bind_expected(*args, **kwargs)
+                return method(*ba.args, **ba.kwargs)
 
         method_wrapper.__name__ = metadata_to_copy.__name__
 
@@ -113,8 +121,7 @@ class SignatureAdapter(Signature):
                         parameters_ex = (param,)
                         break
                     elif (
-                        param.kind == Parameter.VAR_KEYWORD
-                        or param.default is not Parameter.empty
+                        param.kind == Parameter.VAR_KEYWORD or param.default is not Parameter.empty
                     ):
                         # That's fine too - we have a default value for this
                         # parameter.  So, lets start parsing `kwargs`, starting
@@ -161,7 +168,7 @@ class SignatureAdapter(Signature):
 
         # Now, we iterate through the remaining parameters to process
         # keyword arguments
-        for param in itertools.chain(parameters_ex, parameters):
+        for param in chain(parameters_ex, parameters):
             if param.kind == Parameter.VAR_KEYWORD:
                 # Memorize that we have a '**kwargs'-like parameter
                 kwargs_param = param

statemachine/state.py

@@ -4,6 +4,7 @@ from typing import Dict
 from weakref import ref
 
 from .callbacks import CallbackMetaList
+from .callbacks import CallbackPriority
 from .exceptions import StateMachineError
 from .i18n import _
 from .transition import Transition
@@ -107,31 +108,30 @@ class State:
         self._final = final
         self._id: str = ""
         self.transitions = TransitionList()
-        self.enter = CallbackMetaList().add(enter)
-        self.exit = CallbackMetaList().add(exit)
+        self.enter = CallbackMetaList().add(enter, priority=CallbackPriority.INLINE)
+        self.exit = CallbackMetaList().add(exit, priority=CallbackPriority.INLINE)
 
     def __eq__(self, other):
-        return (
-            isinstance(other, State) and self.name == other.name and self.id == other.id
-        )
+        return isinstance(other, State) and self.name == other.name and self.id == other.id
 
     def __hash__(self):
         return hash(repr(self))
 
-    def _setup(self, register):
+    def _setup(self):
+        self.enter.add("on_enter_state", priority=CallbackPriority.GENERIC, suppress_errors=True)
+        self.enter.add(
+            f"on_enter_{self.id}", priority=CallbackPriority.NAMING, suppress_errors=True
+        )
+        self.exit.add("on_exit_state", priority=CallbackPriority.GENERIC, suppress_errors=True)
+        self.exit.add(f"on_exit_{self.id}", priority=CallbackPriority.NAMING, suppress_errors=True)
+
+    def _add_observer(self, register):
         register(self.enter)
         register(self.exit)
-        return self
 
-    def _add_observer(self, registry):
-        self.enter.add(
-            "on_enter_state", registry=registry, prepend=True, suppress_errors=True
-        )
-        self.enter.add(f"on_enter_{self.id}", registry=registry, suppress_errors=True)
-        self.exit.add(
-            "on_exit_state", registry=registry, prepend=True, suppress_errors=True
-        )
-        self.exit.add(f"on_exit_{self.id}", registry=registry, suppress_errors=True)
+    def _check_callbacks(self, check):
+        check(self.enter)
+        check(self.exit)
 
     def __repr__(self):
         return (
@@ -139,6 +139,9 @@ class State:
             f"initial={self.initial!r}, final={self.final!r})"
         )
 
+    def __str__(self):
+        return self.name
+
     def __get__(self, machine, owner):
         if machine is None:
             return self
@@ -146,14 +149,10 @@ class State:
 
     def __set__(self, instance, value):
         raise StateMachineError(
-            _("State overriding is not allowed. Trying to add '{}' to {}").format(
-                value, self.id
-            )
+            _("State overriding is not allowed. Trying to add '{}' to {}").format(value, self.id)
         )
 
-    def for_instance(
-        self, machine: "StateMachine", cache: Dict["State", "State"]
-    ) -> "State":
+    def for_instance(self, machine: "StateMachine", cache: Dict["State", "State"]) -> "State":
         if self not in cache:
             cache[self] = InstanceState(self, machine)
 
@@ -171,9 +170,7 @@ class State:
             self.name = self._id.replace("_", " ").capitalize()
 
     def _to_(self, *states: "State", **kwargs):
-        transitions = TransitionList(
-            Transition(self, state, **kwargs) for state in states
-        )
+        transitions = TransitionList(Transition(self, state, **kwargs) for state in states)
         self.transitions.add_transitions(transitions)
         return transitions
 

statemachine/statemachine.py

@@ -1,9 +1,15 @@
 from collections import deque
+from copy import deepcopy
 from functools import partial
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import Dict
 
+from statemachine.graph import iterate_states_and_transitions
+from statemachine.utils import run_async_from_sync
+
+from .callbacks import CallbackMetaList
+from .callbacks import CallbacksExecutor
 from .callbacks import CallbacksRegistry
 from .dispatcher import ObjectConfig
 from .dispatcher import resolver_factory
@@ -68,27 +74,32 @@ class StateMachine(metaclass=StateMachineMetaclass):
         self.state_field = state_field
         self.start_value = start_value
         self.allow_event_without_transition = allow_event_without_transition
+        self.__initialized = False
         self.__rtc = rtc
         self.__processing: bool = False
         self._external_queue: deque = deque()
         self._callbacks_registry = CallbacksRegistry()
-        self._states_for_instance: Dict["State", "State"] = {}
+        self._states_for_instance: Dict[State, State] = {}
+        self._observers: Dict[Any, Any] = {}
 
-        assert hasattr(self, "_abstract")
         if self._abstract:
             raise InvalidDefinition(_("There are no states or transitions."))
 
-        initial_transition = Transition(
-            None, self._get_initial_state(), event="__initial__"
-        )
-        self._setup(initial_transition)
-        self._activate_initial_state(initial_transition)
+        self._register_callbacks()
+
+        # Activate the initial state, this only works if the outer scope is sync code.
+        # for async code, the user should manually call `await sm.activate_initial_state()`
+        # after state machine creation.
+        run_async_from_sync(self.activate_initial_state())
+
+    def __init_subclass__(cls, strict_states: bool = False):
+        cls._strict_states = strict_states
+        super().__init_subclass__()
 
     if TYPE_CHECKING:
         """Makes mypy happy with dynamic created attributes"""
 
-        def __getattr__(self, attribute: str) -> Any:
-            ...
+        def __getattr__(self, attribute: str) -> Any: ...
 
     def __repr__(self):
         current_state_id = self.current_state.id if self.current_state_value else None
@@ -97,19 +108,47 @@ class StateMachine(metaclass=StateMachineMetaclass):
             f"current_state={current_state_id!r})"
         )
 
+    def __deepcopy__(self, memo):
+        deepcopy_method = self.__deepcopy__
+        self.__deepcopy__ = None
+        try:
+            cp = deepcopy(self, memo)
+        finally:
+            self.__deepcopy__ = deepcopy_method
+            cp.__deepcopy__ = deepcopy_method
+        cp._callbacks_registry.clear()
+        cp._register_callbacks()
+        cp.add_observer(*cp._observers.keys())
+        return cp
+
     def _get_initial_state(self):
-        current_state_value = (
-            self.start_value if self.start_value else self.initial_state.value
-        )
+        current_state_value = self.start_value if self.start_value else self.initial_state.value
         try:
             return self.states_map[current_state_value]
         except KeyError as err:
             raise InvalidStateValue(current_state_value) from err
 
-    def _activate_initial_state(self, initial_transition):
+    async def activate_initial_state(self):
+        """
+        Activate the initial state.
+
+        Called automatically on state machine creation from sync code, but in
+        async code, the user must call this method explicitly.
+
+        Given how async works on python, there's no built-in way to activate the initial state that
+        may depend on async code from the StateMachine.__init__ method.
+
+        We do a `_ensure_is_initialized()` check before each event, but to check the current state
+        just before the state machine is created, the user must await the activation of the initial
+        state explicitly.
+        """
+        if self.__initialized:
+            return
+        self.__initialized = True
         if self.current_state_value is None:
             # send an one-time event `__initial__` to enter the current state.
             # current_state = self.current_state
+            initial_transition = Transition(None, self._get_initial_state(), event="__initial__")
             initial_transition.before.clear()
             initial_transition.on.clear()
             initial_transition.after.clear()
@@ -121,65 +160,34 @@ class StateMachine(metaclass=StateMachineMetaclass):
                 ),
                 transition=initial_transition,
             )
-            self._activate(event_data)
-
-    def _get_protected_attrs(self):
-        return {
-            "_abstract",
-            "model",
-            "state_field",
-            "start_value",
-            "initial_state",
-            "final_states",
-            "states",
-            "_events",
-            "states_map",
-            "send",
-        } | {s.id for s in self.states}
-
-    def _visit_states_and_transitions(self, visitor):
-        for state in self.states:
-            visitor(state)
-            for transition in state.transitions:
-                visitor(transition)
-
-    def _setup(self, initial_transition: Transition):
-        """
-        Args:
-            initial_transition: A special :ref:`transition` that triggers the enter on the
-                `initial` :ref:`State`.
-        """
-        machine = ObjectConfig.from_obj(self, skip_attrs=self._get_protected_attrs())
-        model = ObjectConfig.from_obj(self.model, skip_attrs={self.state_field})
-        default_resolver = resolver_factory(machine, model)
+            await self._activate(event_data)
 
-        register = partial(self._callbacks_registry.register, resolver=default_resolver)
+    async def _ensure_is_initialized(self):
+        await self.activate_initial_state()
 
-        observer_visitor = self._build_observers_visitor(machine, model)
-
-        def setup_visitor(visited):
-            visited._setup(register)
-            observer_visitor(visited)
-
-        self._visit_states_and_transitions(setup_visitor)
-
-        initial_transition._setup(register)
-
-    def _build_observers_visitor(self, *observers):
-        registry_callbacks = [
+    def _register_callbacks(self):
+        self._add_observer(
             (
-                self._callbacks_registry.build_register_function_for_resolver(
-                    resolver_factory(observer)
-                )
+                ObjectConfig.from_obj(self, skip_attrs=self._protected_attrs),
+                ObjectConfig.from_obj(self.model, skip_attrs={self.state_field}),
             )
-            for observer in observers
-        ]
+        )
 
-        def _add_observer_for_resolver(visited):
-            for register in registry_callbacks:
-                visited._add_observer(register)
+        check_callbacks = self._callbacks_registry.check
+        for visited in iterate_states_and_transitions(self.states):
+            try:
+                visited._check_callbacks(check_callbacks)
+            except Exception as err:
+                raise InvalidDefinition(
+                    f"Error on {visited!s} when resolving callbacks: {err}"
+                ) from err
 
-        return _add_observer_for_resolver
+    def _add_observer(self, observers):
+        register = partial(self._callbacks_registry.register, resolver=resolver_factory(observers))
+        for visited in iterate_states_and_transitions(self.states):
+            visited._add_observer(register)
+
+        return self
 
     def add_observer(self, *observers):
         """Add an observer.
@@ -191,10 +199,8 @@ class StateMachine(metaclass=StateMachineMetaclass):
 
             :ref:`observers`.
         """
-
-        visitor = self._build_observers_visitor(*observers)
-        self._visit_states_and_transitions(visitor)
-        return self
+        self._observers.update({o: None for o in observers})
+        return self._add_observer(tuple(ObjectConfig.from_obj(o) for o in observers))
 
     def _repr_html_(self):
         return f'<div class="statemachine">{self._repr_svg_()}</div>'
@@ -214,8 +220,7 @@ class StateMachine(metaclass=StateMachineMetaclass):
         This is a low level API, that can be used to assign any valid state value
         completely bypassing all the hooks and validations.
         """
-        value = getattr(self.model, self.state_field, None)
-        return value
+        return getattr(self.model, self.state_field, None)
 
     @current_state_value.setter
     def current_state_value(self, value):
@@ -231,11 +236,23 @@ class StateMachine(metaclass=StateMachineMetaclass):
         completely bypassing all the hooks and validations.
         """
 
-        state: State = self.states_map[self.current_state_value].for_instance(
-            machine=self,
-            cache=self._states_for_instance,
-        )
-        return state
+        try:
+            state: State = self.states_map[self.current_state_value].for_instance(
+                machine=self,
+                cache=self._states_for_instance,
+            )
+            return state
+        except KeyError as err:
+            if self.current_state_value is None:
+                raise InvalidStateValue(
+                    self.current_state_value,
+                    _(
+                        "There's no current state set. In async code, "
+                        "did you activate the initial state? "
+                        "(e.g., `await sm.activate_initial_state()`)"
+                    ),
+                ) from err
+            raise InvalidStateValue(self.current_state_value) from err
 
     @current_state.setter
     def current_state(self, value):
@@ -248,12 +265,9 @@ class StateMachine(metaclass=StateMachineMetaclass):
     @property
     def allowed_events(self):
         """List of the current allowed events."""
-        return [
-            getattr(self, event)
-            for event in self.current_state.transitions.unique_events
-        ]
+        return [getattr(self, event) for event in self.current_state.transitions.unique_events]
 
-    def _process(self, trigger):
+    async def _process(self, trigger):
         """Process event triggers.
 
         The simplest implementation is the non-RTC (synchronous),
@@ -274,7 +288,7 @@ class StateMachine(metaclass=StateMachineMetaclass):
         """
         if not self.__rtc:
             # The machine is in "synchronous" mode
-            return trigger()
+            return await trigger()
 
         # The machine is in "queued" mode
         # Add the trigger to queue and start processing in a loop.
@@ -285,9 +299,9 @@ class StateMachine(metaclass=StateMachineMetaclass):
         if self.__processing:
             return
 
-        return self._processing_loop()
+        return await self._processing_loop()
 
-    def _processing_loop(self):
+    async def _processing_loop(self):
         """Execute the triggers in the queue in order until the queue is empty"""
         self.__processing = True
 
@@ -300,7 +314,7 @@ class StateMachine(metaclass=StateMachineMetaclass):
             while self._external_queue:
                 trigger = self._external_queue.popleft()
                 try:
-                    result = trigger()
+                    result = await trigger()
                     if first_result is sentinel:
                         first_result = result
                 except Exception:
@@ -312,20 +326,18 @@ class StateMachine(metaclass=StateMachineMetaclass):
             self.__processing = False
         return first_result if first_result is not sentinel else None
 
-    def _activate(self, event_data: EventData):
+    async def _activate(self, event_data: EventData):
         transition = event_data.transition
         source = event_data.state
         target = transition.target
 
-        result = self._callbacks_registry[transition.before].call(
+        result = await self._callbacks(transition.before).call(
             *event_data.args, **event_data.extended_kwargs
         )
         if source is not None and not transition.internal:
-            self._callbacks_registry[source.exit].call(
-                *event_data.args, **event_data.extended_kwargs
-            )
+            await self._callbacks(source.exit).call(*event_data.args, **event_data.extended_kwargs)
 
-        result += self._callbacks_registry[transition.on].call(
+        result += await self._callbacks(transition.on).call(
             *event_data.args, **event_data.extended_kwargs
         )
 
@@ -333,10 +345,10 @@ class StateMachine(metaclass=StateMachineMetaclass):
         event_data.state = target
 
         if not transition.internal:
-            self._callbacks_registry[target.enter].call(
+            await self._callbacks(target.enter).call(
                 *event_data.args, **event_data.extended_kwargs
             )
-        self._callbacks_registry[transition.after].call(
+        await self._callbacks(transition.after).call(
             *event_data.args, **event_data.extended_kwargs
         )
 
@@ -347,7 +359,20 @@ class StateMachine(metaclass=StateMachineMetaclass):
 
         return result
 
-    def send(self, event, *args, **kwargs):
+    def send(self, event: str, *args, **kwargs):
+        """Send an :ref:`Event` to the state machine.
+
+        This is a thin wrapper around :meth:`async_send` to allow synchronous
+        code to send events.
+
+        .. seealso::
+
+            See: :ref:`triggering events`.
+
+        """
+        return run_async_from_sync(self.async_send(event, *args, **kwargs))
+
+    async def async_send(self, event: str, *args, **kwargs):
         """Send an :ref:`Event` to the state machine.
 
         .. seealso::
@@ -355,5 +380,8 @@ class StateMachine(metaclass=StateMachineMetaclass):
             See: :ref:`triggering events`.
 
         """
-        event = Event(event)
-        return event.trigger(self, *args, **kwargs)
+        event_instance: Event = Event(event)
+        return await event_instance.trigger(self, *args, **kwargs)
+
+    def _callbacks(self, meta_list: CallbackMetaList) -> CallbacksExecutor:
+        return self._callbacks_registry[meta_list]

statemachine/states.py

@@ -15,21 +15,23 @@ class States:
     Helps creating :ref:`StateMachine`'s :ref:`state` definitions from other
     sources, like an ``Enum`` class, using :meth:`States.from_enum`.
 
+    >>> states_def = [('open', {'initial': True}), ('closed', {'final': True})]
+
     >>> from statemachine import StateMachine
     >>> class SM(StateMachine):
     ...
     ...     states = States({
-    ...         name: State(initial=idx == 0) for idx, name in enumerate(["initial", "final"])
+    ...         name: State(**params) for name, params in states_def
     ...     })
     ...
-    ...     finish = states.initial.to(states.final)
+    ...     close = states.open.to(states.closed)
 
     And states can be used as usual.
 
     >>> sm = SM()
-    >>> sm.send("finish")
+    >>> sm.send("close")
     >>> sm.current_state.id
-    'final'
+    'closed'
 
     """