python-statemachine 2.3.1__tar.gz → 2.3.2__tar.gz

{python_statemachine-2.3.1 → python_statemachine-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-statemachine
-Version: 2.3.1
+Version: 2.3.2
 Summary: Python Finite State Machines made easy.
 Home-page: https://github.com/fgmacedo/python-statemachine
 License: MIT
@@ -103,7 +103,7 @@ Define your state machine:
 ...         | red.to(green)
 ...     )
 ...
-...     async def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+...     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}"
 ...
@@ -146,26 +146,6 @@ Then start sending events to your new state machine:
 
 ```
 
-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.
 
@@ -253,7 +233,7 @@ callback method.
 Note how `before_cycle` was declared:
 
 ```py
-async def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+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}"
 ```

{python_statemachine-2.3.1 → python_statemachine-2.3.2}/README.md

@@ -77,7 +77,7 @@ Define your state machine:
 ...         | red.to(green)
 ...     )
 ...
-...     async def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+...     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}"
 ...
@@ -120,26 +120,6 @@ Then start sending events to your new state machine:
 
 ```
 
-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.
 
@@ -227,7 +207,7 @@ callback method.
 Note how `before_cycle` was declared:
 
 ```py
-async def before_cycle(self, event: str, source: State, target: State, message: str = ""):
+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}"
 ```

{python_statemachine-2.3.1 → python_statemachine-2.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-statemachine"
-version = "2.3.1"
+version = "2.3.2"
 description = "Python Finite State Machines made easy."
 authors = ["Fernando Macedo <fgmacedo@gmail.com>"]
 maintainers = [
@@ -39,18 +39,21 @@ diagrams = ["pydot"]
 python = ">=3.7"
 
 [tool.poetry.group.dev.dependencies]
-pytest = "*"
-pytest-cov = "*"
-pytest-sugar = "^1.0.0"
 pydot = "^2.0.0"
 ruff = "^0.4.8"
 pre-commit = "*"
 mypy = "*"
+
+[tool.poetry.group.tests.dependencies]
+pytest = "*"
+pytest-cov = "*"
+pytest-sugar = "^1.0.0"
 pytest-mock = "^3.10.0"
 pytest-profiling = "^1.7.0"
 pytest-benchmark = "^4.0.0"
 pytest-asyncio = "*"
-sphinx-rtd-theme = "^2.0.0"
+django = { version = "^5.0.3", python = ">3.10" }
+pytest-django = { version = "^4.8.0", python = ">3.8" }
 
 [tool.poetry.group.docs.dependencies]
 Sphinx = "*"
@@ -65,18 +68,20 @@ requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.pytest.ini_options]
-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"
+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"')""",
 ]
+python_files = ["tests.py", "test_*.py", "*_tests.py"]
 
 [tool.mypy]
 python_version = "3.12"
 warn_return_any = true
 warn_unused_configs = true
 disable_error_code = "annotation-unchecked"
+mypy_path = "$MYPY_CONFIG_FILE_DIR/tests/django_project"
 
 [[tool.mypy.overrides]]
 module = [

{python_statemachine-2.3.1 → python_statemachine-2.3.2}/statemachine/__init__.py

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

python_statemachine-2.3.2/statemachine/callbacks.py

@@ -0,0 +1,362 @@
+import asyncio
+from bisect import insort
+from collections import Counter
+from collections import defaultdict
+from collections import deque
+from enum import IntEnum
+from enum import auto
+from inspect import isawaitable
+from inspect import iscoroutinefunction
+from typing import Callable
+from typing import Dict
+from typing import Generator
+from typing import Iterable
+from typing import List
+from typing import Type
+
+from .exceptions import AttrNotFound
+from .i18n import _
+from .utils import ensure_iterable
+
+
+class CallbackPriority(IntEnum):
+    GENERIC = 0
+    INLINE = 10
+    DECORATOR = 20
+    NAMING = 30
+    AFTER = 40
+
+
+class SpecReference(IntEnum):
+    NAME = 1
+    CALLABLE = 2
+    PROPERTY = 3
+
+
+class CallbackGroup(IntEnum):
+    ENTER = auto()
+    EXIT = auto()
+    VALIDATOR = auto()
+    BEFORE = auto()
+    ON = auto()
+    AFTER = auto()
+    COND = auto()
+
+    def build_key(self, specs: "CallbackSpecList") -> str:
+        return f"{self.name}@{id(specs)}"
+
+
+def allways_true(*args, **kwargs):
+    return True
+
+
+class CallbackSpec:
+    """Specs about callbacks.
+
+    At first, `func` can be a name (string), a property or a callable.
+
+    Names, properties and unbounded callables should be resolved to a callable
+    before any real call is performed.
+    """
+
+    def __init__(
+        self,
+        func,
+        group: CallbackGroup,
+        is_convention=False,
+        cond=None,
+        priority: CallbackPriority = CallbackPriority.NAMING,
+        expected_value=None,
+    ):
+        self.func = func
+        self.group = group
+        self.is_convention = is_convention
+        self.cond = cond
+        self.expected_value = expected_value
+        self.priority = priority
+
+        if isinstance(func, property):
+            self.reference = SpecReference.PROPERTY
+            self.attr_name: str = func and func.fget and func.fget.__name__ or ""
+        elif callable(func):
+            self.reference = SpecReference.CALLABLE
+            self.is_bounded = hasattr(func, "__self__")
+            self.attr_name = func.__name__
+        else:
+            self.reference = SpecReference.NAME
+            self.attr_name = func
+
+    def __repr__(self):
+        return f"{type(self).__name__}({self.func!r}, is_convention={self.is_convention!r})"
+
+    def __str__(self):
+        name = getattr(self.func, "__name__", self.func)
+        if self.expected_value is False:
+            name = f"!{name}"
+        return name
+
+    def __eq__(self, other):
+        return self.func == other.func and self.group == other.group
+
+    def __hash__(self):
+        return id(self)
+
+    def _update_func(self, func: Callable, attr_name: str):
+        self.func = func
+        self.reference = SpecReference.CALLABLE
+        self.attr_name = attr_name
+
+    def build(self, resolver) -> Generator["CallbackWrapper", None, None]:
+        """
+        Resolves the `func` into a usable callable.
+
+        Args:
+            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,
+            )
+
+
+class SpecListGrouper:
+    def __init__(
+        self, list: "CallbackSpecList", group: CallbackGroup, factory=CallbackSpec
+    ) -> None:
+        self.list = list
+        self.group = group
+        self.factory = factory
+        self.key = group.build_key(list)
+
+    def add(self, callbacks, **kwargs):
+        self.list.add(callbacks, group=self.group, factory=self.factory, **kwargs)
+        return self
+
+    def __call__(self, callback):
+        return self.list._add_unbounded_callback(callback, group=self.group, factory=self.factory)
+
+    def _add_unbounded_callback(self, func, is_event=False, transitions=None, **kwargs):
+        self.list._add_unbounded_callback(
+            func,
+            is_event=is_event,
+            transitions=transitions,
+            group=self.group,
+            factory=self.factory,
+            **kwargs,
+        )
+
+    def __iter__(self):
+        return (item for item in self.list if item.group == self.group)
+
+
+class CallbackSpecList:
+    """List of {ref}`CallbackSpec` instances"""
+
+    def __init__(self, factory=CallbackSpec):
+        self.items: List[CallbackSpec] = []
+        self.conventional_specs = set()
+        self.factory = factory
+
+    def __repr__(self):
+        return f"{type(self).__name__}({self.items!r}, factory={self.factory!r})"
+
+    def _add_unbounded_callback(self, func, is_event=False, transitions=None, **kwargs):
+        """This list was a target for adding a func using decorator
+        `@<state|event>[.on|before|after|enter|exit]` syntax.
+
+        If we assign ``func`` directly as callable on the ``items`` list,
+        this will result in an `unbounded method error`, with `func` expecting a parameter
+        ``self`` not defined.
+
+        The implemented solution is to resolve the collision giving the func a reference method.
+        To update It's callback when the name is resolved on the
+        :func:`StateMachineMetaclass.add_from_attributes`.
+        If the ``func`` is bounded It will be used directly, if not, it's ref will be replaced
+        by the given attr name and on `statemachine._setup()` the dynamic name will be resolved
+        properly.
+
+        Args:
+            func (callable): The decorated method to add on the transitions occurs.
+            is_event (bool): If the func is also an event, we'll create a trigger and link the
+                event name to the transitions.
+            transitions (TransitionList): If ``is_event``, the transitions to be attached to the
+                event.
+
+        """
+        spec = self._add(func, **kwargs)
+        if not getattr(func, "_specs_to_update", None):
+            func._specs_to_update = set()
+        if is_event:
+            func._specs_to_update.add(spec._update_func)
+        func._transitions = transitions
+
+        return func
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def clear(self):
+        self.items = []
+
+    def grouper(
+        self, group: CallbackGroup, factory: Type[CallbackSpec] = CallbackSpec
+    ) -> SpecListGrouper:
+        return SpecListGrouper(self, group, factory=factory)
+
+    def _add(self, func, group: CallbackGroup, factory=None, **kwargs):
+        if factory is None:
+            factory = self.factory
+        spec = factory(func, group, **kwargs)
+
+        if spec in self.items:
+            return
+
+        self.items.append(spec)
+        if spec.is_convention:
+            self.conventional_specs.add(spec.func)
+        return spec
+
+    def add(self, callbacks, group: CallbackGroup, **kwargs):
+        if callbacks is None:
+            return self
+
+        unprepared = ensure_iterable(callbacks)
+        for func in unprepared:
+            self._add(func, group=group, **kwargs)
+
+        return self
+
+
+class CallbackWrapper:
+    def __init__(
+        self,
+        callback: Callable,
+        condition: Callable,
+        meta: "CallbackSpec",
+        unique_key: str,
+    ) -> None:
+        self._callback = callback
+        self._iscoro = iscoroutinefunction(callback)
+        self.condition = condition
+        self.meta = meta
+        self.unique_key = unique_key
+        self.expected_value = self.meta.expected_value
+
+    def __repr__(self):
+        return f"{type(self).__name__}({self.unique_key})"
+
+    def __str__(self):
+        return str(self.meta)
+
+    def __lt__(self, other):
+        return self.meta.priority < other.meta.priority
+
+    async def __call__(self, *args, **kwargs):
+        value = self._callback(*args, **kwargs)
+        if isawaitable(value):
+            value = await value
+
+        if self.expected_value is not None:
+            return bool(value) == self.expected_value
+        return value
+
+    def call(self, *args, **kwargs):
+        value = self._callback(*args, **kwargs)
+        if self.expected_value is not None:
+            return bool(value) == self.expected_value
+        return value
+
+
+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()
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def __repr__(self):
+        return f"{type(self).__name__}({self.items!r})"
+
+    def __str__(self):
+        return ", ".join(str(c) for c in self)
+
+    def _add(self, spec: CallbackSpec, resolver: Callable):
+        for callback in spec.build(resolver):
+            if callback.unique_key in self.items_already_seen:
+                continue
+
+            self.items_already_seen.add(callback.unique_key)
+            insort(self.items, callback)
+
+    def add(self, items: Iterable[CallbackSpec], resolver: Callable):
+        """Validate configurations"""
+        for item in items:
+            self._add(item, resolver)
+        return self
+
+    async def async_call(self, *args, **kwargs):
+        return await asyncio.gather(
+            *(
+                callback(*args, **kwargs)
+                for callback in self
+                if callback.condition(*args, **kwargs)
+            )
+        )
+
+    async def async_all(self, *args, **kwargs):
+        coros = [condition(*args, **kwargs) for condition in self]
+        for coro in asyncio.as_completed(coros):
+            if not await coro:
+                return False
+        return True
+
+    def call(self, *args, **kwargs):
+        return [
+            callback.call(*args, **kwargs)
+            for callback in self
+            if callback.condition(*args, **kwargs)
+        ]
+
+    def all(self, *args, **kwargs):
+        for condition in self:
+            if not condition.call(*args, **kwargs):
+                return False
+        return True
+
+
+class CallbacksRegistry:
+    def __init__(self) -> None:
+        self._registry: Dict[str, CallbacksExecutor] = defaultdict(CallbacksExecutor)
+        self._method_types: Counter = Counter()
+
+    def clear(self):
+        self._registry.clear()
+
+    def __getitem__(self, key: str) -> CallbacksExecutor:
+        return self._registry[key]
+
+    def check(self, specs: CallbackSpecList):
+        for meta in specs:
+            if meta.is_convention:
+                continue
+
+            if any(
+                callback for callback in self[meta.group.build_key(specs)] if callback.meta == meta
+            ):
+                continue
+            raise AttrNotFound(
+                _("Did not found name '{}' from model or statemachine").format(meta.func)
+            )
+
+    def async_or_sync(self):
+        self._method_types.update(
+            callback._iscoro for executor in self._registry.values() for callback in executor
+        )

{python_statemachine-2.3.1 → python_statemachine-2.3.2}/statemachine/contrib/diagram.py

@@ -69,12 +69,15 @@ class DotGraphMachine:
     def _actions_getter(self):
         if isinstance(self.machine, StateMachine):
 
-            def getter(x):
-                return self.machine._callbacks(x)
+            def getter(grouper):
+                return self.machine._get_callbacks(grouper.key)
         else:
 
-            def getter(x):
-                return x
+            def getter(grouper):
+                all_names = set(dir(self.machine))
+                return ", ".join(
+                    str(c) for c in grouper if not c.is_convention or c.func in all_names
+                )
 
         return getter
 

python_statemachine-2.3.2/statemachine/dispatcher.py

@@ -0,0 +1,151 @@
+from dataclasses import dataclass
+from operator import attrgetter
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Callable
+from typing import Generator
+from typing import Iterable
+from typing import Set
+from typing import Tuple
+
+from statemachine.callbacks import SpecReference
+
+from .signature import SignatureAdapter
+
+if TYPE_CHECKING:
+    from .callbacks import CallbackSpec
+    from .callbacks import CallbackSpecList
+
+
+@dataclass
+class Listener:
+    """Object reference that provides attributes to be used as callbacks.
+
+    Args:
+        obj: Any object that will serve as lookup for attributes.
+        skip_attrs: Protected attrs that will be ignored on the search.
+    """
+
+    obj: object
+    all_attrs: Set[str]
+    resolver_id: str
+
+    @classmethod
+    def from_obj(cls, obj, skip_attrs=None) -> "Listener":
+        if isinstance(obj, Listener):
+            return obj
+        else:
+            if skip_attrs is None:
+                skip_attrs = set()
+            all_attrs = set(dir(obj)) - skip_attrs
+            return cls(obj, all_attrs, str(id(obj)))
+
+
+@dataclass
+class Listeners:
+    """Listeners that provides attributes to be used as callbacks."""
+
+    items: Tuple[Listener, ...]
+    all_attrs: Set[str]
+
+    @classmethod
+    def from_listeners(cls, listeners: Iterable["Listener"]) -> "Listeners":
+        listeners = tuple(listeners)
+        all_attrs = set().union(*(listener.all_attrs for listener in listeners))
+        return cls(listeners, all_attrs)
+
+    def resolve(self, specs: "CallbackSpecList", registry):
+        found_convention_specs = specs.conventional_specs & self.all_attrs
+        filtered_specs = [
+            spec for spec in specs if not spec.is_convention or spec.func in found_convention_specs
+        ]
+        if not filtered_specs:
+            return
+
+        for spec in filtered_specs:
+            registry[spec.group.build_key(specs)]._add(spec, self)
+
+    def search(self, spec: "CallbackSpec") -> Generator["Callable", None, None]:
+        if spec.reference is SpecReference.NAME:
+            yield from self._search_name(spec.func)
+            return
+        elif spec.reference is SpecReference.CALLABLE:
+            yield self._search_callable(spec)
+            return
+        elif spec.reference is SpecReference.PROPERTY:
+            result = self._search_property(spec)
+            if result is not None:
+                yield result
+            return
+        else:  # never reached here from tests but put an exception for safety. pragma: no cover
+            raise ValueError(f"Invalid reference {spec.reference}")
+
+    def _search_property(self, spec) -> "Callable | None":
+        # if the attr is a property, we'll try to find the object that has the
+        # property on the configs
+        attr_name = spec.attr_name
+        if attr_name not in self.all_attrs:
+            return None
+        for config in self.items:
+            func = getattr(type(config.obj), attr_name, None)
+            if func is not None and func is spec.func:
+                return attr_method(attr_name, config.obj, config.resolver_id)
+        return None
+
+    def _search_callable(self, spec) -> "Callable":
+        # if the attr is an unbounded method, we'll try to find the bounded method
+        # on the self
+        if not spec.is_bounded:
+            for config in self.items:
+                func = getattr(config.obj, spec.attr_name, None)
+                if func is not None and func.__func__ is spec.func:
+                    return callable_method(spec.attr_name, func, config.resolver_id)
+
+        return callable_method(spec.func, spec.func, None)
+
+    def _search_name(self, name) -> Generator["Callable", None, None]:
+        for config in self.items:
+            if name not in config.all_attrs:
+                continue
+
+            func = getattr(config.obj, name)
+            if not callable(func):
+                yield attr_method(name, config.obj, config.resolver_id)
+                continue
+
+            if getattr(func, "_is_sm_event", False):
+                yield event_method(name, func, config.resolver_id)
+                continue
+
+            yield callable_method(name, func, config.resolver_id)
+
+
+def callable_method(attribute, a_callable, resolver_id) -> Callable:
+    method = SignatureAdapter.wrap(a_callable)
+    method.unique_key = f"{attribute}@{resolver_id}"  # type: ignore[attr-defined]
+    method.__name__ = a_callable.__name__
+    method.__doc__ = a_callable.__doc__
+    return method
+
+
+def attr_method(attribute, obj, resolver_id) -> Callable:
+    getter = attrgetter(attribute)
+
+    def method(*args, **kwargs):
+        return getter(obj)
+
+    method.unique_key = f"{attribute}@{resolver_id}"  # type: ignore[attr-defined]
+    return method
+
+
+def event_method(attribute, func, resolver_id) -> Callable:
+    def method(*args, **kwargs):
+        kwargs.pop("machine", None)
+        return func(*args, **kwargs)
+
+    method.unique_key = f"{attribute}@{resolver_id}"  # type: ignore[attr-defined]
+    return method
+
+
+def resolver_factory_from_objects(*objects: Tuple[Any, ...]):
+    return Listeners.from_listeners(Listener.from_obj(o) for o in objects)