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

{python_statemachine-2.2.0.dist-info → python_statemachine-2.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-statemachine
-Version: 2.2.0
+Version: 2.3.0
 Summary: Python Finite State Machines made easy.
 Home-page: https://github.com/fgmacedo/python-statemachine
 License: MIT
@@ -8,17 +8,18 @@ Author: Fernando Macedo
 Author-email: fgmacedo@gmail.com
 Maintainer: Fernando Macedo
 Maintainer-email: fgmacedo@gmail.com
-Requires-Python: >=3.9,<3.13
+Requires-Python: >=3.7
+Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Topic :: Software Development :: Libraries
 Provides-Extra: diagrams
 Description-Content-Type: text/markdown
@@ -26,8 +27,8 @@ Description-Content-Type: text/markdown
 # Python StateMachine
 
 [![pypi](https://img.shields.io/pypi/v/python-statemachine.svg)](https://pypi.python.org/pypi/python-statemachine)
+[![downloads total](https://static.pepy.tech/badge/python-statemachine)](https://pepy.tech/project/python-statemachine)
 [![downloads](https://img.shields.io/pypi/dm/python-statemachine.svg)](https://pypi.python.org/pypi/python-statemachine)
-[![build status](https://github.com/fgmacedo/python-statemachine/actions/workflows/python-package.yml/badge.svg?branch=develop)](https://github.com/fgmacedo/python-statemachine/actions/workflows/python-package.yml?query=branch%3Adevelop)
 [![Coverage report](https://codecov.io/gh/fgmacedo/python-statemachine/branch/develop/graph/badge.svg)](https://codecov.io/gh/fgmacedo/python-statemachine)
 [![Documentation Status](https://readthedocs.org/projects/python-statemachine/badge/?version=latest)](https://python-statemachine.readthedocs.io/en/latest/?badge=latest)
 [![GitHub commits since last release (main)](https://img.shields.io/github/commits-since/fgmacedo/python-statemachine/main/develop)](https://github.com/fgmacedo/python-statemachine/compare/main...develop)
@@ -35,33 +36,43 @@ Description-Content-Type: text/markdown
 
 Python [finite-state machines](https://en.wikipedia.org/wiki/Finite-state_machine) made easy.
 
+<div align="center">
 
-* Free software: MIT license
-* Documentation: https://python-statemachine.readthedocs.io.
-
-
-Welcome to python-statemachine, an intuitive and powerful state machine framework designed for a
-great developer experience.
-
-🚀 With StateMachine, you can easily create complex, dynamic systems with clean, readable code.
+![](https://github.com/fgmacedo/python-statemachine/blob/develop/docs/images/python-statemachine.png?raw=true)
 
-💡 Our framework makes it easy to understand and reason about the different states, events and
-transitions in your system, so you can focus on building great products.
+</div>
 
-🔒 python-statemachine also provides robust error handling and ensures that your system stays
-in a valid state at all times.
+Welcome to python-statemachine, an intuitive and powerful state machine library designed for a
+great developer experience. We provide an _pythonic_ and expressive API for implementing state
+machines in sync or asynchonous Python codebases.
 
+## Features
 
-A few reasons why you may consider using it:
+- ✨ **Basic components**: Easily define **States**, **Events**, and **Transitions** to model your logic.
+- ⚙️ **Actions and handlers**: Attach actions and handlers to states, events, and transitions to control behavior dynamically.
+- 🛡️ **Conditional transitions**: Implement **Guards** and **Validators** to conditionally control transitions, ensuring they only occur when specific conditions are met.
+- 🚀 **Full async support**: Enjoy full asynchronous support. Await events, and dispatch callbacks asynchronously for seamless integration with async codebases.
+- 🔄 **Full sync support**: Use the same state machine from synchronous codebases without any modifications.
+- 🎨 **Declarative and simple API**: Utilize a clean, elegant, and readable API to define your state machine, making it easy to maintain and understand.
+- 👀 **Observer pattern support**: Register external and generic objects to watch events and register callbacks.
+- 🔍 **Decoupled design**: Separate concerns with a decoupled "state machine" and "model" design, promoting cleaner architecture and easier maintenance.
+- ✅ **Correctness guarantees**: Ensured correctness with validations at class definition time:
+   - Ensures exactly one `initial` state.
+   - Disallows transitions from `final` states.
+   - Requires ongoing transitions for all non-final states.
+   - Guarantees all non-final states have at least one path to a final state if final states are declared.
+   - Validates the state machine graph representation has a single component.
+- 📦 **Flexible event dispatching**: Dispatch events with any extra data, making it available to all callbacks, including actions and guards.
+- 🔧 **Dependency injection**: Needed parameters are injected into callbacks.
+- 📊 **Graphical representation**: Generate and output graphical representations of state machines. Create diagrams from the command line, at runtime, or even in Jupyter notebooks.
+- 🌍 **Internationalization support**: Provides error messages in different languages, making the library accessible to a global audience.
+- 🛡️ **Robust testing**: Ensured reliability with a codebase that is 100% covered by automated tests, including all docs examples. Releases follow semantic versioning for predictable releases.
+- 🏛️ **Domain model integration**: Seamlessly integrate with domain models using Mixins.
+- 🔧 **Django integration**: Automatically discover state machines in Django applications.
 
-* 📈 python-statemachine is designed to help you build scalable,
-  maintainable systems that can handle any complexity.
-* 💪 You can easily create and manage multiple state machines within a single application.
-* 🚫 Prevents common mistakes and ensures that your system stays in a valid state at all times.
 
 
-## Getting started
-
+## Installing
 
 To install Python State Machine, run this command in your terminal:
 
@@ -73,6 +84,8 @@ our docs for more details.
 
     pip install python-statemachine[diagrams]
 
+## First example
+
 Define your state machine:
 
 ```py
@@ -90,7 +103,7 @@ Define your state machine:
 ...         | red.to(green)
 ...     )
 ...
-...     def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+...     async def before_cycle(self, event: str, source: State, target: State, message: str = ""):
 ...         message = ". " + message if message else ""
 ...         return f"Running {event} from {source.id} to {target.id}{message}"
 ...
@@ -133,7 +146,27 @@ Then start sending events to your new state machine:
 
 ```
 
-That's it. This is all an external object needs to know about your state machine: How to send events.
+You can use the exactly same state machine from an async codebase:
+
+
+```py
+>>> async def run_sm():
+...    asm = TrafficLightMachine()
+...    results = []
+...    for _i in range(4):
+...        result = await asm.send("cycle")
+...        results.append(result)
+...    return results
+
+>>> asyncio.run(run_sm())
+Don't move.
+Go ahead!
+['Running cycle from green to yellow', 'Running cycle from yellow to red', ...
+
+```
+
+
+**That's it.** This is all an external object needs to know about your state machine: How to send events.
 Ideally, all states, transitions, and actions should be kept internally and not checked externally to avoid unnecessary coupling.
 
 But if your use case needs, you can inspect state machine properties, like the current state:
@@ -220,7 +253,7 @@ callback method.
 Note how `before_cycle` was declared:
 
 ```py
-def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+async def before_cycle(self, event: str, source: State, target: State, message: str = ""):
     message = ". " + message if message else ""
     return f"Running {event} from {source.id} to {target.id}{message}"
 ```
@@ -265,6 +298,34 @@ and in diagrams:
 
 ```
 
+## Async support
+
+We support native coroutine using `asyncio`, enabling seamless integration with asynchronous code.
+There's no change on the public API of the library to work on async codebases.
+
+
+```py
+>>> class AsyncStateMachine(StateMachine):
+...     initial = State('Initial', initial=True)
+...     final = State('Final', final=True)
+...
+...     advance = initial.to(final)
+...
+...     async def on_advance(self):
+...         return 42
+
+>>> async def run_sm():
+...     sm = AsyncStateMachine()
+...     result = await sm.advance()
+...     print(f"Result is {result}")
+...     print(sm.current_state)
+
+>>> asyncio.run(run_sm())
+Result is 42
+Final
+
+```
+
 ## A more useful example
 
 A simple didactic state machine for controlling an `Order`:

python_statemachine-2.3.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+statemachine/__init__.py,sha256=Omi4-IXrTE0oLfO3oF75OqMYBI9TrbZeBzZIkt-F0rU,192
+statemachine/callbacks.py,sha256=D1mb3Ky18S1jk0-ursuJljqDv63WZShnMvMK_S1Hi9k,8846
+statemachine/contrib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/contrib/diagram.py,sha256=CTlNRtAHEzCCzRUlxkiyzJOCOp1CohihdD0_7pHrx4c,7004
+statemachine/dispatcher.py,sha256=Zizr_Qaj2BfuHu5VbbnNh1giT_pUVLe4mekHj6Ca2dk,5075
+statemachine/event.py,sha256=lfJUSvkDQTnk1COueuV--xQD4o6GeaI94Y8tTOmiS6s,2304
+statemachine/event_data.py,sha256=nxOfypngK-78A77gj4pS-oxLx9zl1S9wnSt_rTiCyZA,2257
+statemachine/events.py,sha256=rUbiTX-QGoo7zzmQMEeWeLrIVnp9zhicdRIm34CoAVI,731
+statemachine/exceptions.py,sha256=RWq1vTjajxt8CzfYCD4DfI2nrgkfCPBL0DjRDOzKkQI,1086
+statemachine/factory.py,sha256=pAfRUuO474FekxrUZkKr8NkQqQ59vOu4dRHSD8Dr9rI,7982
+statemachine/graph.py,sha256=KtwB1CYckaLjTgQD9tEeuaEzJje9q3fPVpBViW5TgSk,487
+statemachine/i18n.py,sha256=NLvGseaORmQ0G-V_J8tkjoxh_piWMOm2CI6mBQpLamc,362
+statemachine/locale/en/LC_MESSAGES/statemachine.po,sha256=zJYaV2DxrHdPngDOt1bji8-lPOZMSDjWG83Ypru5DOI,2126
+statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po,sha256=SPrt-KaCBCKQq7PoOMtyyqU1bihrw_3MPL_NbqZzTVs,3214
+statemachine/mixins.py,sha256=B8WB3EGyZpMWAQg4Nw3kUMCfswgmLCChDpOQdxR28eE,1017
+statemachine/model.py,sha256=OylI3FjMiHpYyDl9mtK1zEJMeSvemaN4giQDonpc8kI,211
+statemachine/registry.py,sha256=RnVBRS3I_6Tm2OMgXMB_ewX7zQaslqEfhXFOhbqIkG4,959
+statemachine/signature.py,sha256=aGoKxC36mTO60GGICVlyduhhB2nKVOXOOHepcBG2Uws,7809
+statemachine/state.py,sha256=bZki0DyemZa-aVAfollQCmpXxesWONzUmE28eDfqz3o,8315
+statemachine/statemachine.py,sha256=5r8vtbMFQtOq9W8UmaWBN_SIzOHkO-4JfPysHfdoB8w,13827
+statemachine/states.py,sha256=gdGemJYF9k-cifs9Tk0Pe_-1u1Lanf3l08o0t8wAMgg,4203
+statemachine/transition.py,sha256=fo6B-XlHDqU8TNrDXBSn4GStdGUrZbcfbEgtsdESmrk,5412
+statemachine/transition_list.py,sha256=DatsmMWgK0YK30Nrj-josVvlTgeGapKutzYur9-puF8,5949
+statemachine/utils.py,sha256=FVtvT1lBSP3mRrYM-wxsX2pV_NZwSDsoBW4syIpACeE,798
+python_statemachine-2.3.0.dist-info/LICENSE,sha256=zcP7TsJMqaFxuTvLRZPT7nJl3_ppjxR9Z76BE9pL5zc,1074
+python_statemachine-2.3.0.dist-info/METADATA,sha256=ubb6vnMCYaYyz486RJW5r1dKKu_emWD7Rwc4x2S7lyY,14361
+python_statemachine-2.3.0.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
+python_statemachine-2.3.0.dist-info/RECORD,,

statemachine/__init__.py

@@ -3,6 +3,6 @@ from .statemachine import StateMachine
 
 __author__ = """Fernando Macedo"""
 __email__ = "fgmacedo@gmail.com"
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 __all__ = ["StateMachine", "State"]

statemachine/callbacks.py

@@ -20,7 +20,7 @@ class CallbackPriority(IntEnum):
     AFTER = 40
 
 
-def allways_true(*args, **kwargs):
+async def allways_true(*args, **kwargs):
     return True
 
 
@@ -46,8 +46,8 @@ class CallbackWrapper:
     def __lt__(self, other):
         return self.meta.priority < other.meta.priority
 
-    def __call__(self, *args, **kwargs):
-        return self._callback(*args, **kwargs)
+    async def __call__(self, *args, **kwargs):
+        return await self._callback(*args, **kwargs)
 
 
 class CallbackMeta:
@@ -137,8 +137,8 @@ class BoolCallbackMeta(CallbackMeta):
         return name if self.expected_value else f"!{name}"
 
     def _wrap_callable(self, func, expected_value):
-        def bool_wrapper(*args, **kwargs):
-            return bool(func(*args, **kwargs)) == expected_value
+        async def bool_wrapper(*args, **kwargs):
+            return bool(await func(*args, **kwargs)) == expected_value
 
         return bool_wrapper
 
@@ -248,13 +248,18 @@ class CallbacksExecutor:
             self._add(item, resolver)
         return self
 
-    def call(self, *args, **kwargs):
+    async def call(self, *args, **kwargs):
         return [
-            callback(*args, **kwargs) for callback in self if callback.condition(*args, **kwargs)
+            await callback(*args, **kwargs)
+            for callback in self
+            if await callback.condition(*args, **kwargs)
         ]
 
-    def all(self, *args, **kwargs):
-        return all(condition(*args, **kwargs) for condition in self)
+    async def all(self, *args, **kwargs):
+        for condition in self:
+            if not await condition(*args, **kwargs):
+                return False
+        return True
 
 
 class CallbacksRegistry:

statemachine/dispatcher.py

@@ -2,6 +2,7 @@ from collections import namedtuple
 from operator import attrgetter
 from typing import Any
 from typing import Generator
+from typing import Tuple
 
 from .signature import SignatureAdapter
 
@@ -15,7 +16,7 @@ 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:
@@ -35,11 +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)
+        return await self._cache(*args, **kwds)
 
 
 class CallableSearchResult(WrapSearchResult):
@@ -62,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
@@ -76,15 +77,15 @@ 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_is_property(
-    attr, configs: tuple[ObjectConfig]
+    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
@@ -96,7 +97,7 @@ def _search_callable_attr_is_property(
     return None
 
 
-def _search_callable_attr_is_callable(attr, configs: tuple[ObjectConfig]) -> WrapSearchResult:
+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__"):
@@ -109,7 +110,7 @@ def _search_callable_attr_is_callable(attr, configs: tuple[ObjectConfig]) -> Wra
 
 
 def _search_callable_in_configs(
-    attr, configs: tuple[ObjectConfig]
+    attr, configs: Tuple[ObjectConfig, ...]
 ) -> Generator[WrapSearchResult, None, None]:
     for obj, skip_attrs, resolver_id in configs:
         if attr in skip_attrs:
@@ -128,7 +129,9 @@ def _search_callable_in_configs(
         yield CallableSearchResult(attr, func, resolver_id)
 
 
-def search_callable(attr, configs: tuple) -> Generator[WrapSearchResult, None, None]:  # noqa: C901
+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:
@@ -142,15 +145,15 @@ def search_callable(attr, configs: tuple) -> Generator[WrapSearchResult, None, N
     yield from _search_callable_in_configs(attr, configs)
 
 
-def resolver_factory(objects: tuple[ObjectConfig]):
+def resolver_factory(objects: Tuple[ObjectConfig, ...]):
     """Factory that returns a configured resolver."""
 
-    def wrapper(attr) -> Generator[WrapSearchResult, None, None]:
+    def resolver(attr) -> Generator[WrapSearchResult, None, None]:
         yield from search_callable(attr, objects)
 
-    return wrapper
+    return resolver
 
 
-def resolver_factory_from_objects(*objects: tuple[Any]):
-    configs = tuple(ObjectConfig.from_obj(o) for o in objects)
+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

@@ -222,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/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()`)"

statemachine/signature.py

@@ -1,8 +1,9 @@
-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
 
@@ -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__
 
@@ -160,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/statemachine.py

@@ -6,6 +6,7 @@ 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
@@ -73,18 +74,23 @@ 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] = {}
 
         if self._abstract:
             raise InvalidDefinition(_("There are no states or transitions."))
 
         self._register_callbacks()
-        self._activate_initial_state()
+
+        # 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
@@ -122,7 +128,23 @@ class StateMachine(metaclass=StateMachineMetaclass):
         except KeyError as err:
             raise InvalidStateValue(current_state_value) from err
 
-    def _activate_initial_state(self):
+    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
@@ -138,7 +160,10 @@ class StateMachine(metaclass=StateMachineMetaclass):
                 ),
                 transition=initial_transition,
             )
-            self._activate(event_data)
+            await self._activate(event_data)
+
+    async def _ensure_is_initialized(self):
+        await self.activate_initial_state()
 
     def _register_callbacks(self):
         self._add_observer(
@@ -195,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):
@@ -212,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):
@@ -231,7 +267,7 @@ class StateMachine(metaclass=StateMachineMetaclass):
         """List of the current allowed 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),
@@ -252,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.
@@ -263,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
 
@@ -278,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:
@@ -290,18 +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(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(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(transition.on).call(
+        result += await self._callbacks(transition.on).call(
             *event_data.args, **event_data.extended_kwargs
         )
 
@@ -309,8 +345,12 @@ class StateMachine(metaclass=StateMachineMetaclass):
         event_data.state = target
 
         if not transition.internal:
-            self._callbacks(target.enter).call(*event_data.args, **event_data.extended_kwargs)
-        self._callbacks(transition.after).call(*event_data.args, **event_data.extended_kwargs)
+            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
@@ -319,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::
@@ -327,8 +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/transition.py

@@ -139,13 +139,13 @@ class Transition:
     def add_event(self, value):
         self._events.add(value)
 
-    def execute(self, event_data: "EventData"):
+    async def execute(self, event_data: "EventData"):
         machine = event_data.machine
         args, kwargs = event_data.args, event_data.extended_kwargs
-        machine._callbacks_registry[self.validators].call(*args, **kwargs)
-        if not machine._callbacks_registry[self.cond].all(*args, **kwargs):
+        await machine._callbacks_registry[self.validators].call(*args, **kwargs)
+        if not await machine._callbacks_registry[self.cond].all(*args, **kwargs):
             return False
 
-        result = machine._activate(event_data)
+        result = await machine._activate(event_data)
         event_data.result = result
         return True

statemachine/utils.py

@@ -1,3 +1,6 @@
+import asyncio
+
+
 def qualname(cls):
     """
     Returns a fully qualified name of the class, to avoid name collisions.
@@ -16,3 +19,15 @@ def ensure_iterable(obj):
         return iter(obj)
     except TypeError:
         return [obj]
+
+
+def run_async_from_sync(coroutine):
+    """
+    Run an async coroutine from a synchronous context.
+    """
+    try:
+        loop = asyncio.get_running_loop()
+        return asyncio.ensure_future(coroutine)
+    except RuntimeError:
+        loop = asyncio.get_event_loop()
+        return loop.run_until_complete(coroutine)

python_statemachine-2.2.0.dist-info/RECORD

@@ -1,28 +0,0 @@
-statemachine/__init__.py,sha256=nhqSQwRfWBVrcn4h-aLlxLbzeSsjt6lE_SSFnFWK0FY,192
-statemachine/callbacks.py,sha256=QMh564YuNVNV74VxlIyvlF_eW6njsmV9VHauQH9JR1U,8704
-statemachine/contrib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-statemachine/contrib/diagram.py,sha256=CTlNRtAHEzCCzRUlxkiyzJOCOp1CohihdD0_7pHrx4c,7004
-statemachine/dispatcher.py,sha256=i9ChhdomQpVbTg9vNS3xoCHUAw3Z32B0UPzK47nb1-A,4924
-statemachine/event.py,sha256=fvWxyFcrbPVxNW94p66rGJ5I1UZUK9mDJz68udkz2JI,2106
-statemachine/event_data.py,sha256=nxOfypngK-78A77gj4pS-oxLx9zl1S9wnSt_rTiCyZA,2257
-statemachine/events.py,sha256=rUbiTX-QGoo7zzmQMEeWeLrIVnp9zhicdRIm34CoAVI,731
-statemachine/exceptions.py,sha256=uzvDbHkzCZkmFI_02L0yC9gd6d0SBn9GmsI8ekc0Hjk,952
-statemachine/factory.py,sha256=m2TeJ19eDIymoGADDp0G0ItrrcCRgIJoJYFJ5lzqmWE,8015
-statemachine/graph.py,sha256=KtwB1CYckaLjTgQD9tEeuaEzJje9q3fPVpBViW5TgSk,487
-statemachine/i18n.py,sha256=NLvGseaORmQ0G-V_J8tkjoxh_piWMOm2CI6mBQpLamc,362
-statemachine/locale/en/LC_MESSAGES/statemachine.po,sha256=MfODCwzML6DzhOpHbno2Pdhsb26AWboR5Ka1JCNvJIA,1685
-statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po,sha256=KsR9rlnhw17EZG-IbVx3F0wJAJSK0B-OByGmUmDHDUM,2375
-statemachine/mixins.py,sha256=B8WB3EGyZpMWAQg4Nw3kUMCfswgmLCChDpOQdxR28eE,1017
-statemachine/model.py,sha256=OylI3FjMiHpYyDl9mtK1zEJMeSvemaN4giQDonpc8kI,211
-statemachine/registry.py,sha256=RnVBRS3I_6Tm2OMgXMB_ewX7zQaslqEfhXFOhbqIkG4,959
-statemachine/signature.py,sha256=9KItptchQlP2VpNmBiIFXLNAWNWY3Bs_ymUd7OOgDD4,7507
-statemachine/state.py,sha256=bZki0DyemZa-aVAfollQCmpXxesWONzUmE28eDfqz3o,8315
-statemachine/statemachine.py,sha256=U0rLIUhvsCivth1uNb0pt2xWVUnDbzhXF982yJH-bg0,11659
-statemachine/states.py,sha256=gdGemJYF9k-cifs9Tk0Pe_-1u1Lanf3l08o0t8wAMgg,4203
-statemachine/transition.py,sha256=ebRhJsjOoLya7oYZVjRAKvjq1EsC9ImpExgHANekVMA,5388
-statemachine/transition_list.py,sha256=DatsmMWgK0YK30Nrj-josVvlTgeGapKutzYur9-puF8,5949
-statemachine/utils.py,sha256=fV-Hz1gnyl4tAs9nPr2u9I9zfxq62mokPV8mUpIJc1k,458
-python_statemachine-2.2.0.dist-info/LICENSE,sha256=zcP7TsJMqaFxuTvLRZPT7nJl3_ppjxR9Z76BE9pL5zc,1074
-python_statemachine-2.2.0.dist-info/METADATA,sha256=qH4SxonFNJStkKVocZABu-RLiYD54DcON2gNGjBPGGQ,11454
-python_statemachine-2.2.0.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
-python_statemachine-2.2.0.dist-info/RECORD,,