Merge branch 'release/3.1.0'

Author: fgmacedo

.github/workflows/python-package.yml

@@ -9,6 +9,9 @@ on:
   pull_request:
     branches: [ "develop" ]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     runs-on: ubuntu-latest

.gitignore

@@ -79,3 +79,9 @@ target/
 docs/auto_examples/sg_execution_times.*
 docs/auto_examples/*.pickle
 docs/sg_execution_times.rst
+
+# Temporary files
+tmp/
+
+# Local specs
+specs/

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
         exclude: docs/auto_examples
 - repo: https://github.com/charliermarsh/ruff-pre-commit
   # Ruff version.
-  rev: v0.15.0
+  rev: v0.15.8
   hooks:
     # Run the linter.
     - id: ruff
@@ -31,6 +31,16 @@ repos:
     types: [python]
     language: system
     pass_filenames: false
+  - id: generate-images
+    name: Generate README images
+    entry: >-
+      uv run python -m statemachine.contrib.diagram
+      tests.examples.traffic_light_machine.TrafficLightMachine
+      docs/images/readme_trafficlightmachine.png
+      --events cycle cycle cycle
+    language: system
+    pass_filenames: false
+    files: (statemachine/contrib/diagram/|tests/examples/traffic_light_machine\.py)
   - id: pytest
     name: Pytest
     entry: uv run pytest -n auto --cov-fail-under=100

AGENTS.md

@@ -77,6 +77,16 @@ current event.
 - `on_error_execution()` works via naming convention but **only** when a transition for
   `error.execution` is declared — it is NOT a generic callback.
 
+### Thread safety
+
+- The sync engine is **thread-safe**: multiple threads can send events to the same SM instance
+  concurrently. The processing loop uses a `threading.Lock` so at most one thread executes
+  transitions at a time. Event queues use `PriorityQueue` (stdlib, thread-safe).
+- **Do not replace `PriorityQueue`** with non-thread-safe alternatives (e.g., `collections.deque`,
+  plain `list`) — this would break concurrent access guarantees.
+- Stress tests in `tests/test_threading.py::TestThreadSafety` exercise real contention with
+  barriers and multiple sender threads. Any change to queue or locking internals must pass these.
+
 ### Invoke (`<invoke>`)
 
 - `invoke.py` — `InvokeManager` on the engine manages the lifecycle: `mark_for_invoke()`,
@@ -127,6 +137,16 @@ timeout 120 uv run pytest -n 4
 
 Testes normally run under 60s (~40s on average), so take a closer look if they take longer, it can be a regression.
 
+### Debug logging
+
+`log_cli_level` defaults to `WARNING` in `pyproject.toml`. The engine caches a no-op
+for `logger.debug` at init time — running tests with `DEBUG` would bypass this
+optimization and inflate benchmark numbers. To enable debug logs for a specific run:
+
+```bash
+uv run pytest -o log_cli_level=DEBUG tests/test_something.py
+```
+
 When analyzing warnings or extensive output, run the tests **once** saving the output to a file
 (`> /tmp/pytest-output.txt 2>&1`), then analyze the file — instead of running the suite
 repeatedly with different greps.
@@ -160,6 +180,26 @@ async def test_something(self, sm_runner):
 
 Do **not** manually add async no-op listeners or duplicate test classes — prefer `sm_runner`.
 
+### TDD and coverage requirements
+
+Follow a **test-driven development** approach: tests are not an afterthought — they are a
+first-class requirement that must be part of every implementation plan.
+
+- **Planning phase:** every plan must include test tasks as explicit steps, not a final
+  "add tests" bullet. Identify what needs to be tested (new branches, edge cases, error
+  paths) while designing the implementation.
+- **100% branch coverage is mandatory.** The pre-commit hook enforces `--cov-fail-under=100`
+  with branch coverage enabled. Code that drops coverage will not pass CI.
+- **Verify coverage before committing:** after writing tests, run coverage on the affected
+  modules and check for missing lines/branches:
+  ```bash
+  timeout 120 uv run pytest tests/<test_file>.py --cov=statemachine.<module> --cov-report=term-missing --cov-branch
+  ```
+- **Use pytest fixtures** (`tmp_path`, `monkeypatch`, etc.) — never hardcode paths or
+  use mutable global state when a fixture exists.
+- **Unreachable defensive branches** (e.g., `if` guards that can never be True given the
+  type system) may be marked with `pragma: no cover`, but prefer writing a test first.
+
 ## Linting and formatting
 
 ```bash

README.md

@@ -77,16 +77,23 @@ True
 
 ```
 
-Generate a diagram:
+Generate a diagram or get a text representation with f-strings:
 
 ```py
->>> # This example will only run on automated tests if dot is present
->>> getfixture("requires_dot_installed")
->>> img_path = "docs/images/readme_trafficlightmachine.png"
->>> sm._graph().write_png(img_path)
+>>> print(f"{sm:md}")
+| State  | Event | Guard | Target |
+| ------ | ----- | ----- | ------ |
+| Green  | Cycle |       | Yellow |
+| Yellow | Cycle |       | Red    |
+| Red    | Cycle |       | Green  |
+<BLANKLINE>
 
 ```
 
+```python
+sm._graph().write_png("traffic_light.png")
+```
+
 ![](https://raw.githubusercontent.com/fgmacedo/python-statemachine/develop/docs/images/readme_trafficlightmachine.png)
 
 Parameters are injected into callbacks automatically — the library inspects the
@@ -345,7 +352,7 @@ There's a lot more to explore:
 - **`prepare_event`** callback — inject custom data into all callbacks
 - **Observer pattern** — register external listeners to watch events and state changes
 - **Django integration** — auto-discover state machines in Django apps with `MachineMixin`
-- **Diagram generation** — from the CLI, at runtime, or in Jupyter notebooks
+- **Diagram generation** — via f-strings (`f"{sm:mermaid}"`), CLI, Sphinx directive, or Jupyter
 - **Dictionary-based definitions** — create state machines from data structures
 - **Internationalization** — error messages in multiple languages
 

docs/async.md

@@ -75,7 +75,7 @@ the initial state:
 ...     print(list(sm.configuration_values))
 
 >>> asyncio.run(show_problem())
-[None]
+[]
 
 ```
 

docs/conf.py

@@ -51,6 +51,8 @@
     "sphinx.ext.autosectionlabel",
     "sphinx_gallery.gen_gallery",
     "sphinx_copybutton",
+    "statemachine.contrib.diagram.sphinx_ext",
+    "sphinxcontrib.mermaid",
 ]
 
 autosectionlabel_prefix_document = True