python-statemachine 2.3.1__py3-none-any.whl → 2.3.2__py3-none-any.whl

statemachine/factory.py

@@ -185,7 +185,7 @@ class StateMachineMetaclass(type):
                 cls.add_state(key, value)
             elif isinstance(value, (Transition, TransitionList)):
                 cls.add_event(key, value)
-            elif getattr(value, "_callbacks_to_update", None):
+            elif getattr(value, "_specs_to_update", None):
                 cls._add_unbounded_callback(key, value)
 
     def _add_states_from_dict(cls, states):
@@ -193,16 +193,15 @@ class StateMachineMetaclass(type):
             cls.add_state(state_id, state)
 
     def _add_unbounded_callback(cls, attr_name, func):
-        if func._is_event:
-            # if func is an event, the `attr_name` will be replaced by an event trigger,
-            # so we'll also give the ``func`` a new unique name to be used by the callback
-            # machinery.
-            cls.add_event(attr_name, func._transitions)
-            attr_name = f"_{attr_name}_{uuid4().hex}"
-            setattr(cls, attr_name, func)
-
-        for ref in func._callbacks_to_update:
-            ref(attr_name)
+        # if func is an event, the `attr_name` will be replaced by an event trigger,
+        # so we'll also give the ``func`` a new unique name to be used by the callback
+        # machinery.
+        cls.add_event(attr_name, func._transitions)
+        attr_name = f"_{attr_name}_{uuid4().hex}"
+        setattr(cls, attr_name, func)
+
+        for ref in func._specs_to_update:
+            ref(getattr(cls, attr_name), attr_name)
 
     def add_state(cls, id, state: State):
         state._set_id(id)

statemachine/mixins.py

@@ -7,15 +7,18 @@ class MachineMixin:
     ``StateMachine``.
     """
 
-    state_field_name = "state"  # type: str
+    state_field_name: str = "state"
     """The model's state field name that will hold the state value."""
 
-    state_machine_name = None  # type: str
+    state_machine_name: "str | None" = None
     """A fully qualified name of the class, where it can be imported."""
 
-    state_machine_attr = "statemachine"  # type: str
+    state_machine_attr: str = "statemachine"
     """Name of the model's attribute that will hold the machine instance."""
 
+    bind_events_as_methods: bool = False
+    """If ``True`` the state machine events triggers will be bound to the model as methods."""
+
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         if not self.state_machine_name:
@@ -23,8 +26,11 @@ class MachineMixin:
                 _("{!r} is not a valid state machine name.").format(self.state_machine_name)
             )
         machine_cls = registry.get_machine_cls(self.state_machine_name)
+        sm = machine_cls(self, state_field=self.state_field_name)
         setattr(
             self,
             self.state_machine_attr,
-            machine_cls(self, state_field=self.state_field_name),
+            sm,
         )
+        if self.bind_events_as_methods:
+            sm.bind_events_to(self)

statemachine/registry.py

@@ -1,14 +1,14 @@
 import warnings
 
+from .utils import qualname
+
 try:
-    _has_django = True
     from django.utils.module_loading import autodiscover_modules
-except ImportError:
+except ImportError:  # pragma: no cover
     # Not a django project
-    autodiscover_modules = None
-    _has_django = False
+    def autodiscover_modules(module_name: str):
+        pass
 
-from .utils import qualname
 
 _REGISTRY = {}
 _initialized = False
@@ -39,8 +39,5 @@ def init_registry():
 
 
 def load_modules(modules=None):
-    if not _has_django:
-        return
-
     for module in modules:
         autodiscover_modules(module)

statemachine/signature.py

@@ -6,6 +6,7 @@ from inspect import iscoroutinefunction
 from itertools import chain
 from types import MethodType
 from typing import Any
+from typing import Callable
 
 
 def _make_key(method):
@@ -44,7 +45,7 @@ def signature_cache(user_function):
 
 class SignatureAdapter(Signature):
     @classmethod
-    def wrap(cls, method):
+    def wrap(cls, method) -> Callable:
         """Build a wrapper that adapts the received arguments to the inner ``method`` signature"""
 
         sig = cls.from_callable(method)
@@ -54,18 +55,18 @@ class SignatureAdapter(Signature):
 
         if iscoroutinefunction(method):
 
-            async def method_wrapper(*args: Any, **kwargs: Any) -> Any:
+            async def signature_adapter(*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:
+            def signature_adapter(*args: Any, **kwargs: Any) -> Any:  # type: ignore[misc]
                 ba = sig_bind_expected(*args, **kwargs)
                 return method(*ba.args, **ba.kwargs)
 
-        method_wrapper.__name__ = metadata_to_copy.__name__
+        signature_adapter.__name__ = metadata_to_copy.__name__
 
-        return method_wrapper
+        return signature_adapter
 
     @classmethod
     @signature_cache

statemachine/state.py

@@ -3,8 +3,9 @@ from typing import Any
 from typing import Dict
 from weakref import ref
 
-from .callbacks import CallbackMetaList
+from .callbacks import CallbackGroup
 from .callbacks import CallbackPriority
+from .callbacks import CallbackSpecList
 from .exceptions import StateMachineError
 from .i18n import _
 from .transition import Transition
@@ -108,8 +109,13 @@ class State:
         self._final = final
         self._id: str = ""
         self.transitions = TransitionList()
-        self.enter = CallbackMetaList().add(enter, priority=CallbackPriority.INLINE)
-        self.exit = CallbackMetaList().add(exit, priority=CallbackPriority.INLINE)
+        self._specs = CallbackSpecList()
+        self.enter = self._specs.grouper(CallbackGroup.ENTER).add(
+            enter, priority=CallbackPriority.INLINE
+        )
+        self.exit = self._specs.grouper(CallbackGroup.EXIT).add(
+            exit, priority=CallbackPriority.INLINE
+        )
 
     def __eq__(self, other):
         return isinstance(other, State) and self.name == other.name and self.id == other.id
@@ -118,20 +124,10 @@ class State:
         return hash(repr(self))
 
     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)
-
-    def _check_callbacks(self, check):
-        check(self.enter)
-        check(self.exit)
+        self.enter.add("on_enter_state", priority=CallbackPriority.GENERIC, is_convention=True)
+        self.enter.add(f"on_enter_{self.id}", priority=CallbackPriority.NAMING, is_convention=True)
+        self.exit.add("on_exit_state", priority=CallbackPriority.GENERIC, is_convention=True)
+        self.exit.add(f"on_exit_{self.id}", priority=CallbackPriority.NAMING, is_convention=True)
 
     def __repr__(self):
         return (

statemachine/statemachine.py

@@ -1,20 +1,24 @@
+import warnings
 from collections import deque
 from copy import deepcopy
 from functools import partial
+from inspect import isawaitable
+from threading import Lock
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import Dict
+from typing import List
 
 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
+from .dispatcher import Listener
+from .dispatcher import Listeners
+from .engines.async_ import AsyncEngine
+from .engines.sync import SyncEngine
 from .event import Event
-from .event_data import EventData
 from .event_data import TriggerData
 from .exceptions import InvalidDefinition
 from .exceptions import InvalidStateValue
@@ -22,7 +26,6 @@ from .exceptions import TransitionNotAllowed
 from .factory import StateMachineMetaclass
 from .i18n import _
 from .model import Model
-from .transition import Transition
 
 if TYPE_CHECKING:
     from .state import State
@@ -49,6 +52,9 @@ class StateMachine(metaclass=StateMachineMetaclass):
             :ref:`transition`, including tolerance to unknown :ref:`event` triggers.
             Default: ``False``.
 
+        listeners: An optional list of objects that provies attributes to be used as callbacks.
+            See :ref:`listeners` for more details.
+
     """
 
     TransitionNotAllowed = TransitionNotAllowed
@@ -69,28 +75,50 @@ class StateMachine(metaclass=StateMachineMetaclass):
         start_value: Any = None,
         rtc: bool = True,
         allow_event_without_transition: bool = False,
+        listeners: "List[object] | None" = None,
     ):
         self.model = model if model else Model()
         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._observers: Dict[Any, Any] = {}
+
+        self._listeners: Dict[Any, Any] = {}
+        """Listeners that provides attributes to be used as callbacks."""
 
         if self._abstract:
             raise InvalidDefinition(_("There are no states or transitions."))
 
-        self._register_callbacks()
+        self._register_callbacks(listeners or [])
 
         # 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())
+        if self.current_state_value is None:
+            trigger_data = TriggerData(
+                machine=self,
+                event="__initial__",
+            )
+            self._put_nonblocking(trigger_data)
+
+        self._engine = self._get_engine(rtc)
+
+    def _get_engine(self, rtc: bool):
+        if self._callbacks_registry._method_types[True] > 0:
+            return AsyncEngine(self, rtc=rtc)
+        else:
+            return SyncEngine(self, rtc=rtc)
+
+    def activate_initial_state(self):
+        result = self._engine.activate_initial_state()
+        if not isawaitable(result):
+            return result
+        return run_async_from_sync(result)
+
+    def _processing_loop(self):
+        return self._engine._processing_loop()
 
     def __init_subclass__(cls, strict_states: bool = False):
         cls._strict_states = strict_states
@@ -110,15 +138,20 @@ class StateMachine(metaclass=StateMachineMetaclass):
 
     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
+        lock = self._engine._processing
+        with lock:
+            self.__deepcopy__ = None
+            self._engine._processing = None
+            try:
+                cp = deepcopy(self, memo)
+                cp._engine._processing = Lock()
+            finally:
+                self.__deepcopy__ = deepcopy_method
+                cp.__deepcopy__ = deepcopy_method
+                self._engine._processing = lock
         cp._callbacks_registry.clear()
-        cp._register_callbacks()
-        cp.add_observer(*cp._observers.keys())
+        cp._register_callbacks([])
+        cp.add_listener(*cp._listeners.keys())
         return cp
 
     def _get_initial_state(self):
@@ -128,79 +161,75 @@ class StateMachine(metaclass=StateMachineMetaclass):
         except KeyError as err:
             raise InvalidStateValue(current_state_value) from err
 
-    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()
-
-            event_data = EventData(
-                trigger_data=TriggerData(
-                    machine=self,
-                    event=initial_transition.event,
-                ),
-                transition=initial_transition,
-            )
-            await self._activate(event_data)
+    def bind_events_to(self, *targets):
+        """Bind the state machine events to the target objects."""
+
+        for event in self.events:
+            trigger = getattr(self, event.name)
+            for target in targets:
+                if hasattr(target, event.name):
+                    warnings.warn(
+                        f"Attribute {event.name!r} already exists on {target!r}. "
+                        f"Skipping binding.",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+                    continue
+                setattr(target, event.name, trigger)
+
+    def _add_listener(self, listeners: "Listeners"):
+        register = partial(listeners.resolve, registry=self._callbacks_registry)
+        for visited in iterate_states_and_transitions(self.states):
+            register(visited._specs)
 
-    async def _ensure_is_initialized(self):
-        await self.activate_initial_state()
+        return self
 
-    def _register_callbacks(self):
-        self._add_observer(
-            (
-                ObjectConfig.from_obj(self, skip_attrs=self._protected_attrs),
-                ObjectConfig.from_obj(self.model, skip_attrs={self.state_field}),
+    def _register_callbacks(self, listeners: List[object]):
+        self._listeners.update({listener: None for listener in listeners})
+        self._add_listener(
+            Listeners.from_listeners(
+                (
+                    Listener.from_obj(self, skip_attrs=self._protected_attrs),
+                    Listener.from_obj(self.model, skip_attrs={self.state_field}),
+                    *(Listener.from_obj(listener) for listener in listeners),
+                )
             )
         )
 
         check_callbacks = self._callbacks_registry.check
         for visited in iterate_states_and_transitions(self.states):
             try:
-                visited._check_callbacks(check_callbacks)
+                check_callbacks(visited._specs)
             except Exception as err:
                 raise InvalidDefinition(
                     f"Error on {visited!s} when resolving callbacks: {err}"
                 ) from err
 
-    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
+        self._callbacks_registry.async_or_sync()
 
     def add_observer(self, *observers):
-        """Add an observer.
+        """Add a listener."""
+        warnings.warn(
+            """The `add_observer` was rebranded to `add_listener`.""",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.add_listener(*observers)
+
+    def add_listener(self, *listeners):
+        """Add a listener.
 
-        Observers are a way to generically add behavior to a :ref:`StateMachine` without changing
+        Listener are a way to generically add behavior to a :ref:`StateMachine` without changing
         its internal implementation.
 
         .. seealso::
 
-            :ref:`observers`.
+            :ref:`listeners`.
         """
-        self._observers.update({o: None for o in observers})
-        return self._add_observer(tuple(ObjectConfig.from_obj(o) for o in observers))
+        self._listeners.update({o: None for o in listeners})
+        return self._add_listener(
+            Listeners.from_listeners(Listener.from_obj(o) for o in listeners)
+        )
 
     def _repr_html_(self):
         return f'<div class="statemachine">{self._repr_svg_()}</div>'
@@ -267,97 +296,9 @@ class StateMachine(metaclass=StateMachineMetaclass):
         """List of the current allowed events."""
         return [getattr(self, event) for event in self.current_state.transitions.unique_events]
 
-    async def _process(self, trigger):
-        """Process event triggers.
-
-        The simplest implementation is the non-RTC (synchronous),
-        where the trigger will be run immediately and the result collected as the return.
-
-        .. note::
-
-            While processing the trigger, if others events are generated, they
-            will also be processed immediately, so a "nested" behavior happens.
-
-        If the machine is on ``rtc`` model (queued), the event is put on a queue, and only the
-        first event will have the result collected.
-
-        .. note::
-            While processing the queue items, if others events are generated, they
-            will be processed sequentially (and not nested).
-
-        """
-        if not self.__rtc:
-            # The machine is in "synchronous" mode
-            return await trigger()
-
-        # The machine is in "queued" mode
-        # Add the trigger to queue and start processing in a loop.
-        self._external_queue.append(trigger)
-
-        # We make sure that only the first event enters the processing critical section,
-        # next events will only be put on the queue and processed by the same loop.
-        if self.__processing:
-            return
-
-        return await self._processing_loop()
-
-    async def _processing_loop(self):
-        """Execute the triggers in the queue in order until the queue is empty"""
-        self.__processing = True
-
-        # We will collect the first result as the processing result to keep backwards compatibility
-        # so we need to use a sentinel object instead of `None` because the first result may
-        # be also `None`, and on this case the `first_result` may be overridden by another result.
-        sentinel = object()
-        first_result = sentinel
-        try:
-            while self._external_queue:
-                trigger = self._external_queue.popleft()
-                try:
-                    result = await trigger()
-                    if first_result is sentinel:
-                        first_result = result
-                except Exception:
-                    # Whe clear the queue as we don't have an expected behavior
-                    # and cannot keep processing
-                    self._external_queue.clear()
-                    raise
-        finally:
-            self.__processing = False
-        return first_result if first_result is not sentinel else None
-
-    async def _activate(self, event_data: EventData):
-        transition = event_data.transition
-        source = event_data.state
-        target = transition.target
-
-        result = await self._callbacks(transition.before).call(
-            *event_data.args, **event_data.extended_kwargs
-        )
-        if source is not None and not transition.internal:
-            await self._callbacks(source.exit).call(*event_data.args, **event_data.extended_kwargs)
-
-        result += await self._callbacks(transition.on).call(
-            *event_data.args, **event_data.extended_kwargs
-        )
-
-        self.current_state = target
-        event_data.state = target
-
-        if not transition.internal:
-            await self._callbacks(target.enter).call(
-                *event_data.args, **event_data.extended_kwargs
-            )
-        await self._callbacks(transition.after).call(
-            *event_data.args, **event_data.extended_kwargs
-        )
-
-        if len(result) == 0:
-            result = None
-        elif len(result) == 1:
-            result = result[0]
-
-        return result
+    def _put_nonblocking(self, trigger_data: TriggerData):
+        """Put the trigger on the queue without blocking the caller."""
+        self._external_queue.append(trigger_data)
 
     def send(self, event: str, *args, **kwargs):
         """Send an :ref:`Event` to the state machine.
@@ -370,9 +311,12 @@ class StateMachine(metaclass=StateMachineMetaclass):
             See: :ref:`triggering events`.
 
         """
-        return run_async_from_sync(self.async_send(event, *args, **kwargs))
+        result = self._async_send(event, *args, **kwargs)
+        if not isawaitable(result):
+            return result
+        return run_async_from_sync(result)
 
-    async def async_send(self, event: str, *args, **kwargs):
+    def _async_send(self, event: str, *args, **kwargs):
         """Send an :ref:`Event` to the state machine.
 
         .. seealso::
@@ -381,7 +325,7 @@ class StateMachine(metaclass=StateMachineMetaclass):
 
         """
         event_instance: Event = Event(event)
-        return await event_instance.trigger(self, *args, **kwargs)
+        return event_instance.trigger(self, *args, **kwargs)
 
-    def _callbacks(self, meta_list: CallbackMetaList) -> CallbacksExecutor:
-        return self._callbacks_registry[meta_list]
+    def _get_callbacks(self, key) -> CallbacksExecutor:
+        return self._callbacks_registry[key]

statemachine/states.py

@@ -54,6 +54,7 @@ class States:
         return list(self) == list(other)
 
     def __getattr__(self, name: str):
+        name = name.lower()
         if name in self._states:
             return self._states[name]
         raise AttributeError(f"{name} not found in {self.__class__.__name__}")
@@ -80,7 +81,7 @@ class States:
         return self._states.items()
 
     @classmethod
-    def from_enum(cls, enum_type: EnumType, initial: Enum, final=None):
+    def from_enum(cls, enum_type: EnumType, initial, final=None):
         """
         Creates a new instance of the ``States`` class from an enumeration.
 
@@ -124,7 +125,7 @@ class States:
         True
 
         >>> sm.current_state_value
-        2
+        <Status.completed: 2>
 
         Args:
             enum_type: An enumeration containing the states of the machine.
@@ -137,7 +138,7 @@ class States:
         final_set = set(ensure_iterable(final))
         return cls(
             {
-                e.name: State(value=e.value, initial=e is initial, final=e in final_set)
+                e.name.lower(): State(value=e, initial=e is initial, final=e in final_set)
                 for e in enum_type
             }
         )