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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-statemachine
-Version: 2.1.2
+Version: 2.3.0
 Summary: Python Finite State Machines made easy.
 Home-page: https://github.com/fgmacedo/python-statemachine
 License: MIT
@@ -8,7 +8,8 @@ Author: Fernando Macedo
 Author-email: fgmacedo@gmail.com
 Maintainer: Fernando Macedo
 Maintainer-email: fgmacedo@gmail.com
-Requires-Python: >=3.7,<3.13
+Requires-Python: >=3.7
+Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
@@ -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.
+![](https://github.com/fgmacedo/python-statemachine/blob/develop/docs/images/python-statemachine.png?raw=true)
 
+</div>
 
-Welcome to python-statemachine, an intuitive and powerful state machine framework designed for a
-great developer experience.
+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.
 
-🚀 With StateMachine, you can easily create complex, dynamic systems with clean, readable code.
+## Features
 
-💡 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.
+- ✨ **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 also provides robust error handling and ensures that your system stays
-in a valid state at all times.
 
 
-A few reasons why you may consider using it:
-
-* 📈 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.1.2"
+__version__ = "2.3.0"
 
 __all__ = ["StateMachine", "State"]

statemachine/callbacks.py

@@ -1,7 +1,10 @@
+from bisect import insort
 from collections import defaultdict
 from collections import deque
+from enum import IntEnum
 from typing import Callable
 from typing import Dict
+from typing import Generator
 from typing import List
 
 from .exceptions import AttrNotFound
@@ -9,27 +12,42 @@ from .i18n import _
 from .utils import ensure_iterable
 
 
+class CallbackPriority(IntEnum):
+    GENERIC = 0
+    INLINE = 10
+    DECORATOR = 20
+    NAMING = 30
+    AFTER = 40
+
+
+async def allways_true(*args, **kwargs):
+    return True
+
+
 class CallbackWrapper:
     def __init__(
         self,
         callback: Callable,
         condition: Callable,
+        meta: "CallbackMeta",
         unique_key: str,
-        expected_value: "bool | None" = None,
     ) -> None:
         self._callback = callback
         self.condition = condition
+        self.meta = meta
         self.unique_key = unique_key
-        self.expected_value = expected_value
 
     def __repr__(self):
         return f"{type(self).__name__}({self.unique_key})"
 
-    def __call__(self, *args, **kwargs):
-        result = self._callback(*args, **kwargs)
-        if self.expected_value is not None:
-            return bool(result) == self.expected_value
-        return result
+    def __str__(self):
+        return str(self.meta)
+
+    def __lt__(self, other):
+        return self.meta.priority < other.meta.priority
+
+    async def __call__(self, *args, **kwargs):
+        return await self._callback(*args, **kwargs)
 
 
 class CallbackMeta:
@@ -42,14 +60,22 @@ class CallbackMeta:
     call is performed, to allow the proper callback resolution.
     """
 
-    def __init__(self, func, suppress_errors=False, cond=None, expected_value=None):
+    def __init__(
+        self,
+        func,
+        suppress_errors=False,
+        cond=None,
+        priority: CallbackPriority = CallbackPriority.NAMING,
+        expected_value=None,
+    ):
         self.func = func
         self.suppress_errors = suppress_errors
-        self.cond = CallbackMetaList().add(cond)
+        self.cond = cond
         self.expected_value = expected_value
+        self.priority = priority
 
     def __repr__(self):
-        return f"{type(self).__name__}({self.func!r})"
+        return f"{type(self).__name__}({self.func!r}, suppress_errors={self.suppress_errors!r})"
 
     def __str__(self):
         return getattr(self.func, "__name__", self.func)
@@ -63,7 +89,10 @@ class CallbackMeta:
     def _update_func(self, func):
         self.func = func
 
-    def build(self, resolver) -> "CallbackWrapper | None":
+    def _wrap_callable(self, func, _expected_value):
+        return func
+
+    def build(self, resolver) -> Generator["CallbackWrapper", None, None]:
         """
         Resolves the `func` into a usable callable.
 
@@ -71,25 +100,14 @@ class CallbackMeta:
             resolver (callable): A method responsible to build and return a valid callable that
                 can receive arbitrary parameters like `*args, **kwargs`.
         """
-        callback = resolver(self.func)
-        if not callback.is_empty:
-            conditions = CallbacksExecutor()
-            conditions.add(self.cond, resolver)
-
-            return CallbackWrapper(
-                callback=callback,
-                condition=conditions.all,
+        for callback in resolver(self.func):
+            condition = next(resolver(self.cond)) if self.cond is not None else allways_true
+            yield CallbackWrapper(
+                callback=self._wrap_callable(callback, self.expected_value),
+                condition=condition,
+                meta=self,
                 unique_key=callback.unique_key,
-                expected_value=self.expected_value,
-            )
-
-        if not self.suppress_errors:
-            raise AttrNotFound(
-                _("Did not found name '{}' from model or statemachine").format(
-                    self.func
-                )
             )
-        return None
 
 
 class BoolCallbackMeta(CallbackMeta):
@@ -102,18 +120,32 @@ class BoolCallbackMeta(CallbackMeta):
     call is performed, to allow the proper callback resolution.
     """
 
-    def __init__(self, func, suppress_errors=False, cond=None, expected_value=True):
-        self.func = func
-        self.suppress_errors = suppress_errors
-        self.cond = CallbackMetaList().add(cond)
-        self.expected_value = expected_value
+    def __init__(
+        self,
+        func,
+        suppress_errors=False,
+        cond=None,
+        priority: CallbackPriority = CallbackPriority.NAMING,
+        expected_value=True,
+    ):
+        super().__init__(
+            func, suppress_errors, cond, priority=priority, expected_value=expected_value
+        )
 
     def __str__(self):
         name = super().__str__()
         return name if self.expected_value else f"!{name}"
 
+    def _wrap_callable(self, func, expected_value):
+        async def bool_wrapper(*args, **kwargs):
+            return bool(await func(*args, **kwargs)) == expected_value
+
+        return bool_wrapper
+
 
 class CallbackMetaList:
+    """List of `CallbackMeta` instances"""
+
     def __init__(self, factory=CallbackMeta):
         self.items: List[CallbackMeta] = []
         self.factory = factory
@@ -157,6 +189,7 @@ class CallbackMetaList:
         return func
 
     def __call__(self, callback):
+        """Allows usage of the callback list as a decorator."""
         return self._add_unbounded_callback(callback)
 
     def __iter__(self):
@@ -165,18 +198,13 @@ class CallbackMetaList:
     def clear(self):
         self.items = []
 
-    def _add(self, func, registry=None, prepend=False, **kwargs):
+    def _add(self, func, **kwargs):
         meta = self.factory(func, **kwargs)
-        if registry is not None and not registry(self, meta, prepend=prepend):
-            return
 
         if meta in self.items:
             return
 
-        if prepend:
-            self.items.insert(0, meta)
-        else:
-            self.items.append(meta)
+        self.items.append(meta)
         return meta
 
     def add(self, callbacks, **kwargs):
@@ -191,6 +219,8 @@ class CallbackMetaList:
 
 
 class CallbacksExecutor:
+    """A list of callbacks that can be executed in order."""
+
     def __init__(self):
         self.items: List[CallbackWrapper] = deque()
         self.items_already_seen = set()
@@ -201,60 +231,60 @@ class CallbacksExecutor:
     def __repr__(self):
         return f"{type(self).__name__}({self.items!r})"
 
-    def add_one(
-        self, callback_info: CallbackMeta, resolver: Callable, prepend: bool = False
-    ) -> "CallbackWrapper | None":
-        callback = callback_info.build(resolver)
-        if callback is None:
-            return None
+    def __str__(self):
+        return ", ".join(str(c) for c in self)
 
-        if callback.unique_key in self.items_already_seen:
-            return None
+    def _add(self, callback_meta: CallbackMeta, resolver: Callable):
+        for callback in callback_meta.build(resolver):
+            if callback.unique_key in self.items_already_seen:
+                continue
 
-        self.items_already_seen.add(callback.unique_key)
-        if prepend:
-            self.items.insert(0, callback)
-        else:
-            self.items.append(callback)
-        return callback
+            self.items_already_seen.add(callback.unique_key)
+            insort(self.items, callback)
 
     def add(self, items: CallbackMetaList, resolver: Callable):
         """Validate configurations"""
         for item in items:
-            self.add_one(item, resolver)
+            self._add(item, resolver)
         return self
 
-    def call(self, *args, **kwargs):
+    async def call(self, *args, **kwargs):
         return [
-            callback(*args, **kwargs)
+            await callback(*args, **kwargs)
             for callback in self
-            if callback.condition(*args, **kwargs)
+            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:
     def __init__(self) -> None:
-        self._registry: Dict[CallbackMetaList, CallbacksExecutor] = defaultdict(
-            CallbacksExecutor
-        )
+        self._registry: Dict[CallbackMetaList, CallbacksExecutor] = defaultdict(CallbacksExecutor)
 
-    def register(self, callbacks: CallbackMetaList, resolver):
-        executor_list = self[callbacks]
-        executor_list.add(callbacks, resolver)
+    def register(self, meta_list: CallbackMetaList, resolver):
+        executor_list = self[meta_list]
+        executor_list.add(meta_list, resolver)
         return executor_list
 
-    def __getitem__(self, callbacks: CallbackMetaList) -> CallbacksExecutor:
-        return self._registry[callbacks]
+    def clear(self):
+        self._registry.clear()
+
+    def __getitem__(self, meta_list: CallbackMetaList) -> CallbacksExecutor:
+        return self._registry[meta_list]
 
-    def build_register_function_for_resolver(self, resolver):
-        def register(
-            meta_list: CallbackMetaList,
-            meta: CallbackMeta,
-            prepend: bool = False,
-        ):
-            return self[meta_list].add_one(meta, resolver, prepend=prepend)
+    def check(self, meta_list: CallbackMetaList):
+        executor = self[meta_list]
+        for meta in meta_list:
+            if meta.suppress_errors:
+                continue
 
-        return register
+            if any(callback for callback in executor if callback.meta == meta):
+                continue
+            raise AttrNotFound(
+                _("Did not found name '{}' from model or statemachine").format(meta.func)
+            )

statemachine/contrib/diagram.py

@@ -66,21 +66,35 @@ class DotGraphMachine:
             fontsize=self.transition_font_size,
         )
 
+    def _actions_getter(self):
+        if isinstance(self.machine, StateMachine):
+
+            def getter(x):
+                return self.machine._callbacks(x)
+        else:
+
+            def getter(x):
+                return x
+
+        return getter
+
     def _state_actions(self, state):
-        entry = ", ".join([str(action) for action in state.enter])
-        exit = ", ".join([str(action) for action in state.exit])
+        getter = self._actions_getter()
+
+        entry = str(getter(state.enter))
+        exit_ = str(getter(state.exit))
         internal = ", ".join(
-            f"{transition.event} / {transition.on!s}"
+            f"{transition.event} / {str(getter(transition.on))}"
             for transition in state.transitions
             if transition.internal
         )
 
         if entry:
             entry = f"entry / {entry}"
-        if exit:
-            exit = f"exit / {exit}"
+        if exit_:
+            exit_ = f"exit / {exit_}"
 
-        actions = "\n".join(x for x in [entry, exit, internal] if x)
+        actions = "\n".join(x for x in [entry, exit_, internal] if x)
 
         if actions:
             actions = f"\n{actions}"