python-statemachine 3.1.1__tar.gz → 3.1.2__tar.gz

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/.github/workflows/python-package.yml

@@ -21,16 +21,16 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - run: git fetch origin develop
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     - name: Setup Graphviz
       uses: ts-graphviz/setup-graphviz@v2
     - name: Install uv
-      uses: astral-sh/setup-uv@v3
+      uses: astral-sh/setup-uv@v8.1.0
       with:
         enable-cache: true
         cache-suffix: "python${{ matrix.python-version }}"
@@ -55,7 +55,7 @@ jobs:
       #          upload coverage
       #----------------------------------------------
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v6
       if: matrix.python-version == 3.14
       with:
         token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/.github/workflows/release.yml

@@ -11,12 +11,12 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - run: git fetch origin develop
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.14'
 
@@ -24,7 +24,7 @@ jobs:
         uses: ts-graphviz/setup-graphviz@v2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           enable-cache: true
 

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/.pre-commit-config.yaml

@@ -1,15 +1,15 @@
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v6.0.0
     hooks:
     -   id: check-yaml
     -   id: end-of-file-fixer
         exclude: docs/auto_examples
     -   id: trailing-whitespace
         exclude: docs/auto_examples
-- repo: https://github.com/charliermarsh/ruff-pre-commit
+- repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.15.8
+  rev: v0.15.13
   hooks:
     # Run the linter.
     - id: ruff

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-statemachine
-Version: 3.1.1
+Version: 3.1.2
 Summary: Python Finite State Machines made easy.
 Project-URL: homepage, https://github.com/fgmacedo/python-statemachine
 Author-email: Fernando Macedo <fgmacedo@gmail.com>

python_statemachine-3.1.2/docs/releases/3.1.2.md

@@ -0,0 +1,53 @@
+# StateChart 3.1.2
+
+*May 18, 2026*
+
+## Bug fixes in 3.1.2
+
+### `pydot` is optional again
+
+Starting in 3.1.0, defining any `StateMachine` or `StateChart` subclass
+implicitly required `pydot` to be installed. The metaclass invokes
+`_expand_docstring()` for every class, and that path eagerly imported the
+diagram formatter, which in turn imported `pydot` at module load time, so
+`import` of a user module failed with `ModuleNotFoundError: No module
+named 'pydot'` even when no diagrams were rendered.
+
+Two changes restore the original behavior:
+
+- `_expand_docstring` now short-circuits when the class docstring contains
+  no `{statechart:FORMAT}` placeholder, skipping the formatter import for
+  the common case.
+- `statemachine.contrib.diagram` no longer re-exports renderer classes at
+  the package top level, and renderer modules are only imported when
+  actually used. The dependency is only resolved when `dot`/`svg`
+  rendering is requested. Mermaid and Markdown/RST formats work without
+  `pydot`.
+
+If your code imports `DotRenderer`, `DotRendererConfig`, `MermaidRenderer`
+or `MermaidRendererConfig` directly from `statemachine.contrib.diagram`,
+import them from the renderer submodule instead:
+
+```python
+from statemachine.contrib.diagram.renderers.dot import DotRenderer
+from statemachine.contrib.diagram.renderers.mermaid import MermaidRenderer
+```
+
+[#622](https://github.com/fgmacedo/python-statemachine/issues/622).
+
+## Other changes in 3.1.2
+
+### Security and dependency bumps
+
+Picked up from the dependency refresh applied to `main`:
+
+- ruff `>=0.15.13`
+- pytest `>=9.0.3` (CVE-2025, tmpdir handling) for py>=3.10
+- django `>=5.2.14` for py3.10/3.11 (multiple CVEs)
+- pillow `>=12.2.0` for py>=3.10 (multiple CVEs)
+- transitive: urllib3 `2.6.3 -> 2.7.0` (GHSA-qccp-gfcp-xxvc), requests
+  `2.33.1 -> 2.34.2`
+
+CI workflows: `actions/checkout` v4 → v5, `actions/setup-python` v5 → v6,
+`astral-sh/setup-uv` v3 → v8 (pinned to `v8.1.0`), `codecov/codecov-action`
+v4 → v6.

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/docs/releases/index.md

@@ -16,6 +16,7 @@ Requires Python 3.9+.
 ```{toctree}
 :maxdepth: 2
 
+3.1.2
 3.1.1
 3.1.0
 3.0.0

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-statemachine"
-version = "3.1.1"
+version = "3.1.2"
 description = "Python Finite State Machines made easy."
 authors = [{ name = "Fernando Macedo", email = "fgmacedo@gmail.com" }]
 maintainers = [{ name = "Fernando Macedo", email = "fgmacedo@gmail.com" }]
@@ -32,10 +32,11 @@ diagrams = ["pydot >= 4.0.1"]
 
 [dependency-groups]
 dev = [
-    "ruff >=0.15.8",
+    "ruff >=0.15.13",
     "pre-commit",
     "mypy",
-    "pytest",
+    "pytest >=9.0.3; python_version >='3.10'",
+    "pytest >=8.4.2; python_version <'3.10'",
     "pytest-cov >=7.1.0; python_version >='3.9'",
     "pytest-cov; python_version <'3.9'",
     "pytest-sugar >=1.1.1",
@@ -45,12 +46,13 @@ dev = [
     "pytest-asyncio >=0.25.0; python_version <'3.10'",
     "pydot",
     "django >=6.0.3; python_version >='3.12'",
-    "django >=5.2.12; python_version >='3.10' and python_version <'3.12'",
+    "django >=5.2.14; python_version >='3.10' and python_version <'3.12'",
     "pytest-django >=4.12.0; python_version >='3.10'",
     "Sphinx; python_version >'3.8'",
     "sphinx-gallery; python_version >'3.8'",
     "myst-parser; python_version >'3.8'",
-    "pillow; python_version >'3.8'",
+    "pillow >=12.2.0; python_version >='3.10'",
+    "pillow; python_version <'3.10'",
     "sphinx-autobuild; python_version >'3.8'",
     "furo >=2025.12.19; python_version >'3.8'",
     "sphinx-copybutton >=0.5.2; python_version >'3.8'",

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/statemachine/__init__.py

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

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/statemachine/contrib/diagram/__init__.py

@@ -1,13 +1,14 @@
 import importlib
+from typing import TYPE_CHECKING
 from urllib.parse import quote
 from urllib.request import urlopen
 
 from .extract import extract
 from .formatter import formatter as formatter
-from .renderers.dot import DotRenderer
-from .renderers.dot import DotRendererConfig
-from .renderers.mermaid import MermaidRenderer
-from .renderers.mermaid import MermaidRendererConfig
+
+if TYPE_CHECKING:
+    from .renderers.dot import DotRendererConfig
+    from .renderers.mermaid import MermaidRendererConfig
 
 
 class DotGraphMachine:
@@ -40,7 +41,9 @@ class DotGraphMachine:
     def __init__(self, machine):
         self.machine = machine
 
-    def _build_config(self) -> DotRendererConfig:
+    def _build_config(self) -> "DotRendererConfig":
+        from .renderers.dot import DotRendererConfig
+
         return DotRendererConfig(
             graph_rankdir=self.graph_rankdir,
             font_name=self.font_name,
@@ -51,6 +54,8 @@ class DotGraphMachine:
         )
 
     def get_graph(self):
+        from .renderers.dot import DotRenderer
+
         ir = extract(self.machine)
         renderer = DotRenderer(config=self._build_config())
         return renderer.render(ir)
@@ -69,7 +74,9 @@ class MermaidGraphMachine:
     def __init__(self, machine):
         self.machine = machine
 
-    def _build_config(self) -> MermaidRendererConfig:
+    def _build_config(self) -> "MermaidRendererConfig":
+        from .renderers.mermaid import MermaidRendererConfig
+
         return MermaidRendererConfig(
             direction=self.direction,
             active_fill=self.active_fill,
@@ -77,6 +84,8 @@ class MermaidGraphMachine:
         )
 
     def get_mermaid(self) -> str:
+        from .renderers.mermaid import MermaidRenderer
+
         ir = extract(self.machine)
         renderer = MermaidRenderer(config=self._build_config())
         return renderer.render(ir)

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/statemachine/factory.py

@@ -99,7 +99,7 @@ class StateMachineMetaclass(type):
     def _expand_docstring(cls) -> None:
         """Replace ``{statechart:FORMAT}`` placeholders in the class docstring."""
         doc = cls.__doc__
-        if not doc:
+        if not doc or not cls._STATECHART_RE.search(doc):
             return
 
         from .contrib.diagram.formatter import formatter

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/statemachine/locale/en/LC_MESSAGES/statemachine.po

@@ -5,7 +5,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  3.1.1\n"
 "Report-Msgid-Bugs-To: fgmacedo@gmail.com\n"
-"POT-Creation-Date: 2026-05-15 12:08-0300\n"
+"POT-Creation-Date: 2026-05-18 16:16-0300\n"
 "PO-Revision-Date: 2026-02-24 14:31-0300\n"
 "Last-Translator: Fernando Macedo <fgmacedo@gmail.com>\n"
 "Language: en\n"
@@ -21,7 +21,7 @@ msgstr ""
 msgid "Did not found name '{}' from model or statemachine"
 msgstr "Did not found name '{}' from model or statemachine"
 
-#: statemachine/configuration.py:121
+#: statemachine/configuration.py:129
 msgid ""
 "There's no current state set. In async code, did you activate the initial"
 " state? (e.g., `await sm.activate_initial_state()`)"

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/statemachine/locale/hi_IN/LC_MESSAGES/statemachine.po

@@ -5,7 +5,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  3.1.1\n"
 "Report-Msgid-Bugs-To: fgmacedo@gmail.com\n"
-"POT-Creation-Date: 2026-05-15 12:08-0300\n"
+"POT-Creation-Date: 2026-05-18 16:16-0300\n"
 "PO-Revision-Date: 2024-06-07 17:41-0300\n"
 "Last-Translator: Fernando Macedo <fgmacedo@gmail.com>\n"
 "Language: hi_IN\n"
@@ -21,7 +21,7 @@ msgstr ""
 msgid "Did not found name '{}' from model or statemachine"
 msgstr "मॉडल या स्टेटमशीन में नाम '{}' नहीं मिला"
 
-#: statemachine/configuration.py:121
+#: statemachine/configuration.py:129
 msgid ""
 "There's no current state set. In async code, did you activate the initial"
 " state? (e.g., `await sm.activate_initial_state()`)"

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/statemachine/locale/pt_BR/LC_MESSAGES/statemachine.po

@@ -5,7 +5,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  3.1.1\n"
 "Report-Msgid-Bugs-To: fgmacedo@gmail.com\n"
-"POT-Creation-Date: 2026-05-15 12:08-0300\n"
+"POT-Creation-Date: 2026-05-18 16:16-0300\n"
 "PO-Revision-Date: 2024-06-07 17:41-0300\n"
 "Last-Translator: Fernando Macedo <fgmacedo@gmail.com>\n"
 "Language: pt_BR\n"
@@ -21,7 +21,7 @@ msgstr ""
 msgid "Did not found name '{}' from model or statemachine"
 msgstr "Nome '{}' não encontrado no modelo ou na máquina de estados"
 
-#: statemachine/configuration.py:121
+#: statemachine/configuration.py:129
 msgid ""
 "There's no current state set. In async code, did you activate the initial"
 " state? (e.g., `await sm.activate_initial_state()`)"

{python_statemachine-3.1.1 → python_statemachine-3.1.2}/statemachine/locale/zh_CN/LC_MESSAGES/statemachine.po

@@ -5,7 +5,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  3.1.1\n"
 "Report-Msgid-Bugs-To: fgmacedo@gmail.com\n"
-"POT-Creation-Date: 2026-05-15 12:08-0300\n"
+"POT-Creation-Date: 2026-05-18 16:16-0300\n"
 "PO-Revision-Date: 2024-06-07 17:41-0300\n"
 "Last-Translator: Fernando Macedo <fgmacedo@gmail.com>\n"
 "Language: zh_CN\n"
@@ -21,7 +21,7 @@ msgstr ""
 msgid "Did not found name '{}' from model or statemachine"
 msgstr "在模型或状态机中未找到名称 '{}'"
 
-#: statemachine/configuration.py:121
+#: statemachine/configuration.py:129
 msgid ""
 "There's no current state set. In async code, did you activate the initial"
 " state? (e.g., `await sm.activate_initial_state()`)"
@@ -37,9 +37,7 @@ msgstr "无法解析布尔表达式 '{}'"
 msgid ""
 "Event() received a non-string 'id' ({cls_name}). To combine multiple "
 "transitions under one event, use the | operator: t1 | t2."
-msgstr ""
-"Event() 接收到的 'id' 不是字符串 ({cls_name})。要将多个转换组合在同一个事件下，"
-"请使用 | 运算符：t1 | t2。"
+msgstr "Event() 接收到的 'id' 不是字符串 ({cls_name})。要将多个转换组合在同一个事件下，请使用 | 运算符：t1 | t2。"
 
 #: statemachine/event.py:131
 #, python-brace-format

python_statemachine-3.1.2/tests/test_optional_pydot.py

@@ -0,0 +1,135 @@
+"""Regression tests for issue #622: ``pydot`` must remain optional.
+
+These tests run in a subprocess so we can install a strict import hook that
+rejects ``pydot`` without contaminating the main test interpreter (where the
+diagram test suite legitimately requires ``pydot``).
+"""
+
+import subprocess
+import sys
+import textwrap
+
+
+def _run_without_pydot(script: str) -> subprocess.CompletedProcess:
+    """Execute ``script`` in a fresh interpreter where importing ``pydot`` fails."""
+    preamble = textwrap.dedent(
+        """
+        import builtins
+        _real_import = builtins.__import__
+
+        def _guarded(name, globals=None, locals=None, fromlist=(), level=0):
+            if name == "pydot" or name.startswith("pydot."):
+                raise ModuleNotFoundError("No module named 'pydot'")
+            return _real_import(name, globals, locals, fromlist, level)
+
+        builtins.__import__ = _guarded
+        """
+    )
+    return subprocess.run(
+        [sys.executable, "-c", preamble + script],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_define_statemachine_without_pydot():
+    """Defining a StateMachine subclass must not import ``pydot``."""
+    result = _run_without_pydot(
+        textwrap.dedent(
+            """
+            from statemachine import State, StateMachine
+
+            class TrafficLight(StateMachine):
+                'Light that cycles through colors.'
+                green = State(initial=True)
+                yellow = State()
+                red = State(final=True)
+                cycle = green.to(yellow) | yellow.to(red)
+
+            import sys
+            assert "pydot" not in sys.modules, "pydot was imported transitively"
+            print("OK")
+            """
+        )
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "OK"
+
+
+def test_define_statechart_without_pydot():
+    """Defining a StateChart subclass must not import ``pydot`` either."""
+    result = _run_without_pydot(
+        textwrap.dedent(
+            """
+            from statemachine import State
+            from statemachine.statemachine import StateChart
+
+            class Workflow(StateChart):
+                'Workflow with a docstring but no statechart placeholder.'
+                draft = State(initial=True)
+                published = State(final=True)
+                publish = draft.to(published)
+
+            import sys
+            assert "pydot" not in sys.modules
+            print("OK")
+            """
+        )
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "OK"
+
+
+def test_mermaid_format_without_pydot():
+    """The ``mermaid`` / ``md`` / ``rst`` formats must work without ``pydot``."""
+    result = _run_without_pydot(
+        textwrap.dedent(
+            """
+            from statemachine import State, StateMachine
+
+            class TrafficLight(StateMachine):
+                green = State(initial=True)
+                red = State(final=True)
+                stop = green.to(red)
+
+            mermaid = format(TrafficLight, "mermaid")
+            assert "stateDiagram-v2" in mermaid, mermaid
+
+            md = format(TrafficLight, "md")
+            assert "| State" in md, md
+
+            import sys
+            assert "pydot" not in sys.modules
+            print("OK")
+            """
+        )
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "OK"
+
+
+def test_dot_format_requires_pydot_with_clear_error():
+    """``dot``/``svg`` formats still need ``pydot``; the error should surface clearly."""
+    result = _run_without_pydot(
+        textwrap.dedent(
+            """
+            from statemachine import State, StateMachine
+
+            class TrafficLight(StateMachine):
+                green = State(initial=True)
+                red = State(final=True)
+                stop = green.to(red)
+
+            try:
+                format(TrafficLight, "dot")
+            except ModuleNotFoundError as exc:
+                assert "pydot" in str(exc), exc
+                print("OK")
+            else:
+                raise AssertionError("Expected ModuleNotFoundError for dot format")
+            """
+        )
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "OK"