python-statemachine 3.2.0__py3-none-any.whl → 3.2.2__py3-none-any.whl

{python_statemachine-3.2.0.dist-info → python_statemachine-3.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-statemachine
-Version: 3.2.0
+Version: 3.2.2
 Summary: Python Finite State Machines made easy.
 Project-URL: homepage, https://github.com/fgmacedo/python-statemachine
 Author-email: Fernando Macedo <fgmacedo@gmail.com>
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Home Automation
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
@@ -37,15 +38,15 @@ Description-Content-Type: text/markdown
 [![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)
-[![Coverage report](https://codecov.io/gh/fgmacedo/python-statemachine/branch/develop/graph/badge.svg)](https://codecov.io/gh/fgmacedo/python-statemachine)
+[![Coverage report](https://codecov.io/gh/fgmacedo/python-statemachine/branch/main/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)
+[![GitHub commits since last release](https://img.shields.io/github/commits-since/fgmacedo/python-statemachine/latest?sort=semver)](https://github.com/fgmacedo/python-statemachine/compare/latest...main)
 
 Expressive [statecharts](https://statecharts.dev/) and [FSMs](https://en.wikipedia.org/wiki/Finite-state_machine) for modern Python.
 
 <div align="center">
 
-![](https://github.com/fgmacedo/python-statemachine/blob/develop/docs/images/python-statemachine.png?raw=true)
+![](https://github.com/fgmacedo/python-statemachine/blob/main/docs/images/python-statemachine.png?raw=true)
 
 </div>
 
@@ -128,7 +129,7 @@ Generate a diagram or get a text representation with f-strings:
 sm._graph().write_png("traffic_light.png")
 ```
 
-![](https://raw.githubusercontent.com/fgmacedo/python-statemachine/develop/docs/images/readme_trafficlightmachine.png)
+![](https://raw.githubusercontent.com/fgmacedo/python-statemachine/main/docs/images/readme_trafficlightmachine.png)
 
 Parameters are injected into callbacks automatically — the library inspects the
 signature and provides only the arguments each callback needs:

python_statemachine-3.2.2.dist-info/RECORD

@@ -0,0 +1,73 @@
+statemachine/__init__.py,sha256=KyQKpJwLYHOkVETTQ60dx3HBZPE2ltpSTS0rb0jH1vk,445
+statemachine/callbacks.py,sha256=k0RfCmQlDGMaKE3ZHlot9hiJ0eHykL1dwKM4Oerj--o,14994
+statemachine/configuration.py,sha256=MblvaBwEOyooYc4Vzo-qeryF9sEmx9mdtZDY0Gf_uRU,5991
+statemachine/dispatcher.py,sha256=QeQ2CNWzHxeFDXiW9AtxrSD4WDUio9hauBgj0BLK1ps,8469
+statemachine/event.py,sha256=vmcoBIyiRtBwX_7i4efKQKg6-3-3nIHDGM9ThAFp9-I,8361
+statemachine/event_data.py,sha256=dh9nR1gi23fhlfjUizMbqOmVbZP1RlnAndrAhPHXXqg,3978
+statemachine/events.py,sha256=cRDfZXF-7FiA6yEQtxmwMJl3mnbfkO6wagOpyaBakdY,1288
+statemachine/exceptions.py,sha256=q1ZOqBmNv34mtHAzv4XHBV67BHldxtEpu3uoeTXiEYI,1317
+statemachine/factory.py,sha256=AjDdbNst0Avf0M9ypohE_uBusZGSpIWOPz0aajLf1Wg,19230
+statemachine/graph.py,sha256=ngQ31YAetfQLQvdBU5cHwLQcD-wJL92axPJ2sUeCu1g,1999
+statemachine/i18n.py,sha256=NLvGseaORmQ0G-V_J8tkjoxh_piWMOm2CI6mBQpLamc,362
+statemachine/invoke.py,sha256=5B7XNvBFnQaKByoYM1VbRlJvJyEwXn1C0QKUCaRjmpU,24908
+statemachine/mixins.py,sha256=8qxZZfBwVdFcr3oPFVWHGzgmAubH6VgQus5x3c6VEE0,1706
+statemachine/model.py,sha256=OylI3FjMiHpYyDl9mtK1zEJMeSvemaN4giQDonpc8kI,211
+statemachine/orderedset.py,sha256=a2FqEAAKja6E0Bu5O5Lzbd18V4hECrrCbinguIdzTjk,2794
+statemachine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/registry.py,sha256=-CYm8bdZN5ro9Pc806XPJ7ZfT3YrcSB9cOZ83AnTFdY,829
+statemachine/signature.py,sha256=-IiRYJScx4cDKny3ictQvHwQBbaCyxWpRKSgQksMT0E,9834
+statemachine/spec_parser.py,sha256=jxskD6Mxs--b5q_f3gAZAxD9morER7nK7My0UwvI0h4,18982
+statemachine/state.py,sha256=vm42WSZ-gNSOFgk9L9sqUIA1YAkngPaxu-VS7qh0dyI,17349
+statemachine/statemachine.py,sha256=yoLZh7Q4evCCOkKmaSNiozGDN27W1l_HPb58ricJ_Oo,21129
+statemachine/states.py,sha256=NRHtATtb-2Ac2nwzSn5OfHwzOSxI2FLeNR8o1v84USs,4827
+statemachine/transition.py,sha256=JtGABHJ6inZrneI70bgu4ir2BZ2YQagcYX9l6TcsHSc,6912
+statemachine/transition_list.py,sha256=zZuGWB86fL2ux-orIE7CdeCcnhaS5p2njIy8h2SuyVY,4361
+statemachine/transition_mixin.py,sha256=i9ZLDGPgE2zIkTn7IAEMjscn1gnI-HJMtxX-YG447tY,3002
+statemachine/utils.py,sha256=taCgrsRDcQQLweyq607AVZyI0NMukRP-HGpO8TiVNgk,1527
+statemachine/contrib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/contrib/timeout.py,sha256=VXkdLpxNeUKihkbtLv8XTWdG-meQlSFtxJfcxXgV8Uw,2251
+statemachine/contrib/weighted.py,sha256=lzcopcY0EzjJb-N4APJJc7AlgZIPtthTbBizKaDtOIk,6787
+statemachine/contrib/diagram/__init__.py,sha256=8nnEIE_Lk4tX_sUzB8v0RqaJwHbbMgXYtfkWytNgfVU,8042
+statemachine/contrib/diagram/__main__.py,sha256=iPpiz09xKqtAjrhONS99OYp6R2dQ6Anbhw1qPIN8ELo,80
+statemachine/contrib/diagram/extract.py,sha256=0X9RsHFgQgxDGaz6GGbFnJacZyxRO7sV7PolpWiFbdw,9869
+statemachine/contrib/diagram/formatter.py,sha256=4ed_i_fFsbDnBUZG9gRlaKyvTR0IWFuU65OGPc1VrZk,4745
+statemachine/contrib/diagram/graphviz.py,sha256=G7-gij3uC_Lsy5ondUTcJud8mLvK4443SHRma5nSyUs,2342
+statemachine/contrib/diagram/model.py,sha256=pn7dzrt8U8TOn4A-Jg1Rc3b1UUlTgs75WfR2x-xtEuc,1451
+statemachine/contrib/diagram/sphinx_ext.py,sha256=c_TAZAh4hKVk_ldoDMDilQXO-SnVdku9QHfYm-w0q4o,11348
+statemachine/contrib/diagram/renderers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/contrib/diagram/renderers/dot.py,sha256=VkWMVP1DLl1YUEUZVmBVSNQVbAG516v3hQcK4PePWD8,19772
+statemachine/contrib/diagram/renderers/mermaid.py,sha256=3N1z0klonL768exBcWp3WLMuWUgCpRso2UhpdnvHYhY,13424
+statemachine/contrib/diagram/renderers/table.py,sha256=PLVfwTIZHtv7uK3smAfN1owAOEunkBRHyEkh5ygVcfw,3711
+statemachine/engines/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statemachine/engines/async_.py,sha256=VmN3jc6vQmMsGOYPAgSS03ZIKuTZzuUCK4eCgxwG7Rg,22641
+statemachine/engines/base.py,sha256=PRTdKGxsZU1Fgw9hddoAdhmu9JSVG5XJpqt8srIu7ps,38233
+statemachine/engines/sync.py,sha256=Z3hP_vqbi6BdoKvQBS92pjb0P8UdEhnzJwZyrklVxnw,12757
+statemachine/io/__init__.py,sha256=BMA91t_PY0fmsjIfMeq8pQ6Cs4KS1gxyrZj_DtMntRA,2769
+statemachine/io/actions.py,sha256=rxObGx0xbXMooRVtGGaoeqmtTWl93AFQGv2gGAMCi4w,24549
+statemachine/io/builder.py,sha256=yNaQrtFfbs55uRd-loZ-Vs5061liwM-np-B_2ZuJO1I,8350
+statemachine/io/class_factory.py,sha256=H8zxsfrjLw7L_X2g2hoXb2CjpHxTftsoBmPBWIcen-4,9557
+statemachine/io/evaluators.py,sha256=A6g_o_8GuYMcSFOWJ1dsVRzr06ddikybCI-xAbY3vhY,12178
+statemachine/io/interpreter.py,sha256=FQUXUlt1PSPzFHyixiLNXcN-7KYBM_i5RAFPRPLu6TE,5567
+statemachine/io/invoke.py,sha256=iPYck_vP2vh7-bRXkMwOYHryrXCqWxNhLzFE8uiG6L8,10632
+statemachine/io/loader.py,sha256=g_X6NgI2mudpwHN6EoDCaDv4HsryFpO93lExPo_lOdU,7054
+statemachine/io/model.py,sha256=mTJvlbDJndX78pHfyDdEaqc9zTBWVA-OFA5xzVZbz6Y,8695
+statemachine/io/native.py,sha256=HjIOKDQIGExLMglcm8VGbga71Y1Zw-pBbKYWP-y_oiY,13758
+statemachine/io/ports.py,sha256=XoIAQfMujkEnH38t4iu766yiHycb89TNrA3owtBJU2U,2956
+statemachine/io/system_variables.py,sha256=yYoAJTCm1uNIp63Dyw0wSUKDJbg1gQGgWKfvBt6LyGQ,7278
+statemachine/io/validation.py,sha256=6qiDx0gMkPAehSxJu_mrW4nEF_sebHwa5Dr_njclRcw,1662
+statemachine/io/json/__init__.py,sha256=tFWoOrD9RuKEqkOpI0XifNRP7rguSGY4k-RaSCV_GnM,38
+statemachine/io/json/reader.py,sha256=40V5T-yB1i0Qg-MkK00KHRi7eDQQk4ajfzmKtKXylHs,789
+statemachine/io/schemas/statechart.schema.json,sha256=ngxuIIegKLZWg8MUozQkktE8TbhUO57ZlzEbs7mKdRs,8132
+statemachine/io/scxml/__init__.py,sha256=0CMGGfpOaindNGb6VOkMn7Z4nGqK3iJ3sMZcS531Kaw,972
+statemachine/io/scxml/processor.py,sha256=wk6Tt7yTf2GxCwx5S3eT9NInMsObspPmpQFLTNkacSk,1532
+statemachine/io/scxml/reader.py,sha256=gp6tglHXdNxnPa9jNoo9jvRqNUfIr3O_DjCQJQijbD4,17821
+statemachine/io/yaml/__init__.py,sha256=oMapUmquV7hb5qIGMfjDZmDHNq2fqqjJw6LOgGNKeC4,79
+statemachine/io/yaml/reader.py,sha256=mf2FaBttxQuCniSM-vHhSYDGaNLQdzRLoMUHO2kZ0xA,2208
+statemachine/locale/en/LC_MESSAGES/statemachine.po,sha256=fv26VIkXR_Nn_Ki-CdW0_SPjBQqGdV6oLXqFhmUrOiI,6466
+statemachine/locale/hi_IN/LC_MESSAGES/statemachine.po,sha256=WQieKolnjtonMT2ld39F4MTgzjBirm7jsMnXWIcB2Qg,10512
+statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po,sha256=j-sqfIZTSrS6we4oOCXLosv3DIqdy7NE7rFLIuHiHBk,7619
+statemachine/locale/zh_CN/LC_MESSAGES/statemachine.po,sha256=1KQiUND1iII4HXW20sheHWgkyeQ-EbWI0kcZGsdsuIg,7035
+python_statemachine-3.2.2.dist-info/METADATA,sha256=AoxoXlVxhdLMJvO1XPPdSPkl4KabGJQl3AzvGJ4-9aI,12682
+python_statemachine-3.2.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+python_statemachine-3.2.2.dist-info/licenses/LICENSE,sha256=zcP7TsJMqaFxuTvLRZPT7nJl3_ppjxR9Z76BE9pL5zc,1074
+python_statemachine-3.2.2.dist-info/RECORD,,

{python_statemachine-3.2.0.dist-info → python_statemachine-3.2.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any

statemachine/__init__.py

@@ -8,7 +8,7 @@ from .statemachine import TModel
 
 __author__ = """Fernando Macedo"""
 __email__ = "fgmacedo@gmail.com"
-__version__ = "3.2.0"
+__version__ = "3.2.2"
 
 __all__ = [
     "StateChart",

statemachine/callbacks.py

@@ -8,6 +8,8 @@ from enum import IntFlag
 from enum import auto
 from functools import partial
 from inspect import isawaitable
+from inspect import isfunction
+from typing import Any
 
 from .exceptions import AttrNotFound
 from .i18n import _
@@ -18,6 +20,11 @@ def allways_true(*args, **kwargs):
     return True
 
 
+def is_unbounded_reference(func: Any) -> bool:
+    """Whether ``func`` is a function that a `CallbackSpec` holds by object."""
+    return isfunction(func) and hasattr(func, "attr_name")
+
+
 class CallbackPriority(IntEnum):
     GENERIC = 0
     INLINE = 10
@@ -103,6 +110,10 @@ class CallbackSpec:
             and self.reference == SpecReference.NAME
         )
 
+        self.lookup_name: str = self.attr_name
+        """Attribute of the machine holding an unbounded callable. Differs from `attr_name`
+        when nested state bodies share the name and each function is stored apart."""
+
     def __repr__(self):
         return f"{type(self).__name__}({self.func!r}, is_convention={self.is_convention!r})"
 

statemachine/contrib/diagram/__init__.py

@@ -5,6 +5,9 @@ from urllib.request import urlopen
 
 from .extract import extract
 from .formatter import formatter as formatter
+from .graphviz import GraphvizError as GraphvizError
+from .graphviz import GraphvizNotFoundError as GraphvizNotFoundError
+from .graphviz import run_graphviz
 
 if TYPE_CHECKING:
     from .renderers.dot import DotRendererConfig
@@ -207,13 +210,19 @@ def write_image(qualname, out, events=None, fmt=None):
         else:
             with open(out, "w") as f:
                 f.write(text)
+    elif out == "-":
+        sys.stdout.buffer.write(_render_image(machine, "svg"))
     else:
-        graph = DotGraphMachine(machine).get_graph()
-        if out == "-":
-            sys.stdout.buffer.write(graph.create_svg())  # type: ignore[attr-defined]
-        else:
-            out_extension = out.rsplit(".", 1)[1]
-            graph.write(out, format=out_extension)
+        image = _render_image(machine, out.rsplit(".", 1)[1])
+        with open(out, "wb") as f:
+            f.write(image)
+
+
+def _render_image(machine, fmt: str) -> bytes:
+    dot_source: str = DotGraphMachine(machine).get_graph().to_string()
+    if fmt == "raw":
+        return dot_source.encode("utf-8")
+    return run_graphviz(dot_source, fmt)
 
 
 def main(argv=None):

statemachine/contrib/diagram/extract.py

@@ -91,7 +91,7 @@ def _extract_state(
 
     return DiagramState(
         id=state.id,
-        name=state.name,
+        name=str(state.name),
         type=state_type,
         actions=actions,
         children=children,
@@ -125,7 +125,7 @@ def _format_event_names(transition: "Transition") -> str:
             continue
         if eid not in seen_ids:  # pragma: no branch
             seen_ids.add(eid)
-            display.append(event.name if event.name else eid)
+            display.append(str(event.name) if event.name else eid)
 
     return " ".join(display)
 
@@ -279,7 +279,7 @@ def extract(machine_or_class: "MachineRef") -> DiagramGraph:
     _resolve_initial_states(states)
 
     return DiagramGraph(
-        name=machine.name,
+        name=str(machine.name),
         states=states,
         transitions=transitions,
         compound_state_ids=compound_ids,

statemachine/contrib/diagram/formatter.py

@@ -19,6 +19,8 @@ A module-level :data:`formatter` instance is the single public entry point::
 from collections.abc import Callable
 from typing import TYPE_CHECKING
 
+from .graphviz import run_graphviz
+
 if TYPE_CHECKING:
     from typing import TypeAlias
 
@@ -108,8 +110,8 @@ def _render_dot(machine_or_class: "MachineRef") -> str:
 def _render_svg(machine_or_class: "MachineRef") -> str:
     from statemachine.contrib.diagram import DotGraphMachine
 
-    svg_bytes: bytes = DotGraphMachine(machine_or_class).get_graph().create_svg()  # type: ignore[attr-defined]
-    return svg_bytes.decode("utf-8")
+    dot_source = DotGraphMachine(machine_or_class).get_graph().to_string()
+    return run_graphviz(dot_source, "svg").decode("utf-8")
 
 
 @formatter.register_format("mermaid")

statemachine/contrib/diagram/graphviz.py

@@ -0,0 +1,66 @@
+"""Run the Graphviz ``dot`` program and report its failures."""
+
+import errno
+import subprocess
+
+from statemachine.exceptions import StateMachineError
+
+GRAPHVIZ_DOWNLOAD_URL = "https://graphviz.org/download/"
+
+
+class GraphvizError(StateMachineError):
+    """Raised when the Graphviz ``dot`` program cannot run or fails to render a graph."""
+
+
+class GraphvizNotFoundError(GraphvizError, FileNotFoundError):
+    """Raised when the Graphviz program is not found in ``PATH``.
+
+    Also a :class:`FileNotFoundError`, so ``except FileNotFoundError`` catches a missing
+    Graphviz.
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.errno = errno.ENOENT
+
+
+def run_graphviz(dot_source: str, fmt: str, prog: str = "dot") -> bytes:
+    """Render ``dot_source`` with Graphviz and return the output bytes.
+
+    Args:
+        dot_source: Graph in the DOT language.
+        fmt: Graphviz output format, passed as ``-T<fmt>`` (``"svg"``, ``"png"``, ...).
+        prog: Graphviz layout program to run, looked up on ``PATH``.
+
+    Raises:
+        GraphvizNotFoundError: If ``prog`` is not found in ``PATH``.
+        GraphvizError: If ``prog`` cannot be run or exits with a non-zero code.
+            The message carries what Graphviz wrote to stderr.
+    """
+    command = [prog, f"-T{fmt}"]
+    try:
+        completed = subprocess.run(
+            command,
+            input=dot_source.encode("utf-8"),
+            capture_output=True,
+            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+        )
+    except FileNotFoundError as err:
+        raise GraphvizNotFoundError(
+            f"{prog!r} not found in PATH. Install Graphviz from {GRAPHVIZ_DOWNLOAD_URL} "
+            "to generate diagrams."
+        ) from err
+    except OSError as err:
+        raise GraphvizError(f"{prog!r} could not be run: {err}") from err
+
+    if completed.returncode != 0:
+        if completed.returncode < 0:
+            message = f"{' '.join(command)} was terminated by signal {-completed.returncode}."
+        else:
+            message = f"{' '.join(command)} failed with exit code {completed.returncode}."
+        stderr = completed.stderr.decode("utf-8", errors="replace").strip()
+        if stderr:
+            message = f"{message}\n{stderr}"
+        raise GraphvizError(message)
+
+    return completed.stdout

statemachine/contrib/diagram/sphinx_ext.py

@@ -24,6 +24,7 @@ from typing import ClassVar
 from docutils import nodes
 from docutils.parsers.rst import directives
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.osutil import relative_uri
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -118,7 +119,7 @@ class StateMachineDiagram(SphinxDirective):
         svg_tag = svg_tag.replace("<svg ", f"<svg {svg_styles} ", 1)
 
         alt_text = html_mod.escape(self.options.get("alt", qualname.rsplit(".", 1)[-1]))
-        target = self._resolve_target(svg_text)
+        target, zoom_filename = self._resolve_target(svg_text)
 
         img_html = f'<div role="img" aria-label="{alt_text}">{svg_tag}</div>'
         if target:
@@ -142,6 +143,7 @@ class StateMachineDiagram(SphinxDirective):
             html = f"<div{class_attr}>{img_html}</div>"
 
         raw_node = nodes.raw("", html, format="html")
+        raw_node["zoom_filename"] = zoom_filename
 
         if "name" in self.options:
             self.add_name(raw_node)
@@ -232,18 +234,21 @@ class StateMachineDiagram(SphinxDirective):
 
         return f'style="{"; ".join(parts)}"'
 
-    def _resolve_target(self, svg_text: str) -> str:
-        """Return the href for the wrapper ``<a>`` tag, if any.
+    def _resolve_target(self, svg_text: str) -> tuple[str, str]:
+        """Return ``(href, zoom_filename)`` for the wrapper ``<a>`` tag.
 
         When ``:target:`` is given without a value (or as empty string), the
         raw SVG is written to ``_images/`` and linked so the user can open
-        the full diagram in a new browser tab for zooming.
+        the full diagram in a new browser tab for zooming. The href is
+        root-relative at this point; ``_resolve_zoom_links`` rewrites it
+        relative to each page at write time, once the builder knows the
+        page's final URI.
         """
         if "target" not in self.options:
-            return ""
+            return "", ""
         target = (self.options["target"] or "").strip()
         if target:
-            return target
+            return target, ""
 
         # Auto-generate a standalone SVG file for zoom.
         qualname = self.arguments[0]
@@ -258,7 +263,7 @@ class StateMachineDiagram(SphinxDirective):
         with open(outpath, "w", encoding="utf-8") as f:
             f.write(svg_text)
 
-        return f"/_images/{filename}"
+        return f"_images/{filename}", filename
 
     def _build_wrapper_classes(self) -> list[str]:
         """Build CSS class list for the outer wrapper element."""
@@ -275,6 +280,22 @@ def _split_length(value: str) -> tuple[float, str]:
     return 0.0, value
 
 
+def _resolve_zoom_links(app: "Sphinx", doctree: nodes.document, docname: str) -> None:
+    """Rewrite auto-generated zoom hrefs relative to the page being written."""
+    builder = app.builder
+    if builder.format != "html":
+        return
+    page_uri = builder.get_target_uri(docname).split("#", 1)[0]
+    for node in doctree.findall(nodes.raw):
+        filename = node.get("zoom_filename")
+        if not filename:
+            continue
+        href = relative_uri(page_uri, f"_images/{filename}")
+        html = node.astext().replace(f'href="_images/{filename}"', f'href="{href}"')
+        node[0] = nodes.Text(html)
+
+
 def setup(app: "Sphinx") -> dict[str, Any]:
     app.add_directive("statemachine-diagram", StateMachineDiagram)
+    app.connect("doctree-resolved", _resolve_zoom_links)
     return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True}

statemachine/dispatcher.py

@@ -14,6 +14,7 @@ from .event import Event
 from .exceptions import InvalidDefinition
 from .i18n import _
 from .signature import SignatureAdapter
+from .spec_parser import UnsupportedExpression
 from .spec_parser import custom_and
 from .spec_parser import operator_mapping
 from .spec_parser import parse_boolean_expr
@@ -118,7 +119,10 @@ class Listeners:
 
         try:
             expression = parse_boolean_expr(spec.func, take_callback_partial, operator_mapping)
-        except SyntaxError as err:
+        except (SyntaxError, UnsupportedExpression) as err:
+            # ``UnsupportedExpression`` comes from the AST allowlist rejecting a node
+            # kind that cannot appear in a boolean expression (e.g. ``"user.age"``).
+            # Errors raised while resolving names are not parse errors and propagate.
             raise InvalidDefinition(
                 _("Failed to parse boolean expression '{}'").format(spec.func)
             ) from err
@@ -157,14 +161,15 @@ class Listeners:
         # if the attr is an unbounded method, we'll try to find the bounded method
         # on the self
         if not spec.is_bounded:
+            attr_name = spec.lookup_name
             for listener in self.items:
-                func = getattr(listener.obj, spec.attr_name, None)
+                func = getattr(listener.obj, attr_name, None)
                 # ``getattr`` may return a non-method that happens to share the name
                 # (e.g. a model attribute named like a compiled guard); it is not the
                 # unbounded method we are rebinding, so skip it instead of accessing
                 # ``__func__`` (which would raise on a plain value).
                 if getattr(func, "__func__", None) is spec.func:
-                    yield listener.build_key(spec.attr_name), partial(callable_method, func)
+                    yield listener.build_key(attr_name), partial(callable_method, func)
                     return
 
         yield f"{spec.attr_name}-{id(spec.func)}@None", partial(callable_method, spec.func)