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

statemachine/dispatcher.py

@@ -1,159 +1,151 @@
-from collections import namedtuple
+from dataclasses import dataclass
 from operator import attrgetter
+from typing import TYPE_CHECKING
 from typing import Any
+from typing import Callable
 from typing import Generator
+from typing import Iterable
+from typing import Set
 from typing import Tuple
 
+from statemachine.callbacks import SpecReference
+
 from .signature import SignatureAdapter
 
+if TYPE_CHECKING:
+    from .callbacks import CallbackSpec
+    from .callbacks import CallbackSpecList
+
 
-class ObjectConfig(namedtuple("ObjectConfig", "obj skip_attrs resolver_id")):
-    """Configuration for objects passed to resolver_factory.
+@dataclass
+class Listener:
+    """Object reference that provides attributes to be used as callbacks.
 
     Args:
         obj: Any object that will serve as lookup for attributes.
         skip_attrs: Protected attrs that will be ignored on the search.
     """
 
+    obj: object
+    all_attrs: Set[str]
+    resolver_id: str
+
     @classmethod
-    def from_obj(cls, obj, skip_attrs=None) -> "ObjectConfig":
-        if isinstance(obj, ObjectConfig):
+    def from_obj(cls, obj, skip_attrs=None) -> "Listener":
+        if isinstance(obj, Listener):
             return obj
         else:
-            return cls(obj, skip_attrs or set(), str(id(obj)))
-
-
-class WrapSearchResult:
-    def __init__(self, attribute, resolver_id) -> None:
-        self.attribute = attribute
-        self.resolver_id = resolver_id
-        self._cache = None
-        self.unique_key = f"{attribute}@{resolver_id}"
-
-    def __repr__(self):
-        return f"{type(self).__name__}({self.unique_key})"
-
-    def wrap(self):  # pragma: no cover
-        pass
-
-    async def __call__(self, *args: Any, **kwds: Any) -> Any:
-        if self._cache is None:
-            self._cache = self.wrap()
-        assert self._cache
-        return await self._cache(*args, **kwds)
-
-
-class CallableSearchResult(WrapSearchResult):
-    def __init__(self, attribute, a_callable, resolver_id) -> None:
-        self.a_callable = a_callable
-        super().__init__(attribute, resolver_id)
-
-    def wrap(self):
-        return SignatureAdapter.wrap(self.a_callable)
-
-
-class AttributeCallableSearchResult(WrapSearchResult):
-    def __init__(self, attribute, obj, resolver_id) -> None:
-        self.obj = obj
-        super().__init__(attribute, resolver_id)
-
-    def wrap(self):
-        # if `attr` is not callable, then it's an attribute or property,
-        # so `func` contains it's current value.
-        # we'll build a method that get's the fresh value for each call
-        getter = attrgetter(self.attribute)
-
-        async def wrapper(*args, **kwargs):
-            return getter(self.obj)
-
-        return wrapper
-
-
-class EventSearchResult(WrapSearchResult):
-    def __init__(self, attribute, func, resolver_id) -> None:
-        self.func = func
-        super().__init__(attribute, resolver_id)
-
-    def wrap(self):
-        "Events already have the 'machine' parameter defined."
+            if skip_attrs is None:
+                skip_attrs = set()
+            all_attrs = set(dir(obj)) - skip_attrs
+            return cls(obj, all_attrs, str(id(obj)))
 
-        async def wrapper(*args, **kwargs):
-            kwargs.pop("machine", None)
-            return await self.func(*args, **kwargs)
 
-        return wrapper
+@dataclass
+class Listeners:
+    """Listeners that provides attributes to be used as callbacks."""
 
+    items: Tuple[Listener, ...]
+    all_attrs: Set[str]
 
-def _search_callable_attr_is_property(
-    attr, configs: Tuple[ObjectConfig, ...]
-) -> "WrapSearchResult | None":
-    # if the attr is a property, we'll try to find the object that has the
-    # property on the configs
-    attr_name = attr.fget.__name__
-    for obj, _skip_attrs, resolver_id in configs:
-        func = getattr(type(obj), attr_name, None)
-        if func is not None and func is attr:
-            return AttributeCallableSearchResult(attr_name, obj, resolver_id)
-    return None
-
-
-def _search_callable_attr_is_callable(attr, configs: Tuple[ObjectConfig, ...]) -> WrapSearchResult:
-    # if the attr is an unbounded method, we'll try to find the bounded method
-    # on the configs
-    if not hasattr(attr, "__self__"):
-        for obj, _skip_attrs, resolver_id in configs:
-            func = getattr(obj, attr.__name__, None)
-            if func is not None and func.__func__ is attr:
-                return CallableSearchResult(attr.__name__, func, resolver_id)
-
-    return CallableSearchResult(attr, attr, None)
-
-
-def _search_callable_in_configs(
-    attr, configs: Tuple[ObjectConfig, ...]
-) -> Generator[WrapSearchResult, None, None]:
-    for obj, skip_attrs, resolver_id in configs:
-        if attr in skip_attrs:
-            continue
-
-        if not hasattr(obj, attr):
-            continue
-
-        func = getattr(obj, attr)
-        if not callable(func):
-            yield AttributeCallableSearchResult(attr, obj, resolver_id)
-
-        if getattr(func, "_is_sm_event", False):
-            yield EventSearchResult(attr, func, resolver_id)
-
-        yield CallableSearchResult(attr, func, resolver_id)
-
-
-def search_callable(
-    attr, configs: Tuple[ObjectConfig, ...]
-) -> Generator[WrapSearchResult, None, None]:  # noqa: C901
-    if isinstance(attr, property):
-        result = _search_callable_attr_is_property(attr, configs)
-        if result is not None:
-            yield result
-        return
-
-    if callable(attr):
-        yield _search_callable_attr_is_callable(attr, configs)
-        return
-
-    yield from _search_callable_in_configs(attr, configs)
-
-
-def resolver_factory(objects: Tuple[ObjectConfig, ...]):
-    """Factory that returns a configured resolver."""
-
-    def resolver(attr) -> Generator[WrapSearchResult, None, None]:
-        yield from search_callable(attr, objects)
-
-    return resolver
+    @classmethod
+    def from_listeners(cls, listeners: Iterable["Listener"]) -> "Listeners":
+        listeners = tuple(listeners)
+        all_attrs = set().union(*(listener.all_attrs for listener in listeners))
+        return cls(listeners, all_attrs)
+
+    def resolve(self, specs: "CallbackSpecList", registry):
+        found_convention_specs = specs.conventional_specs & self.all_attrs
+        filtered_specs = [
+            spec for spec in specs if not spec.is_convention or spec.func in found_convention_specs
+        ]
+        if not filtered_specs:
+            return
+
+        for spec in filtered_specs:
+            registry[spec.group.build_key(specs)]._add(spec, self)
+
+    def search(self, spec: "CallbackSpec") -> Generator["Callable", None, None]:
+        if spec.reference is SpecReference.NAME:
+            yield from self._search_name(spec.func)
+            return
+        elif spec.reference is SpecReference.CALLABLE:
+            yield self._search_callable(spec)
+            return
+        elif spec.reference is SpecReference.PROPERTY:
+            result = self._search_property(spec)
+            if result is not None:
+                yield result
+            return
+        else:  # never reached here from tests but put an exception for safety. pragma: no cover
+            raise ValueError(f"Invalid reference {spec.reference}")
+
+    def _search_property(self, spec) -> "Callable | None":
+        # if the attr is a property, we'll try to find the object that has the
+        # property on the configs
+        attr_name = spec.attr_name
+        if attr_name not in self.all_attrs:
+            return None
+        for config in self.items:
+            func = getattr(type(config.obj), attr_name, None)
+            if func is not None and func is spec.func:
+                return attr_method(attr_name, config.obj, config.resolver_id)
+        return None
+
+    def _search_callable(self, spec) -> "Callable":
+        # if the attr is an unbounded method, we'll try to find the bounded method
+        # on the self
+        if not spec.is_bounded:
+            for config in self.items:
+                func = getattr(config.obj, spec.attr_name, None)
+                if func is not None and func.__func__ is spec.func:
+                    return callable_method(spec.attr_name, func, config.resolver_id)
+
+        return callable_method(spec.func, spec.func, None)
+
+    def _search_name(self, name) -> Generator["Callable", None, None]:
+        for config in self.items:
+            if name not in config.all_attrs:
+                continue
+
+            func = getattr(config.obj, name)
+            if not callable(func):
+                yield attr_method(name, config.obj, config.resolver_id)
+                continue
+
+            if getattr(func, "_is_sm_event", False):
+                yield event_method(name, func, config.resolver_id)
+                continue
+
+            yield callable_method(name, func, config.resolver_id)
+
+
+def callable_method(attribute, a_callable, resolver_id) -> Callable:
+    method = SignatureAdapter.wrap(a_callable)
+    method.unique_key = f"{attribute}@{resolver_id}"  # type: ignore[attr-defined]
+    method.__name__ = a_callable.__name__
+    method.__doc__ = a_callable.__doc__
+    return method
+
+
+def attr_method(attribute, obj, resolver_id) -> Callable:
+    getter = attrgetter(attribute)
+
+    def method(*args, **kwargs):
+        return getter(obj)
+
+    method.unique_key = f"{attribute}@{resolver_id}"  # type: ignore[attr-defined]
+    return method
+
+
+def event_method(attribute, func, resolver_id) -> Callable:
+    def method(*args, **kwargs):
+        kwargs.pop("machine", None)
+        return func(*args, **kwargs)
+
+    method.unique_key = f"{attribute}@{resolver_id}"  # type: ignore[attr-defined]
+    return method
 
 
 def resolver_factory_from_objects(*objects: Tuple[Any, ...]):
-    configs: Tuple[ObjectConfig, ...] = tuple(ObjectConfig.from_obj(o) for o in objects)
-    return resolver_factory(configs)
+    return Listeners.from_listeners(Listener.from_obj(o) for o in objects)

statemachine/engines/async_.py

@@ -0,0 +1,136 @@
+from threading import Lock
+from typing import TYPE_CHECKING
+from weakref import proxy
+
+from ..event_data import EventData
+from ..event_data import TriggerData
+from ..exceptions import InvalidDefinition
+from ..exceptions import TransitionNotAllowed
+from ..i18n import _
+from ..transition import Transition
+
+if TYPE_CHECKING:
+    from ..statemachine import StateMachine
+
+
+class AsyncEngine:
+    def __init__(self, sm: "StateMachine", rtc: bool = True):
+        self.sm = proxy(sm)
+        self._sentinel = object()
+        if not rtc:
+            raise InvalidDefinition(_("Only RTC is supported on async engine"))
+        self._processing = Lock()
+
+    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.
+        """
+        return await self._processing_loop()
+
+    async def _processing_loop(self):
+        """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).
+
+        """
+        # 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 not self._processing.acquire(blocking=False):
+            return None
+
+        # 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.
+        first_result = self._sentinel
+        try:
+            # Execute the triggers in the queue in FIFO order until the queue is empty
+            while self.sm._external_queue:
+                trigger_data = self.sm._external_queue.popleft()
+                try:
+                    result = await self._trigger(trigger_data)
+                    if first_result is self._sentinel:
+                        first_result = result
+                except Exception:
+                    # Whe clear the queue as we don't have an expected behavior
+                    # and cannot keep processing
+                    self.sm._external_queue.clear()
+                    raise
+        finally:
+            self._processing.release()
+        return first_result if first_result is not self._sentinel else None
+
+    async def _trigger(self, trigger_data: TriggerData):
+        event_data = None
+        if trigger_data.event == "__initial__":
+            transition = Transition(None, self.sm._get_initial_state(), event="__initial__")
+            transition._specs.clear()
+            event_data = EventData(trigger_data=trigger_data, transition=transition)
+            await self._activate(event_data)
+            return self._sentinel
+
+        state = self.sm.current_state
+        for transition in state.transitions:
+            if not transition.match(trigger_data.event):
+                continue
+
+            event_data = EventData(trigger_data=trigger_data, transition=transition)
+            args, kwargs = event_data.args, event_data.extended_kwargs
+            await self.sm._get_callbacks(transition.validators.key).async_call(*args, **kwargs)
+            if not await self.sm._get_callbacks(transition.cond.key).async_all(*args, **kwargs):
+                continue
+
+            result = await self._activate(event_data)
+            event_data.result = result
+            event_data.executed = True
+            break
+        else:
+            if not self.sm.allow_event_without_transition:
+                raise TransitionNotAllowed(trigger_data.event, state)
+
+        return event_data.result if event_data else None
+
+    async def _activate(self, event_data: EventData):
+        args, kwargs = event_data.args, event_data.extended_kwargs
+        transition = event_data.transition
+        source = event_data.state
+        target = transition.target
+
+        result = await self.sm._get_callbacks(transition.before.key).async_call(*args, **kwargs)
+        if source is not None and not transition.internal:
+            await self.sm._get_callbacks(source.exit.key).async_call(*args, **kwargs)
+
+        result += await self.sm._get_callbacks(transition.on.key).async_call(*args, **kwargs)
+
+        self.sm.current_state = target
+        event_data.state = target
+        kwargs["state"] = target
+
+        if not transition.internal:
+            await self.sm._get_callbacks(target.enter.key).async_call(*args, **kwargs)
+        await self.sm._get_callbacks(transition.after.key).async_call(*args, **kwargs)
+
+        if len(result) == 0:
+            result = None
+        elif len(result) == 1:
+            result = result[0]
+
+        return result

statemachine/engines/sync.py

@@ -0,0 +1,139 @@
+from threading import Lock
+from typing import TYPE_CHECKING
+from weakref import proxy
+
+from ..event_data import EventData
+from ..event_data import TriggerData
+from ..exceptions import TransitionNotAllowed
+from ..transition import Transition
+
+if TYPE_CHECKING:
+    from ..statemachine import StateMachine
+
+
+class SyncEngine:
+    def __init__(self, sm: "StateMachine", rtc: bool = True):
+        self.sm = proxy(sm)
+        self._sentinel = object()
+        self._rtc = rtc
+        self._processing = Lock()
+        self.activate_initial_state()
+
+    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.
+        """
+        return self._processing_loop()
+
+    def _processing_loop(self):
+        """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
+            trigger_data = self.sm._external_queue.popleft()
+            return self._trigger(trigger_data)
+
+        # 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 not self._processing.acquire(blocking=False):
+            return None
+
+        # 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.
+        first_result = self._sentinel
+        try:
+            # Execute the triggers in the queue in FIFO order until the queue is empty
+            while self.sm._external_queue:
+                trigger_data = self.sm._external_queue.popleft()
+                try:
+                    result = self._trigger(trigger_data)
+                    if first_result is self._sentinel:
+                        first_result = result
+                except Exception:
+                    # Whe clear the queue as we don't have an expected behavior
+                    # and cannot keep processing
+                    self.sm._external_queue.clear()
+                    raise
+        finally:
+            self._processing.release()
+        return first_result if first_result is not self._sentinel else None
+
+    def _trigger(self, trigger_data: TriggerData):
+        event_data = None
+        if trigger_data.event == "__initial__":
+            transition = Transition(None, self.sm._get_initial_state(), event="__initial__")
+            transition._specs.clear()
+            event_data = EventData(trigger_data=trigger_data, transition=transition)
+            self._activate(event_data)
+            return self._sentinel
+
+        state = self.sm.current_state
+        for transition in state.transitions:
+            if not transition.match(trigger_data.event):
+                continue
+
+            event_data = EventData(trigger_data=trigger_data, transition=transition)
+            args, kwargs = event_data.args, event_data.extended_kwargs
+            self.sm._get_callbacks(transition.validators.key).call(*args, **kwargs)
+            if not self.sm._get_callbacks(transition.cond.key).all(*args, **kwargs):
+                continue
+
+            result = self._activate(event_data)
+            event_data.result = result
+            event_data.executed = True
+            break
+        else:
+            if not self.sm.allow_event_without_transition:
+                raise TransitionNotAllowed(trigger_data.event, state)
+
+        return event_data.result if event_data else None
+
+    def _activate(self, event_data: EventData):
+        args, kwargs = event_data.args, event_data.extended_kwargs
+        transition = event_data.transition
+        source = event_data.state
+        target = transition.target
+
+        result = self.sm._get_callbacks(transition.before.key).call(*args, **kwargs)
+        if source is not None and not transition.internal:
+            self.sm._get_callbacks(source.exit.key).call(*args, **kwargs)
+
+        result += self.sm._get_callbacks(transition.on.key).call(*args, **kwargs)
+
+        self.sm.current_state = target
+        event_data.state = target
+        kwargs["state"] = target
+
+        if not transition.internal:
+            self.sm._get_callbacks(target.enter.key).call(*args, **kwargs)
+        self.sm._get_callbacks(transition.after.key).call(*args, **kwargs)
+
+        if len(result) == 0:
+            result = None
+        elif len(result) == 1:
+            result = result[0]
+
+        return result

statemachine/event.py

@@ -1,11 +1,9 @@
-from functools import partial
+from inspect import isawaitable
 from typing import TYPE_CHECKING
 
 from statemachine.utils import run_async_from_sync
 
-from .event_data import EventData
 from .event_data import TriggerData
-from .exceptions import TransitionNotAllowed
 
 if TYPE_CHECKING:
     from .statemachine import StateMachine
@@ -18,42 +16,25 @@ class Event:
     def __repr__(self):
         return f"{type(self).__name__}({self.name!r})"
 
-    async def trigger(self, machine: "StateMachine", *args, **kwargs):
+    def trigger(self, machine: "StateMachine", *args, **kwargs):
         trigger_data = TriggerData(
             machine=machine,
             event=self.name,
             args=args,
             kwargs=kwargs,
         )
-        trigger_wrapper = partial(self._trigger, trigger_data=trigger_data)
-
-        return await machine._process(trigger_wrapper)
-
-    async def _trigger(self, trigger_data: TriggerData):
-        event_data = None
-        await trigger_data.machine._ensure_is_initialized()
-
-        state = trigger_data.machine.current_state
-        for transition in state.transitions:
-            if not transition.match(trigger_data.event):
-                continue
-
-            event_data = EventData(trigger_data=trigger_data, transition=transition)
-            if await transition.execute(event_data):
-                event_data.executed = True
-                break
-        else:
-            if not trigger_data.machine.allow_event_without_transition:
-                raise TransitionNotAllowed(trigger_data.event, state)
-
-        return event_data.result if event_data else None
+        machine._put_nonblocking(trigger_data)
+        return machine._processing_loop()
 
 
 def trigger_event_factory(event_instance: Event):
     """Build a method that sends specific `event` to the machine"""
 
     def trigger_event(self, *args, **kwargs):
-        return run_async_from_sync(event_instance.trigger(self, *args, **kwargs))
+        result = event_instance.trigger(self, *args, **kwargs)
+        if not isawaitable(result):
+            return result
+        return run_async_from_sync(result)
 
     trigger_event.name = event_instance.name  # type: ignore[attr-defined]
     trigger_event.identifier = event_instance.name  # type: ignore[attr-defined]
@@ -66,7 +47,7 @@ def same_event_cond_builder(expected_event: str):
     Builds a condition method that evaluates to ``True`` when the expected event is received.
     """
 
-    def cond(event: str) -> bool:
+    def cond(*args, event: "str | None" = None, **kwargs) -> bool:
         return event == expected_event
 
     return cond

statemachine/event_data.py

@@ -47,16 +47,14 @@ class EventData:
     """The destination :ref:`State` of the :ref:`transition`."""
 
     result: "Any | None" = None
+
     executed: bool = False
 
     def __post_init__(self):
         self.state = self.transition.source
         self.source = self.transition.source
         self.target = self.transition.target
-
-    @property
-    def machine(self):
-        return self.trigger_data.machine
+        self.machine = self.trigger_data.machine
 
     @property
     def event(self):

statemachine/events.py

@@ -27,5 +27,5 @@ class Events:
 
         return self
 
-    def match(self, event):
-        return any(t == event for t in self)
+    def match(self, event: str):
+        return any(e == event for e in self)