python-statemachine 2.3.5__tar.gz → 2.4.0__tar.gz

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-statemachine
-Version: 2.3.5
+Version: 2.4.0
 Summary: Python Finite State Machines made easy.
 Home-page: https://github.com/fgmacedo/python-statemachine
 License: MIT
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Provides-Extra: diagrams
+Requires-Dist: pydot (>=2.0.0) ; (python_full_version > "3.8.0") and (extra == "diagrams")
 Description-Content-Type: text/markdown
 
 # Python StateMachine
@@ -404,7 +405,7 @@ There's a lot more to cover, please take a look at our docs:
 https://python-statemachine.readthedocs.io.
 
 
-## Contributing to the project
+## Contributing
 
 * <a class="github-button" href="https://github.com/fgmacedo/python-statemachine" data-icon="octicon-star" aria-label="Star fgmacedo/python-statemachine on GitHub">Star this project</a>
 * <a class="github-button" href="https://github.com/fgmacedo/python-statemachine/issues" data-icon="octicon-issue-opened" aria-label="Issue fgmacedo/python-statemachine on GitHub">Open an Issue</a>
@@ -412,18 +413,18 @@ https://python-statemachine.readthedocs.io.
 
 - If you found this project helpful, please consider giving it a star on GitHub.
 
-- **Contribute code**: If you would like to contribute code to this project, please submit a pull
+- **Contribute code**: If you would like to contribute code, please submit a pull
 request. For more information on how to contribute, please see our [contributing.md](contributing.md) file.
 
-- **Report bugs**: If you find any bugs in this project, please report them by opening an issue
+- **Report bugs**: If you find any bugs, please report them by opening an issue
   on our GitHub issue tracker.
 
-- **Suggest features**: If you have a great idea for a new feature, please let us know by opening
-  an issue on our GitHub issue tracker.
+- **Suggest features**: If you have an idea for a new feature, of feels something being harder than it should be,
+  please let us know by opening an issue on our GitHub issue tracker.
 
-- **Documentation**: Help improve this project's documentation by submitting pull requests.
+- **Documentation**: Help improve documentation by submitting pull requests.
 
-- **Promote the project**: Help spread the word about this project by sharing it on social media,
+- **Promote the project**: Help spread the word by sharing on social media,
   writing a blog post, or giving a talk about it. Tag me on Twitter
   [@fgmacedo](https://twitter.com/fgmacedo) so I can share it too!
 

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/README.md

@@ -377,7 +377,7 @@ There's a lot more to cover, please take a look at our docs:
 https://python-statemachine.readthedocs.io.
 
 
-## Contributing to the project
+## Contributing
 
 * <a class="github-button" href="https://github.com/fgmacedo/python-statemachine" data-icon="octicon-star" aria-label="Star fgmacedo/python-statemachine on GitHub">Star this project</a>
 * <a class="github-button" href="https://github.com/fgmacedo/python-statemachine/issues" data-icon="octicon-issue-opened" aria-label="Issue fgmacedo/python-statemachine on GitHub">Open an Issue</a>
@@ -385,17 +385,17 @@ https://python-statemachine.readthedocs.io.
 
 - If you found this project helpful, please consider giving it a star on GitHub.
 
-- **Contribute code**: If you would like to contribute code to this project, please submit a pull
+- **Contribute code**: If you would like to contribute code, please submit a pull
 request. For more information on how to contribute, please see our [contributing.md](contributing.md) file.
 
-- **Report bugs**: If you find any bugs in this project, please report them by opening an issue
+- **Report bugs**: If you find any bugs, please report them by opening an issue
   on our GitHub issue tracker.
 
-- **Suggest features**: If you have a great idea for a new feature, please let us know by opening
-  an issue on our GitHub issue tracker.
+- **Suggest features**: If you have an idea for a new feature, of feels something being harder than it should be,
+  please let us know by opening an issue on our GitHub issue tracker.
 
-- **Documentation**: Help improve this project's documentation by submitting pull requests.
+- **Documentation**: Help improve documentation by submitting pull requests.
 
-- **Promote the project**: Help spread the word about this project by sharing it on social media,
+- **Promote the project**: Help spread the word by sharing on social media,
   writing a blog post, or giving a talk about it. Tag me on Twitter
   [@fgmacedo](https://twitter.com/fgmacedo) so I can share it too!

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/pyproject.toml

@@ -1,21 +1,19 @@
 [tool.poetry]
 name = "python-statemachine"
-version = "2.3.5"
+version = "2.4.0"
 description = "Python Finite State Machines made easy."
 authors = ["Fernando Macedo <fgmacedo@gmail.com>"]
-maintainers = [
-    "Fernando Macedo <fgmacedo@gmail.com>",
-]
+maintainers = ["Fernando Macedo <fgmacedo@gmail.com>"]
 license = "MIT license"
 readme = "README.md"
 homepage = "https://github.com/fgmacedo/python-statemachine"
-packages = [
-    {include = "statemachine"},
-    {include = "statemachine/**/*.py" },
-]
+packages = [{ include = "statemachine" }, { include = "statemachine/**/*.py" }]
 include = [
     { path = "statemachine/locale/**/*.po", format = "sdist" },
-    { path = "statemachine/locale/**/*.mo", format = ["sdist", "wheel"] }
+    { path = "statemachine/locale/**/*.mo", format = [
+        "sdist",
+        "wheel",
+    ] },
 ]
 classifiers = [
     "Intended Audience :: Developers",
@@ -33,14 +31,14 @@ classifiers = [
     "Intended Audience :: Developers",
 ]
 
-[tool.poetry.extras]
-diagrams = ["pydot"]
-
 [tool.poetry.dependencies]
 python = ">=3.7"
+pydot = { version = ">=2.0.0", optional = true, python = ">3.8" }
+
+[tool.poetry.extras]
+diagrams = ["pydot"]
 
 [tool.poetry.group.dev.dependencies]
-pydot = "^2.0.0"
 ruff = "^0.4.8"
 pre-commit = "*"
 mypy = "*"
@@ -59,7 +57,7 @@ pytest-django = { version = "^4.8.0", python = ">3.8" }
 Sphinx = { version = "*", python = ">3.8" }
 myst-parser = { version = "*", python = ">3.8" }
 sphinx-gallery = { version = "*", python = ">3.8" }
-pillow = { version ="*", python = ">3.8" }
+pillow = { version = "*", python = ">3.8" }
 sphinx-autobuild = { version = "*", python = ">3.8" }
 furo = { version = "^2024.5.6", python = ">3.8" }
 sphinx-copybutton = { version = "^0.5.2", python = ">3.8" }
@@ -72,9 +70,7 @@ build-backend = "poetry.core.masonry.api"
 addopts = "--ignore=docs/conf.py --ignore=docs/auto_examples/ --ignore=docs/_build/ --ignore=tests/examples/ --cov --cov-config .coveragerc --doctest-glob='*.md' --doctest-modules --doctest-continue-on-failure --benchmark-autosave --benchmark-group-by=name"
 doctest_optionflags = "ELLIPSIS IGNORE_EXCEPTION_DETAIL NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL"
 asyncio_mode = "auto"
-markers = [
-    """slow: marks tests as slow (deselect with '-m "not slow"')""",
-]
+markers = ["""slow: marks tests as slow (deselect with '-m "not slow"')"""]
 python_files = ["tests.py", "test_*.py", "*_tests.py"]
 
 [tool.mypy]
@@ -85,19 +81,11 @@ disable_error_code = "annotation-unchecked"
 mypy_path = "$MYPY_CONFIG_FILE_DIR/tests/django_project"
 
 [[tool.mypy.overrides]]
-module = [
-    'django.*',
-    'pytest.*',
-    'pydot.*',
-    'sphinx_gallery.*',
-]
+module = ['django.*', 'pytest.*', 'pydot.*', 'sphinx_gallery.*']
 ignore_missing_imports = true
 
 [tool.flake8]
-ignore = [
-    "E231",
-    "W503",
-]
+ignore = ["E231", "W503"]
 max-line-length = 99
 
 [tool.ruff]
@@ -131,10 +119,10 @@ exclude = [
 
 # Enable Pyflakes and pycodestyle rules.
 select = [
-    "E", # pycodestyle errors
-    "W", # pycodestyle warnings
-    "F", # pyflakes
-    "I", # isort
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
     "UP", # pyupgrade
     "C",  # flake8-comprehensions
     "B",  # flake8-bugbear
@@ -169,14 +157,8 @@ convention = "google"
 branch = true
 relative_files = true
 data_file = ".coverage"
-source = [
-    "statemachine",
-]
-omit = [
-    "*test*.py",
-    "tmp/*",
-    "pytest_cov",
-]
+source = ["statemachine"]
+omit = ["*test*.py", "tmp/*", "pytest_cov"]
 [tool.coverage.report]
 show_missing = true
 exclude_lines = [
@@ -190,7 +172,7 @@ exclude_lines = [
     # Don't complain if tests don't hit defensive assertion code:
     "raise AssertionError",
     "raise NotImplementedError",
-   "if TYPE_CHECKING",
+    "if TYPE_CHECKING",
 ]
 
 [tool.coverage.html]

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/statemachine/__init__.py

@@ -1,8 +1,9 @@
+from .event import Event
 from .state import State
 from .statemachine import StateMachine
 
 __author__ = """Fernando Macedo"""
 __email__ = "fgmacedo@gmail.com"
-__version__ = "2.3.5"
+__version__ = "2.4.0"
 
-__all__ = ["StateMachine", "State"]
+__all__ = ["StateMachine", "State", "Event"]

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/statemachine/callbacks.py

@@ -5,19 +5,30 @@ from collections import deque
 from enum import IntEnum
 from enum import IntFlag
 from enum import auto
+from functools import partial
+from functools import reduce
 from inspect import isawaitable
 from inspect import iscoroutinefunction
+from typing import TYPE_CHECKING
 from typing import Callable
 from typing import Dict
 from typing import Generator
 from typing import Iterable
 from typing import List
+from typing import Set
 from typing import Type
 
 from .exceptions import AttrNotFound
+from .exceptions import InvalidDefinition
 from .i18n import _
+from .spec_parser import custom_and
+from .spec_parser import operator_mapping
+from .spec_parser import parse_boolean_expr
 from .utils import ensure_iterable
 
+if TYPE_CHECKING:
+    from statemachine.dispatcher import Listeners
+
 
 class CallbackPriority(IntEnum):
     GENERIC = 0
@@ -54,6 +65,17 @@ def allways_true(*args, **kwargs):
     return True
 
 
+def take_callback(name: str, resolver: "Listeners", not_found_handler: Callable) -> Callable:
+    callbacks = list(resolver.search_name(name))
+    if len(callbacks) == 0:
+        not_found_handler(name)
+        return allways_true
+    elif len(callbacks) == 1:
+        return callbacks[0]
+    else:
+        return reduce(custom_and, callbacks)
+
+
 class CallbackSpec:
     """Specs about callbacks.
 
@@ -110,7 +132,16 @@ class CallbackSpec:
         self.reference = SpecReference.CALLABLE
         self.attr_name = attr_name
 
-    def build(self, resolver) -> Generator["CallbackWrapper", None, None]:
+    def _wrap(self, callback):
+        condition = self.cond if self.cond is not None else allways_true
+        return CallbackWrapper(
+            callback=callback,
+            condition=condition,
+            meta=self,
+            unique_key=callback.unique_key,
+        )
+
+    def build(self, resolver: "Listeners") -> Generator["CallbackWrapper", None, None]:
         """
         Resolves the `func` into a usable callable.
 
@@ -118,14 +149,29 @@ class CallbackSpec:
             resolver (callable): A method responsible to build and return a valid callable that
                 can receive arbitrary parameters like `*args, **kwargs`.
         """
-        for callback in resolver.search(self):
-            condition = self.cond if self.cond is not None else allways_true
-            yield CallbackWrapper(
-                callback=callback,
-                condition=condition,
-                meta=self,
-                unique_key=callback.unique_key,
+        if (
+            not self.is_convention
+            and self.group == CallbackGroup.COND
+            and self.reference == SpecReference.NAME
+        ):
+            names_not_found: Set[str] = set()
+            take_callback_partial = partial(
+                take_callback, resolver=resolver, not_found_handler=names_not_found.add
             )
+            try:
+                expression = parse_boolean_expr(self.func, take_callback_partial, operator_mapping)
+            except SyntaxError as err:
+                raise InvalidDefinition(
+                    _("Failed to parse boolean expression '{}'").format(self.func)
+                ) from err
+            if not expression or names_not_found:
+                self.names_not_found = names_not_found
+                return
+            yield self._wrap(expression)
+            return
+
+        for callback in resolver.search(self):
+            yield self._wrap(callback)
 
 
 class SpecListGrouper:
@@ -292,7 +338,7 @@ class CallbacksExecutor:
     def __str__(self):
         return ", ".join(str(c) for c in self)
 
-    def _add(self, spec: CallbackSpec, resolver: Callable):
+    def _add(self, spec: CallbackSpec, resolver: "Listeners"):
         for callback in spec.build(resolver):
             if callback.unique_key in self.items_already_seen:
                 continue
@@ -300,7 +346,7 @@ class CallbacksExecutor:
             self.items_already_seen.add(callback.unique_key)
             insort(self.items, callback)
 
-    def add(self, items: Iterable[CallbackSpec], resolver: Callable):
+    def add(self, items: Iterable[CallbackSpec], resolver: "Listeners"):
         """Validate configurations"""
         for item in items:
             self._add(item, resolver)
@@ -356,6 +402,12 @@ class CallbacksRegistry:
                 callback for callback in self[meta.group.build_key(specs)] if callback.meta == meta
             ):
                 continue
+            if hasattr(meta, "names_not_found"):
+                raise AttrNotFound(
+                    _("Did not found name '{}' from model or statemachine").format(
+                        ", ".join(meta.names_not_found)
+                    ),
+                )
             raise AttrNotFound(
                 _("Did not found name '{}' from model or statemachine").format(meta.func)
             )

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/statemachine/contrib/diagram.py

@@ -166,10 +166,6 @@ def quickchart_write_svg(sm: StateMachine, path: str):
     >>> sm = OrderControl()
     >>> print(sm._graph().to_string())
     digraph list {
-    fontname=Arial;
-    fontsize=10;
-    label=OrderControl;
-    rankdir=LR;
     ...
 
     To give you an example, we included this method that will serialize the dot, request the graph

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/statemachine/dispatcher.py

@@ -10,6 +10,7 @@ from typing import Tuple
 
 from .callbacks import SPECS_ALL
 from .callbacks import SpecReference
+from .event import Event
 from .signature import SignatureAdapter
 
 if TYPE_CHECKING:
@@ -75,7 +76,7 @@ class Listeners:
 
     def search(self, spec: "CallbackSpec") -> Generator["Callable", None, None]:
         if spec.reference is SpecReference.NAME:
-            yield from self._search_name(spec.func)
+            yield from self.search_name(spec.func)
             return
         elif spec.reference is SpecReference.CALLABLE:
             yield self._search_callable(spec)
@@ -111,7 +112,7 @@ class Listeners:
 
         return callable_method(spec.attr_name, spec.func, None)
 
-    def _search_name(self, name) -> Generator["Callable", None, None]:
+    def search_name(self, name) -> Generator["Callable", None, None]:
         for config in self.items:
             if name not in config.all_attrs:
                 continue
@@ -121,7 +122,7 @@ class Listeners:
                 yield attr_method(name, config.obj, config.resolver_id)
                 continue
 
-            if getattr(func, "_is_sm_event", False):
+            if isinstance(func, Event):
                 yield event_method(name, func, config.resolver_id)
                 continue
 
@@ -143,6 +144,7 @@ def attr_method(attribute, obj, resolver_id) -> Callable:
         return getter(obj)
 
     method.unique_key = f"{attribute}@{resolver_id}"  # type: ignore[attr-defined]
+    method.__name__ = attribute
     return method
 
 

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/statemachine/engines/async_.py

@@ -15,6 +15,7 @@ if TYPE_CHECKING:
 
 class AsyncEngine:
     def __init__(self, sm: "StateMachine", rtc: bool = True):
+        sm._engine = self
         self.sm = proxy(sm)
         self._sentinel = object()
         if not rtc:

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/statemachine/engines/sync.py

@@ -13,6 +13,7 @@ if TYPE_CHECKING:
 
 class SyncEngine:
     def __init__(self, sm: "StateMachine", rtc: bool = True):
+        sm._engine = self
         self.sm = proxy(sm)
         self._sentinel = object()
         self._rtc = rtc

python_statemachine-2.4.0/statemachine/event.py

@@ -0,0 +1,131 @@
+from inspect import isawaitable
+from typing import TYPE_CHECKING
+from typing import List
+from uuid import uuid4
+
+from statemachine.utils import run_async_from_sync
+
+from .event_data import TriggerData
+
+if TYPE_CHECKING:
+    from .statemachine import StateMachine
+    from .transition_list import TransitionList
+
+
+_event_data_kwargs = {
+    "event_data",
+    "machine",
+    "event",
+    "model",
+    "transition",
+    "state",
+    "source",
+    "target",
+}
+
+
+class Event(str):
+    """An event is triggers a signal that something has happened.
+
+    They are send to a state machine and allow the state machine to react.
+
+    An event starts a :ref:`Transition`, which can be thought of as a “cause” that initiates a
+    change in the state of the system.
+
+    See also :ref:`events`.
+    """
+
+    id: str
+    """The event identifier."""
+
+    name: str
+    """The event name."""
+
+    _sm: "StateMachine | None" = None
+    """The state machine instance."""
+
+    _transitions: "TransitionList | None" = None
+    _has_real_id = False
+
+    def __new__(
+        cls,
+        transitions: "str | TransitionList | None" = None,
+        id: "str | None" = None,
+        name: "str | None" = None,
+        _sm: "StateMachine | None" = None,
+    ):
+        if isinstance(transitions, str):
+            id = transitions
+            transitions = None
+
+        _has_real_id = id is not None
+        id = str(id) if _has_real_id else f"__event__{uuid4().hex}"
+
+        instance = super().__new__(cls, id)
+        instance.id = id
+        if name:
+            instance.name = name
+        elif _has_real_id:
+            instance.name = str(id).replace("_", " ").capitalize()
+        else:
+            instance.name = ""
+        if transitions:
+            instance._transitions = transitions
+        instance._has_real_id = _has_real_id
+        instance._sm = _sm
+        return instance
+
+    def __repr__(self):
+        return f"{type(self).__name__}({self.id!r})"
+
+    def is_same_event(self, *_args, event: "str | None" = None, **_kwargs) -> bool:
+        return self == event
+
+    def __get__(self, instance, owner):
+        """By implementing this method `Event` can be used as a property descriptor
+
+        When attached to a SM class, if the user tries to get the `Event` instance,
+        we intercept here and return a `BoundEvent` instance, so the user can call
+        it as a method with the correct SM instance.
+
+        """
+        if instance is None:
+            return self
+        return BoundEvent(id=self.id, name=self.name, _sm=instance)
+
+    def __call__(self, *args, **kwargs):
+        """Send this event to the current state machine.
+
+        Triggering an event on a state machine means invoking or sending a signal, initiating the
+        process that may result in executing a transition.
+        """
+        # The `__call__` is declared here to help IDEs knowing that an `Event`
+        # can be called as a method. But it is not meant to be called without
+        # an SM instance. Such SM instance is provided by `__get__` method when
+        # used as a property descriptor.
+
+        machine = self._sm
+        kwargs = {k: v for k, v in kwargs.items() if k not in _event_data_kwargs}
+        trigger_data = TriggerData(
+            machine=machine,
+            event=self,
+            args=args,
+            kwargs=kwargs,
+        )
+        machine._put_nonblocking(trigger_data)
+        result = machine._processing_loop()
+        if not isawaitable(result):
+            return result
+        return run_async_from_sync(result)
+
+    def split(  # type: ignore[override]
+        self, sep: "str | None" = None, maxsplit: int = -1
+    ) -> List["Event"]:
+        result = super().split(sep, maxsplit)
+        if len(result) == 1:
+            return [self]
+        return [Event(event) for event in result]
+
+
+class BoundEvent(Event):
+    pass

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/statemachine/event_data.py

@@ -4,6 +4,7 @@ from typing import TYPE_CHECKING
 from typing import Any
 
 if TYPE_CHECKING:
+    from .event import Event
     from .state import State
     from .statemachine import StateMachine
     from .transition import Transition
@@ -13,7 +14,7 @@ if TYPE_CHECKING:
 class TriggerData:
     machine: "StateMachine"
 
-    event: str
+    event: "Event"
     """The Event that was triggered."""
 
     model: Any = field(init=False)

python_statemachine-2.4.0/statemachine/events.py

@@ -0,0 +1,40 @@
+from statemachine.event import Event
+
+from .utils import ensure_iterable
+
+
+class Events:
+    """A collection of event names."""
+
+    def __init__(self):
+        self._items: list[Event] = []
+
+    def __repr__(self):
+        sep = " " if len(self._items) > 1 else ""
+        return sep.join(item for item in self._items)
+
+    def __iter__(self):
+        return iter(self._items)
+
+    def add(self, events):
+        if events is None:
+            return self
+
+        unprepared = ensure_iterable(events)
+        for events in unprepared:
+            for event in events.split(" "):
+                if event in self._items:
+                    continue
+                if isinstance(event, Event):
+                    self._items.append(event)
+                else:
+                    self._items.append(Event(id=event, name=event))
+
+        return self
+
+    def match(self, event: str):
+        return any(e == event for e in self)
+
+    def _replace(self, old, new):
+        self._items.remove(old)
+        self._items.append(new)

{python_statemachine-2.3.5 → python_statemachine-2.4.0}/statemachine/exceptions.py

@@ -3,6 +3,7 @@ from typing import TYPE_CHECKING
 from .i18n import _
 
 if TYPE_CHECKING:
+    from .event import Event
     from .state import State
 
 
@@ -31,8 +32,8 @@ class AttrNotFound(InvalidDefinition):
 class TransitionNotAllowed(StateMachineError):
     "Raised when there's no transition that can run from the current :ref:`state`."
 
-    def __init__(self, event: str, state: "State"):
+    def __init__(self, event: "Event", state: "State"):
         self.event = event
         self.state = state
-        msg = _("Can't {} when in {}.").format(self.event, self.state.name)
+        msg = _("Can't {} when in {}.").format(self.event.name, self.state.name)
         super().__init__(msg)