python-statemachine 2.1.1__tar.gz → 2.2.0__tar.gz

{python_statemachine-2.1.1 → python_statemachine-2.2.0}/PKG-INFO

@@ -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.1.1 → python_statemachine-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-statemachine"
-version = "2.1.1"
+version = "2.2.0"
 description = "Python Finite State Machines made easy."
 authors = ["Fernando Macedo <fgmacedo@gmail.com>"]
 maintainers = [
@@ -26,6 +26,7 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Topic :: Software Development :: Libraries"
 ]
 
@@ -33,40 +34,41 @@ classifiers = [
 diagrams = ["pydot"]
 
 [tool.poetry.dependencies]
-python = ">=3.7, <3.12"
+python = ">=3.9, <3.13"
 
 [tool.poetry.group.dev.dependencies]
-pytest = "^7.2.0"
-pytest-cov = "^4.0.0"
-pytest-sugar = "^0.9.6"
-pydot = "^1.4.2"
-ruff = "^0.0.257"
-pre-commit = "^2.21.0"
-mypy = "^0.991"
-black = "^22.12.0"
-pdbpp = "^0.10.3"
+pytest = "^8.1.1"
+pytest-cov = "^5.0.0"
+pytest-sugar = "^1.0.0"
+pydot = "^2.0.0"
+ruff = "^0.3.7"
+pre-commit = "^3.7.0"
+mypy = "^1.9.0"
 pytest-mock = "^3.10.0"
+pytest-profiling = "^1.7.0"
+pytest-benchmark = "^4.0.0"
 
 [tool.poetry.group.docs.dependencies]
-Sphinx = "4.5.0"
-sphinx-rtd-theme = "1.1.1"
-myst-parser = "^0.18.1"
-sphinx-gallery = "^0.11.1"
-pillow = "^9.4.0"
-sphinx-autobuild = "^2021.3.14"
+Sphinx = "7.2.6"
+sphinx-rtd-theme = "2.0.0"
+myst-parser = "^2.0.0"
+sphinx-gallery = "^0.15.0"
+pillow = "^10.3.0"
+sphinx-autobuild = "^2024.4.16"
 
 [build-system]
 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"
+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"
 doctest_optionflags = "ELLIPSIS IGNORE_EXCEPTION_DETAIL NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL"
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.12"
 warn_return_any = true
 warn_unused_configs = true
+disable_error_code = "annotation-unchecked"
 
 [[tool.mypy.overrides]]
 module = [
@@ -87,24 +89,8 @@ max-line-length = 99
 [tool.ruff]
 src = ["statemachine"]
 
-# Enable Pyflakes and pycodestyle rules.
-select = [
-    "E", # pycodestyle errors
-    "W", # pycodestyle warnings
-    "F", # pyflakes
-    "I", # isort
-    "UP", # pyupgrade
-    "C",  # flake8-comprehensions
-    "B",  # flake8-bugbear
-    "PT", # flake8-pytest-style
-]
-ignore = [
-    "UP006", # `use-pep585-annotation` Requires Python3.9+
-    "UP035", # `use-pep585-annotation` Requires Python3.9+
-    "UP038", # `use-pep585-annotation` Requires Python3.9+
-]
-
 line-length = 99
+target-version = "py312"
 
 # Exclude a variety of commonly ignored directories.
 exclude = [
@@ -127,19 +113,41 @@ exclude = [
     "venv",
 ]
 
+[tool.ruff.lint]
+
+# Enable Pyflakes and pycodestyle rules.
+select = [
+    "E", # pycodestyle errors
+    "W", # pycodestyle warnings
+    "F", # pyflakes
+    "I", # isort
+    "UP", # pyupgrade
+    "C",  # flake8-comprehensions
+    "B",  # flake8-bugbear
+    "PT", # flake8-pytest-style
+]
+ignore = [
+    "UP006", # `use-pep585-annotation` Requires Python3.9+
+    "UP035", # `use-pep585-annotation` Requires Python3.9+
+    "UP038", # `use-pep585-annotation` Requires Python3.9+
+]
+
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 
-# Assume Python 3.11.
-target-version = "py311"
+[tool.ruff.lint.per-file-ignores]
+# Ignore `E402` (import violations) in all `__init__.py` files, and in `path/to/file.py`.
+"__init__.py" = ["E402"]
+"path/to/file.py" = ["E402"]
+"tests/examples/**.py" = ["B018"]
 
-[tool.ruff.mccabe]
+[tool.ruff.lint.mccabe]
 max-complexity = 6
 
-[tool.ruff.isort]
+[tool.ruff.lint.isort]
 force-single-line = true
 
-[tool.ruff.pydocstyle]
+[tool.ruff.lint.pydocstyle]
 # Use Google-style docstrings.
 convention = "google"
 

{python_statemachine-2.1.1 → python_statemachine-2.2.0}/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"]

python_statemachine-2.2.0/statemachine/callbacks.py

@@ -0,0 +1,285 @@
+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 .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:
+    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.
+
+    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=None,
+    ):
+        self.func = func
+        self.suppress_errors = suppress_errors
+        self.cond = cond
+        self.expected_value = expected_value
+        self.priority = priority
+
+    def __repr__(self):
+        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
+
+    def __hash__(self):
+        return id(self)
+
+    def _update_func(self, func):
+        self.func = func
+
+    def _wrap_callable(self, func, _expected_value):
+        return func
+
+    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(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,
+            )
+
+
+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 _wrap_callable(self, func, expected_value):
+        def bool_wrapper(*args, **kwargs):
+            return bool(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
+
+    def __repr__(self):
+        return f"{type(self).__name__}({self.items!r}, factory={self.factory!r})"
+
+    def __str__(self):
+        return ", ".join(str(c) for c in self)
+
+    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.
+
+        """
+        callback = self._add(func, **kwargs)
+        if not getattr(func, "_callbacks_to_update", None):
+            func._callbacks_to_update = set()
+        func._callbacks_to_update.add(callback._update_func)
+        func._is_event = is_event
+        func._transitions = transitions
+
+        return func
+
+    def __call__(self, callback):
+        """Allows usage of the callback list as a decorator."""
+        return self._add_unbounded_callback(callback)
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def clear(self):
+        self.items = []
+
+    def _add(self, func, **kwargs):
+        meta = self.factory(func, **kwargs)
+
+        if meta in self.items:
+            return
+
+        self.items.append(meta)
+        return meta
+
+    def add(self, callbacks, **kwargs):
+        if callbacks is None:
+            return self
+
+        unprepared = ensure_iterable(callbacks)
+        for func in unprepared:
+            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)
+            )

{python_statemachine-2.1.1 → python_statemachine-2.2.0}/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}"

python_statemachine-2.2.0/statemachine/dispatcher.py

@@ -0,0 +1,156 @@
+from collections import namedtuple
+from operator import attrgetter
+from typing import Any
+from typing import Generator
+
+from .signature import SignatureAdapter
+
+
+class ObjectConfig(namedtuple("ObjectConfig", "obj skip_attrs resolver_id")):
+    """Configuration for objects passed to resolver_factory.
+
+    Args:
+        obj: Any object that will serve as lookup for attributes.
+        skip_attrs: Protected attrs that will be ignored on the search.
+    """
+
+    @classmethod
+    def from_obj(cls, obj, skip_attrs=None):
+        if isinstance(obj, ObjectConfig):
+            return obj
+        else:
+            return cls(obj, skip_attrs or set(), str(id(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 wrap(self):  # pragma: no cover
+        pass
+
+    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)
+
+
+class CallableSearchResult(WrapSearchResult):
+    def __init__(self, attribute, a_callable, resolver_id) -> None:
+        self.a_callable = a_callable
+        super().__init__(attribute, resolver_id)
+
+    def wrap(self):
+        return SignatureAdapter.wrap(self.a_callable)
+
+
+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 wrapper(*args, **kwargs):
+            return getter(self.obj)
+
+        return wrapper
+
+
+class EventSearchResult(WrapSearchResult):
+    def __init__(self, attribute, func, resolver_id) -> None:
+        self.func = func
+        super().__init__(attribute, resolver_id)
+
+    def wrap(self):
+        "Events already have the 'machine' parameter defined."
+
+        def wrapper(*args, **kwargs):
+            kwargs.pop("machine", None)
+            return self.func(*args, **kwargs)
+
+        return wrapper
+
+
+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
+
+        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
+
+    if callable(attr):
+        yield _search_callable_attr_is_callable(attr, configs)
+        return
+
+    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)