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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-statemachine
-Version: 2.1.1
+Version: 2.2.0
 Summary: Python Finite State Machines made easy.
 Home-page: https://github.com/fgmacedo/python-statemachine
 License: MIT
@@ -8,21 +8,17 @@ Author: Fernando Macedo
 Author-email: fgmacedo@gmail.com
 Maintainer: Fernando Macedo
 Maintainer-email: fgmacedo@gmail.com
-Requires-Python: >=3.7,<3.12
+Requires-Python: >=3.9,<3.13
 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.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: Programming Language :: Python :: 3.9
 Classifier: Topic :: Software Development :: Libraries
 Provides-Extra: diagrams
 Description-Content-Type: text/markdown

python_statemachine-2.2.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+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,,

{python_statemachine-2.1.1.dist-info → python_statemachine-2.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.4.0
+Generator: poetry-core 1.6.1
 Root-Is-Purelib: true
 Tag: py3-none-any

statemachine/__init__.py

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

statemachine/callbacks.py

@@ -1,11 +1,57 @@
+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
-from .exceptions import InvalidDefinition
 from .i18n import _
 from .utils import ensure_iterable
 
 
+class CallbackPriority(IntEnum):
+    GENERIC = 0
+    INLINE = 10
+    DECORATOR = 20
+    NAMING = 30
+    AFTER = 40
+
+
+def allways_true(*args, **kwargs):
+    return True
+
+
 class CallbackWrapper:
-    """A thin wrapper that ensures the target callback is a proper callable.
+    def __init__(
+        self,
+        callback: Callable,
+        condition: Callable,
+        meta: "CallbackMeta",
+        unique_key: str,
+    ) -> None:
+        self._callback = callback
+        self.condition = condition
+        self.meta = meta
+        self.unique_key = unique_key
+
+    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
+
+    def __call__(self, *args, **kwargs):
+        return self._callback(*args, **kwargs)
+
+
+class CallbackMeta:
+    """A thin wrapper that register info about actions and guards.
 
     At first, `func` can be a string or a callable, and even if it's already
     a callable, his signature can mismatch.
@@ -14,21 +60,28 @@ class CallbackWrapper:
     call is performed, to allow the proper callback resolution.
     """
 
-    def __init__(self, func, suppress_errors=False, cond=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 = Callbacks(factory=ConditionWrapper).add(cond)
-        self._callback = None
-        self._resolver_id = None
+        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)
 
     def __eq__(self, other):
-        return self.func == other.func and self._resolver_id == other._resolver_id
+        return self.func == other.func
 
     def __hash__(self):
         return id(self)
@@ -36,7 +89,10 @@ class CallbackWrapper:
     def _update_func(self, func):
         self.func = func
 
-    def setup(self, resolver):
+    def _wrap_callable(self, func, _expected_value):
+        return func
+
+    def build(self, resolver) -> Generator["CallbackWrapper", None, None]:
         """
         Resolves the `func` into a usable callable.
 
@@ -44,41 +100,54 @@ class CallbackWrapper:
             resolver (callable): A method responsible to build and return a valid callable that
                 can receive arbitrary parameters like `*args, **kwargs`.
         """
-        self.cond.setup(resolver)
-        try:
-            self._resolver_id = getattr(resolver, "id", id(resolver))
-            self._callback = resolver(self.func)
-            return True
-        except AttrNotFound:
-            if not self.suppress_errors:
-                raise
-            return False
-
-    def __call__(self, *args, **kwargs):
-        if self._callback is None:
-            raise InvalidDefinition(
-                _("Callback {!r} not property configured.").format(self)
+        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,
             )
-        return self._callback(*args, **kwargs)
 
 
-class ConditionWrapper(CallbackWrapper):
-    def __init__(self, func, suppress_errors=False, expected_value=True):
-        super().__init__(func, suppress_errors)
-        self.expected_value = expected_value
+class BoolCallbackMeta(CallbackMeta):
+    """A thin wrapper that register info about actions and guards.
+
+    At first, `func` can be a string or a callable, and even if it's already
+    a callable, his signature can mismatch.
+
+    After instantiation, `.setup(resolver)` must be called before any real
+    call is performed, to allow the proper callback resolution.
+    """
+
+    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 __call__(self, *args, **kwargs):
-        return bool(super().__call__(*args, **kwargs)) == self.expected_value
+    def _wrap_callable(self, func, expected_value):
+        def bool_wrapper(*args, **kwargs):
+            return bool(func(*args, **kwargs)) == expected_value
 
+        return bool_wrapper
 
-class Callbacks:
-    def __init__(self, resolver=None, factory=CallbackWrapper):
-        self.items = []
-        self._resolver = resolver
+
+class CallbackMetaList:
+    """List of `CallbackMeta` instances"""
+
+    def __init__(self, factory=CallbackMeta):
+        self.items: List[CallbackMeta] = []
         self.factory = factory
 
     def __repr__(self):
@@ -87,13 +156,6 @@ class Callbacks:
     def __str__(self):
         return ", ".join(str(c) for c in self)
 
-    def setup(self, resolver):
-        """Validate configurations"""
-        self._resolver = resolver
-        self.items = [
-            callback for callback in self.items if callback.setup(self._resolver)
-        ]
-
     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.
@@ -127,6 +189,7 @@ class Callbacks:
         return func
 
     def __call__(self, callback):
+        """Allows usage of the callback list as a decorator."""
         return self._add_unbounded_callback(callback)
 
     def __iter__(self):
@@ -135,31 +198,14 @@ class Callbacks:
     def clear(self):
         self.items = []
 
-    def call(self, *args, **kwargs):
-        return [
-            callback(*args, **kwargs)
-            for callback in self.items
-            if callback.cond.all(*args, **kwargs)
-        ]
-
-    def all(self, *args, **kwargs):
-        return all(condition(*args, **kwargs) for condition in self)
-
-    def _add(self, func, resolver=None, prepend=False, **kwargs):
-        resolver = resolver or self._resolver
+    def _add(self, func, **kwargs):
+        meta = self.factory(func, **kwargs)
 
-        callback = self.factory(func, **kwargs)
-        if resolver is not None and not callback.setup(resolver):
+        if meta in self.items:
             return
 
-        if callback in self.items:
-            return
-
-        if prepend:
-            self.items.insert(0, callback)
-        else:
-            self.items.append(callback)
-        return callback
+        self.items.append(meta)
+        return meta
 
     def add(self, callbacks, **kwargs):
         if callbacks is None:
@@ -170,3 +216,70 @@ class Callbacks:
             self._add(func, **kwargs)
 
         return self
+
+
+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, 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)
+            insort(self.items, callback)
+
+    def add(self, items: CallbackMetaList, resolver: Callable):
+        """Validate configurations"""
+        for item in items:
+            self._add(item, resolver)
+        return self
+
+    def call(self, *args, **kwargs):
+        return [
+            callback(*args, **kwargs) for callback in self if callback.condition(*args, **kwargs)
+        ]
+
+    def all(self, *args, **kwargs):
+        return all(condition(*args, **kwargs) for condition in self)
+
+
+class CallbacksRegistry:
+    def __init__(self) -> None:
+        self._registry: Dict[CallbackMetaList, CallbacksExecutor] = defaultdict(CallbacksExecutor)
+
+    def register(self, meta_list: CallbackMetaList, resolver):
+        executor_list = self[meta_list]
+        executor_list.add(meta_list, resolver)
+        return executor_list
+
+    def clear(self):
+        self._registry.clear()
+
+    def __getitem__(self, meta_list: CallbackMetaList) -> CallbacksExecutor:
+        return self._registry[meta_list]
+
+    def check(self, meta_list: CallbackMetaList):
+        executor = self[meta_list]
+        for meta in meta_list:
+            if meta.suppress_errors:
+                continue
+
+            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}"

statemachine/dispatcher.py

@@ -1,13 +1,12 @@
 from collections import namedtuple
-from functools import wraps
 from operator import attrgetter
+from typing import Any
+from typing import Generator
 
-from .exceptions import AttrNotFound
-from .i18n import _
 from .signature import SignatureAdapter
 
 
-class ObjectConfig(namedtuple("ObjectConfig", "obj skip_attrs")):
+class ObjectConfig(namedtuple("ObjectConfig", "obj skip_attrs resolver_id")):
     """Configuration for objects passed to resolver_factory.
 
     Args:
@@ -16,86 +15,142 @@ class ObjectConfig(namedtuple("ObjectConfig", "obj skip_attrs")):
     """
 
     @classmethod
-    def from_obj(cls, obj):
+    def from_obj(cls, obj, skip_attrs=None):
         if isinstance(obj, ObjectConfig):
             return obj
         else:
-            return cls(obj, set())
+            return cls(obj, skip_attrs or set(), str(id(obj)))
 
 
-def _get_func_by_attr(attr, *configs):
-    for config in configs:
-        if attr in config.skip_attrs:
-            continue
-        func = getattr(config.obj, attr, None)
-        if func is not None:
-            break
-    else:
-        raise AttrNotFound(
-            _("Did not found name '{}' from model or statemachine").format(attr)
-        )
-    return func, config.obj
+class WrapSearchResult:
+    def __init__(self, attribute, resolver_id) -> None:
+        self.attribute = attribute
+        self.resolver_id = resolver_id
+        self._cache = None
+        self.unique_key = f"{attribute}@{resolver_id}"
 
+    def __repr__(self):
+        return f"{type(self).__name__}({self.unique_key})"
 
-def _build_attr_wrapper(attr: str, obj):
-    # if `attr` is not callable, then it's an attribute or property,
-    # so `func` contains it's current value.
-    # we'll build a method that get's the fresh value for each call
-    getter = attrgetter(attr)
+    def wrap(self):  # pragma: no cover
+        pass
 
-    def wrapper(*args, **kwargs):
-        return getter(obj)
+    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 wrapper
 
+class CallableSearchResult(WrapSearchResult):
+    def __init__(self, attribute, a_callable, resolver_id) -> None:
+        self.a_callable = a_callable
+        super().__init__(attribute, resolver_id)
 
-def _build_sm_event_wrapper(func):
-    "Events already have the 'machine' parameter defined."
+    def wrap(self):
+        return SignatureAdapter.wrap(self.a_callable)
 
-    def wrapper(*args, **kwargs):
-        kwargs.pop("machine", None)
-        return func(*args, **kwargs)
 
-    return wrapper
+class AttributeCallableSearchResult(WrapSearchResult):
+    def __init__(self, attribute, obj, resolver_id) -> None:
+        self.obj = obj
+        super().__init__(attribute, resolver_id)
 
+    def wrap(self):
+        # if `attr` is not callable, then it's an attribute or property,
+        # so `func` contains it's current value.
+        # we'll build a method that get's the fresh value for each call
+        getter = attrgetter(self.attribute)
 
-def ensure_callable(attr, *objects):
-    """Ensure that `attr` is a callable, if not, tries to retrieve one from any of the given
-    `objects`.
+        def wrapper(*args, **kwargs):
+            return getter(self.obj)
 
-    Args:
-        attr (str or callable): A property/method name or a callable.
-        objects: A list of objects instances that will serve as lookup for the given attr.
-            The result `callable`, if any, will be a wrapper to the first object's attr that
-            has the given ``attr``.
-    """
-    if callable(attr) or isinstance(attr, property):
-        return SignatureAdapter.wrap(attr)
+        return wrapper
 
-    # Setup configuration if not present to normalize the internal API
-    configs = [ObjectConfig.from_obj(obj) for obj in objects]
 
-    func, obj = _get_func_by_attr(attr, *configs)
+class EventSearchResult(WrapSearchResult):
+    def __init__(self, attribute, func, resolver_id) -> None:
+        self.func = func
+        super().__init__(attribute, resolver_id)
 
-    if not callable(func):
-        return _build_attr_wrapper(attr, obj)
+    def wrap(self):
+        "Events already have the 'machine' parameter defined."
 
-    if getattr(func, "_is_sm_event", False):
-        return _build_sm_event_wrapper(func)
+        def wrapper(*args, **kwargs):
+            kwargs.pop("machine", None)
+            return self.func(*args, **kwargs)
 
-    return SignatureAdapter.wrap(func)
+        return wrapper
 
 
-def resolver_factory(*objects):
-    """Factory that returns a configured resolver."""
+def _search_callable_attr_is_property(
+    attr, configs: tuple[ObjectConfig]
+) -> "WrapSearchResult | None":
+    # if the attr is a property, we'll try to find the object that has the
+    # property on the configs
+    attr_name = attr.fget.__name__
+    for obj, _skip_attrs, resolver_id in configs:
+        func = getattr(type(obj), attr_name, None)
+        if func is not None and func is attr:
+            return AttributeCallableSearchResult(attr_name, obj, resolver_id)
+    return None
+
+
+def _search_callable_attr_is_callable(attr, configs: tuple[ObjectConfig]) -> WrapSearchResult:
+    # if the attr is an unbounded method, we'll try to find the bounded method
+    # on the configs
+    if not hasattr(attr, "__self__"):
+        for obj, _skip_attrs, resolver_id in configs:
+            func = getattr(obj, attr.__name__, None)
+            if func is not None and func.__func__ is attr:
+                return CallableSearchResult(attr.__name__, func, resolver_id)
+
+    return CallableSearchResult(attr, attr, None)
+
+
+def _search_callable_in_configs(
+    attr, configs: tuple[ObjectConfig]
+) -> Generator[WrapSearchResult, None, None]:
+    for obj, skip_attrs, resolver_id in configs:
+        if attr in skip_attrs:
+            continue
 
-    objects = [ObjectConfig.from_obj(obj) for obj in objects]
+        if not hasattr(obj, attr):
+            continue
+
+        func = getattr(obj, attr)
+        if not callable(func):
+            yield AttributeCallableSearchResult(attr, obj, resolver_id)
+
+        if getattr(func, "_is_sm_event", False):
+            yield EventSearchResult(attr, func, resolver_id)
+
+        yield CallableSearchResult(attr, func, resolver_id)
+
+
+def search_callable(attr, configs: tuple) -> Generator[WrapSearchResult, None, None]:  # noqa: C901
+    if isinstance(attr, property):
+        result = _search_callable_attr_is_property(attr, configs)
+        if result is not None:
+            yield result
+        return
 
-    @wraps(ensure_callable)
-    def wrapper(attr):
-        return ensure_callable(attr, *objects)
+    if callable(attr):
+        yield _search_callable_attr_is_callable(attr, configs)
+        return
 
-    resolver_id = ".".join(str(id(obj.obj)) for obj in objects)
-    wrapper.id = resolver_id
+    yield from _search_callable_in_configs(attr, configs)
+
+
+def resolver_factory(objects: tuple[ObjectConfig]):
+    """Factory that returns a configured resolver."""
+
+    def wrapper(attr) -> Generator[WrapSearchResult, None, None]:
+        yield from search_callable(attr, objects)
 
     return wrapper
+
+
+def resolver_factory_from_objects(*objects: tuple[Any]):
+    configs = tuple(ObjectConfig.from_obj(o) for o in objects)
+    return resolver_factory(configs)