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

statemachine/dispatcher.py

@@ -1,6 +1,8 @@
 from collections import namedtuple
 from operator import attrgetter
 from typing import Any
+from typing import Generator
+from typing import Tuple
 
 from .signature import SignatureAdapter
 
@@ -14,21 +16,14 @@ class ObjectConfig(namedtuple("ObjectConfig", "obj skip_attrs resolver_id")):
     """
 
     @classmethod
-    def from_obj(cls, obj, skip_attrs=None):
+    def from_obj(cls, obj, skip_attrs=None) -> "ObjectConfig":
         if isinstance(obj, ObjectConfig):
             return obj
         else:
-            return cls(obj, set(skip_attrs) if skip_attrs else set(), str(id(obj)))
-
-    def getattr(self, attr):
-        if attr in self.skip_attrs:
-            return
-        return getattr(self.obj, attr, None)
+            return cls(obj, skip_attrs or set(), str(id(obj)))
 
 
 class WrapSearchResult:
-    is_empty = False
-
     def __init__(self, attribute, resolver_id) -> None:
         self.attribute = attribute
         self.resolver_id = resolver_id
@@ -41,15 +36,11 @@ class WrapSearchResult:
     def wrap(self):  # pragma: no cover
         pass
 
-    def __call__(self, *args: Any, **kwds: Any) -> Any:
+    async def __call__(self, *args: Any, **kwds: Any) -> Any:
         if self._cache is None:
             self._cache = self.wrap()
         assert self._cache
-        return self._cache(*args, **kwds)
-
-
-class EmptyWrapSearchResult(WrapSearchResult):
-    is_empty = True
+        return await self._cache(*args, **kwds)
 
 
 class CallableSearchResult(WrapSearchResult):
@@ -72,7 +63,7 @@ class AttributeCallableSearchResult(WrapSearchResult):
         # we'll build a method that get's the fresh value for each call
         getter = attrgetter(self.attribute)
 
-        def wrapper(*args, **kwargs):
+        async def wrapper(*args, **kwargs):
             return getter(self.obj)
 
         return wrapper
@@ -86,39 +77,83 @@ class EventSearchResult(WrapSearchResult):
     def wrap(self):
         "Events already have the 'machine' parameter defined."
 
-        def wrapper(*args, **kwargs):
+        async def wrapper(*args, **kwargs):
             kwargs.pop("machine", None)
-            return self.func(*args, **kwargs)
+            return await self.func(*args, **kwargs)
 
         return wrapper
 
 
-def search_callable(attr, *configs) -> WrapSearchResult:
-    if callable(attr) or isinstance(attr, property):
-        return CallableSearchResult(attr, attr, None)
+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)
 
-    for config in configs:
-        func = config.getattr(attr)
-        if func is not None:
-            if not callable(func):
-                return AttributeCallableSearchResult(
-                    attr, config.obj, config.resolver_id
-                )
 
-            if getattr(func, "_is_sm_event", False):
-                return EventSearchResult(attr, func, config.resolver_id)
+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
 
-            return CallableSearchResult(attr, func, config.resolver_id)
+        if not hasattr(obj, attr):
+            continue
 
-    return EmptyWrapSearchResult(attr, None)
+        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)
 
-def resolver_factory(*objects):
+        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."""
 
-    objects = [ObjectConfig.from_obj(obj) for obj in objects]
+    def resolver(attr) -> Generator[WrapSearchResult, None, None]:
+        yield from search_callable(attr, objects)
+
+    return resolver
 
-    def wrapper(attr):
-        return search_callable(attr, *objects)
 
-    return wrapper
+def resolver_factory_from_objects(*objects: Tuple[Any, ...]):
+    configs: Tuple[ObjectConfig, ...] = tuple(ObjectConfig.from_obj(o) for o in objects)
+    return resolver_factory(configs)

statemachine/event.py

@@ -1,5 +1,8 @@
+from functools import partial
 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
@@ -15,28 +18,28 @@ class Event:
     def __repr__(self):
         return f"{type(self).__name__}({self.name!r})"
 
-    def trigger(self, machine: "StateMachine", *args, **kwargs):
-        def trigger_wrapper():
-            """Wrapper that captures event_data as closure."""
-            trigger_data = TriggerData(
-                machine=machine,
-                event=self.name,
-                args=args,
-                kwargs=kwargs,
-            )
-            return self._trigger(trigger_data)
+    async 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 machine._process(trigger_wrapper)
+        return await machine._process(trigger_wrapper)
 
-    def _trigger(self, trigger_data: TriggerData):
+    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 transition.execute(event_data):
+            if await transition.execute(event_data):
                 event_data.executed = True
                 break
         else:
@@ -46,17 +49,15 @@ class Event:
         return event_data.result if event_data else None
 
 
-def trigger_event_factory(event):
+def trigger_event_factory(event_instance: Event):
     """Build a method that sends specific `event` to the machine"""
-    event_instance = Event(event)
 
     def trigger_event(self, *args, **kwargs):
-        return event_instance.trigger(self, *args, **kwargs)
-
-    trigger_event.name = event
-    trigger_event.identifier = event
-    trigger_event._is_sm_event = True
+        return run_async_from_sync(event_instance.trigger(self, *args, **kwargs))
 
+    trigger_event.name = event_instance.name  # type: ignore[attr-defined]
+    trigger_event.identifier = event_instance.name  # type: ignore[attr-defined]
+    trigger_event._is_sm_event = True  # type: ignore[attr-defined]
     return trigger_event
 
 

statemachine/exceptions.py

@@ -1,5 +1,10 @@
+from typing import TYPE_CHECKING
+
 from .i18n import _
 
+if TYPE_CHECKING:
+    from .state import State
+
 
 class StateMachineError(Exception):
     "Base exception for this project, all exceptions that can be raised inherit from this class."
@@ -12,9 +17,10 @@ class InvalidDefinition(StateMachineError):
 class InvalidStateValue(InvalidDefinition):
     "The current model state value is not mapped to a state definition."
 
-    def __init__(self, value):
+    def __init__(self, value, msg=None):
         self.value = value
-        msg = _("{!r} is not a valid state value.").format(value)
+        if msg is None:
+            msg = _("{!r} is not a valid state value.").format(value)
         super().__init__(msg)
 
 
@@ -25,7 +31,7 @@ class AttrNotFound(InvalidDefinition):
 class TransitionNotAllowed(StateMachineError):
     "Raised when there's no transition that can run from the current :ref:`state`."
 
-    def __init__(self, event, state):
+    def __init__(self, event: str, state: "State"):
         self.event = event
         self.state = state
         msg = _("Can't {} when in {}.").format(self.event, self.state.name)

statemachine/factory.py

@@ -1,3 +1,4 @@
+import warnings
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import Dict
@@ -9,6 +10,7 @@ from . import registry
 from .event import Event
 from .event import trigger_event_factory
 from .exceptions import InvalidDefinition
+from .graph import iterate_states_and_transitions
 from .graph import visit_connected_states
 from .i18n import _
 from .state import State
@@ -18,7 +20,15 @@ from .transition_list import TransitionList
 
 
 class StateMachineMetaclass(type):
-    def __init__(cls, name: str, bases: Tuple[type], attrs: Dict[str, Any]):
+    "Metaclass for constructing StateMachine classes"
+
+    def __init__(
+        cls,
+        name: str,
+        bases: Tuple[type],
+        attrs: Dict[str, Any],
+        strict_states: bool = False,
+    ) -> None:
         super().__init__(name, bases, attrs)
         registry.register(cls)
         cls.name = cls.__name__
@@ -27,7 +37,9 @@ class StateMachineMetaclass(type):
         """Map of ``state.value`` to the corresponding :ref:`state`."""
 
         cls._abstract = True
+        cls._strict_states = strict_states
         cls._events: Dict[str, Event] = {}
+        cls._protected_attrs: set = set()
 
         cls.add_inherited(bases)
         cls.add_from_attributes(attrs)
@@ -40,12 +52,12 @@ class StateMachineMetaclass(type):
         cls.final_states: List[State] = [state for state in cls.states if state.final]
 
         cls._check()
+        cls._setup()
 
     if TYPE_CHECKING:
         """Makes mypy happy with dynamic created attributes"""
 
-        def __getattr__(self, attribute: str) -> Any:
-            ...
+        def __getattr__(self, attribute: str) -> Any: ...
 
     def _check(cls):
         has_states = bool(cls.states)
@@ -66,6 +78,8 @@ class StateMachineMetaclass(type):
         cls._check_initial_state()
         cls._check_final_states()
         cls._check_disconnected_state()
+        cls._check_trap_states()
+        cls._check_reachable_final_states()
 
     def _check_initial_state(cls):
         initials = [s for s in cls.states if s.initial]
@@ -73,7 +87,7 @@ class StateMachineMetaclass(type):
             raise InvalidDefinition(
                 _(
                     "There should be one and only one initial state. "
-                    "Your currently have these: {!r}"
+                    "You currently have these: {!r}"
                 ).format([s.id for s in initials])
             )
 
@@ -84,11 +98,44 @@ class StateMachineMetaclass(type):
 
         if final_state_with_invalid_transitions:
             raise InvalidDefinition(
-                _(
-                    "Cannot declare transitions from final state. Invalid state(s): {}"
-                ).format([s.id for s in final_state_with_invalid_transitions])
+                _("Cannot declare transitions from final state. Invalid state(s): {}").format(
+                    [s.id for s in final_state_with_invalid_transitions]
+                )
             )
 
+    def _check_trap_states(cls):
+        trap_states = [s for s in cls.states if not s.final and not s.transitions]
+        if trap_states:
+            message = _(
+                "All non-final states should have at least one outgoing transition. "
+                "These states have no outgoing transition: {!r}"
+            ).format([s.id for s in trap_states])
+            if cls._strict_states:
+                raise InvalidDefinition(message)
+            else:
+                warnings.warn(message, UserWarning, stacklevel=4)
+
+    def _check_reachable_final_states(cls):
+        if not any(s.final for s in cls.states):
+            return  # No need to check final reachability
+        disconnected_states = cls._states_without_path_to_final_states()
+        if disconnected_states:
+            message = _(
+                "All non-final states should have at least one path to a final state. "
+                "These states have no path to a final state: {!r}"
+            ).format([s.id for s in disconnected_states])
+            if cls._strict_states:
+                raise InvalidDefinition(message)
+            else:
+                warnings.warn(message, UserWarning, stacklevel=1)
+
+    def _states_without_path_to_final_states(cls):
+        return [
+            state
+            for state in cls.states
+            if not state.final and not any(s.final for s in visit_connected_states(state))
+        ]
+
     def _disconnected_states(cls, starting_state):
         visitable_states = set(visit_connected_states(starting_state))
         return set(cls.states) - visitable_states
@@ -104,6 +151,23 @@ class StateMachineMetaclass(type):
                 ).format([s.id for s in disconnected_states])
             )
 
+    def _setup(cls):
+        for visited in iterate_states_and_transitions(cls.states):
+            visited._setup()
+
+        cls._protected_attrs = {
+            "_abstract",
+            "model",
+            "state_field",
+            "start_value",
+            "initial_state",
+            "final_states",
+            "states",
+            "_events",
+            "states_map",
+            "send",
+        } | {s.id for s in cls.states}
+
     def add_inherited(cls, bases):
         for base in bases:
             for state in getattr(base, "states", []):
@@ -158,8 +222,7 @@ class StateMachineMetaclass(type):
         if event not in cls._events:
             event_instance = Event(event)
             cls._events[event] = event_instance
-            event_trigger = trigger_event_factory(event)
-            setattr(cls, event, event_trigger)
+            setattr(cls, event, trigger_event_factory(event_instance))
 
         return cls._events[event]
 

statemachine/graph.py

@@ -12,3 +12,9 @@ def visit_connected_states(state):
         already_visited.add(state)
         yield state
         visit.extend(t.target for t in state.transitions)
+
+
+def iterate_states_and_transitions(states):
+    for state in states:
+        yield state
+        yield from state.transitions

statemachine/locale/en/LC_MESSAGES/statemachine.po

@@ -1,66 +1,80 @@
 # This file is distributed under the same license as the PROJECT project.
-# Fernando Macedo <fgmacedo@gmail.com>, 2023.
+# Fernando Macedo <fgmacedo@gmail.com>, 2024.
 #
 msgid ""
 msgstr ""
-"Project-Id-Version: 2.1.0\n"
+"Project-Id-Version: 2.3.0\n"
 "Report-Msgid-Bugs-To: fgmacedo@gmail.com\n"
 "POT-Creation-Date: 2023-03-04 16:10-0300\n"
-"PO-Revision-Date: 2023-03-04 16:10-0300\n"
+"PO-Revision-Date: 2024-06-07 17:41-0300\n"
 "Last-Translator: Fernando Macedo <fgmacedo@gmail.com>\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 "Generated-By: Babel 2.12.1\n"
 
-#: statemachine/callbacks.py:56
-msgid "Callback {!r} not property configured."
-msgstr ""
-
-#: statemachine/dispatcher.py:35
+#: statemachine/callbacks.py:289
 msgid "Did not found name '{}' from model or statemachine"
 msgstr ""
 
-#: statemachine/exceptions.py:17
+#: statemachine/exceptions.py:23
 msgid "{!r} is not a valid state value."
 msgstr ""
 
-#: statemachine/exceptions.py:31
+#: statemachine/exceptions.py:37
 msgid "Can't {} when in {}."
 msgstr ""
 
-#: statemachine/factory.py:35
-msgid ""
-"There should be one and only one initial state. Your currently have "
-"these: {!r}"
+#: statemachine/factory.py:73
+msgid "There are no states."
+msgstr ""
+
+#: statemachine/factory.py:76
+msgid "There are no events."
 msgstr ""
 
-#: statemachine/factory.py:51
+#: statemachine/factory.py:88
 msgid ""
-"There are unreachable states. The statemachine graph should have a single"
-" component. Disconnected states: {}"
+"There should be one and only one initial state. You currently have these:"
+" {!r}"
 msgstr ""
 
-#: statemachine/factory.py:69
-msgid "There are no states."
+#: statemachine/factory.py:101
+msgid "Cannot declare transitions from final state. Invalid state(s): {}"
 msgstr ""
 
-#: statemachine/factory.py:72
-msgid "There are no events."
+#: statemachine/factory.py:109
+msgid ""
+"All non-final states should have at least one outgoing transition. These "
+"states have no outgoing transition: {!r}"
 msgstr ""
 
-#: statemachine/factory.py:82
-msgid "Cannot declare transitions from final state. Invalid state(s): {}"
+#: statemachine/factory.py:123
+msgid ""
+"All non-final states should have at least one path to a final state. "
+"These states have no path to a final state: {!r}"
 msgstr ""
 
-#: statemachine/mixins.py:30
+#: statemachine/factory.py:147
+msgid ""
+"There are unreachable states. The statemachine graph should have a single"
+" component. Disconnected states: {}"
+msgstr ""
+
+#: statemachine/mixins.py:23
 msgid "{!r} is not a valid state machine name."
 msgstr ""
 
-#: statemachine/state.py:148
+#: statemachine/state.py:152
 msgid "State overriding is not allowed. Trying to add '{}' to {}"
 msgstr ""
 
-#: statemachine/statemachine.py:48
+#: statemachine/statemachine.py:86
 msgid "There are no states or transitions."
 msgstr ""
+
+#: statemachine/statemachine.py:249
+msgid ""
+"There's no current state set. In async code, did you activate the initial"
+" state? (e.g., `await sm.activate_initial_state()`)"
+msgstr ""

statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po

@@ -1,70 +1,91 @@
-# This file is distributed under the same license as the PROJECT project.
-# Fernando Macedo <fgmacedo@gmail.com>, 2023.
+# This file is distributed under the same license as the  project.
+# Fernando Macedo <fgmacedo@gmail.com>, 2024.
 #
 msgid ""
 msgstr ""
-"Project-Id-Version: 2.1.0\n"
+"Project-Id-Version:  2.3.0\n"
 "Report-Msgid-Bugs-To: fgmacedo@gmail.com\n"
 "POT-Creation-Date: 2023-03-04 16:10-0300\n"
-"PO-Revision-Date: 2023-03-04 16:10-0300\n"
+"PO-Revision-Date: 2024-06-07 17:41-0300\n"
 "Last-Translator: Fernando Macedo <fgmacedo@gmail.com>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
 "Content-Transfer-Encoding: 8bit\n"
-"Generated-By: Babel 2.12.1\n"
+"Generated-By: Babel 2.14.0\n"
 
-#: statemachine/callbacks.py:56
-msgid "Callback {!r} not property configured."
-msgstr "Callback {!r} não está configurado corretamente."
-
-#: statemachine/dispatcher.py:35
+#: statemachine/callbacks.py:289
 msgid "Did not found name '{}' from model or statemachine"
-msgstr "Não foi encontrado o nome '{}' no modelo ou na máquina de estados"
+msgstr "Não encontrou o nome '{}' no modelo ou na máquina de estados"
 
-#: statemachine/exceptions.py:17
+#: statemachine/exceptions.py:23
 msgid "{!r} is not a valid state value."
 msgstr "{!r} não é um valor de estado válido."
 
-#: statemachine/exceptions.py:31
+#: statemachine/exceptions.py:37
 msgid "Can't {} when in {}."
-msgstr "Não é possível {} quando em {}."
-
-#: statemachine/factory.py:35
-msgid ""
-"There should be one and only one initial state. Your currently have "
-"these: {!r}"
-msgstr ""
-"Deve haver um e apenas um estado inicial. Atualmente, você tem "
-"os seguintes: {!r}"
+msgstr "Não é possível {} quando está em {}."
 
-#: statemachine/factory.py:51
-msgid ""
-"There are unreachable states. The statemachine graph should have a single"
-" component. Disconnected states: {}"
-msgstr ""
-"Há estados inalcançáveis. O grafo da máquina de estados deve ter apenas um"
-" componente. Estados desconectados: {}"
-
-#: statemachine/factory.py:69
+#: statemachine/factory.py:73
 msgid "There are no states."
 msgstr "Não há estados."
 
-#: statemachine/factory.py:72
+#: statemachine/factory.py:76
 msgid "There are no events."
 msgstr "Não há eventos."
 
-#: statemachine/factory.py:82
+#: statemachine/factory.py:88
+msgid ""
+"There should be one and only one initial state. You currently have these:"
+" {!r}"
+msgstr "Deve haver um e apenas um estado inicial. Você atualmente tem estes: {!r}"
+
+#: statemachine/factory.py:101
 msgid "Cannot declare transitions from final state. Invalid state(s): {}"
-msgstr "Não é possível declarar transições a partir do estado final. Estado(s) inválido(s): {}"
+msgstr ""
+"Não é possível declarar transições a partir do estado final. Estado(s) "
+"inválido(s): {}"
+
+#: statemachine/factory.py:109
+msgid ""
+"All non-final states should have at least one outgoing transition. These "
+"states have no outgoing transition: {!r}"
+msgstr ""
+"Todos os estados não finais devem ter pelo menos uma transição de saída. "
+"Esses estados não têm transição de saída: {!r}"
 
-#: statemachine/mixins.py:30
+#: statemachine/factory.py:123
+msgid ""
+"All non-final states should have at least one path to a final state. "
+"These states have no path to a final state: {!r}"
+msgstr ""
+"Todos os estados não finais devem ter pelo menos um caminho para um "
+"estado final. Esses estados não têm caminho para um estado final: {!r}"
+
+#: statemachine/factory.py:147
+msgid ""
+"There are unreachable states. The statemachine graph should have a single"
+" component. Disconnected states: {}"
+msgstr ""
+"Há estados inacessíveis. O gráfico da máquina de estados deve ter um "
+"único componente. Estados desconectados: {}"
+
+#: statemachine/mixins.py:23
 msgid "{!r} is not a valid state machine name."
-msgstr "{!r} não é um nome válido para a máquina de estados."
+msgstr "{!r} não é um nome válido para uma máquina de estados."
 
-#: statemachine/state.py:148
+#: statemachine/state.py:152
 msgid "State overriding is not allowed. Trying to add '{}' to {}"
-msgstr "A substituição de estado não é permitida. Tentando adicionar '{}' a {}"
+msgstr "Sobrescrever estados não é permitido. Tentando adicionar '{}' a {}"
 
-#: statemachine/statemachine.py:48
+#: statemachine/statemachine.py:86
 msgid "There are no states or transitions."
 msgstr "Não há estados ou transições."
+
+#: statemachine/statemachine.py:249
+msgid ""
+"There's no current state set. In async code, did you activate the initial"
+" state? (e.g., `await sm.activate_initial_state()`)"
+msgstr ""
+"Não há estado atual definido. No código assíncrono, você ativou o estado"
+" inicial? (por exemplo, `await sm.activate_initial_state()`)"