python-statemachine 2.4.0__tar.gz → 2.6.0__tar.gz

python_statemachine-2.6.0/.git-blame-ignore-revs

@@ -0,0 +1,4 @@
+37fcf9818178587635fffe1bb67a9fd5024a0a45
+345d82390af35d5d70ddd39c612faa4a64b11080
+d7738e9ad0a3e50bc5c87d4a75c436fb771c96f6
+5bf10afae2b214900aa58dd44b0a91e469c70631

python_statemachine-2.6.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: fgmacedo

python_statemachine-2.6.0/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+* Python State Machine version:
+* Python version:
+* Operating System:
+
+### Description
+
+Describe what you were trying to get done.
+Tell us what happened, what went wrong, and what you expected to happen.
+
+### What I Did
+
+```
+Paste the command(s) you ran and the output.
+If there was a crash, please include the traceback here.
+```

python_statemachine-2.6.0/.github/workflows/python-package.yml

@@ -0,0 +1,64 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python checks
+
+on:
+  push:
+    branches: [ "develop" ]
+  pull_request:
+    branches: [ "develop" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - run: git fetch origin develop
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Setup Graphviz
+      uses: ts-graphviz/setup-graphviz@v2
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+        cache-suffix: "python${{ matrix.python-version }}"
+    - name: Install the project
+      run: uv sync --all-extras --dev
+      #----------------------------------------------
+      #              run ruff
+      #----------------------------------------------
+    - name: Linter with ruff
+      if: matrix.python-version == 3.14
+      run: |
+        uv run ruff check .
+        uv run ruff format --check .
+      #----------------------------------------------
+      #              run pytest
+      #----------------------------------------------
+    - name: Test with pytest
+      run: |
+        uv run pytest --cov-report=xml:coverage.xml
+        uv run coverage xml
+      #----------------------------------------------
+      #          upload coverage
+      #----------------------------------------------
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: matrix.python-version == 3.14
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
+        directory: .
+        env_vars: OS,PYTHON
+        fail_ci_if_error: true
+        flags: unittests
+        name: codecov-umbrella
+        verbose: true

python_statemachine-2.6.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+on:
+  push:
+    tags: [ 'v?*.*.*' ]
+name: release
+
+jobs:
+  release-build:
+    name: Build release artifacts
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - run: git fetch origin develop
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@v2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Test
+        run: |
+          uv run pytest
+
+      - name: Build
+        run: |
+          uv build
+
+      - name: Upload  dists
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+
+  pypi-publish:
+    # by a dedicated job to publish we avoid the risk of
+    # running code with access to PyPI credentials
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

python_statemachine-2.6.0/.gitignore

@@ -0,0 +1,81 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+.mypy_cache
+
+# jupyter
+.ipynb_checkpoints/
+.jupyterlite.doit.db
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+prof/
+.benchmarks/
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+docs/auto_examples/
+
+# PyBuilder
+target/
+
+# pyenv python configuration file
+.python-version
+
+# IDEs and editors
+*.sublime*
+.idea/
+.vscode/
+
+# Sphinx-galery
+docs/auto_examples/sg_execution_times.*
+docs/auto_examples/*.pickle
+docs/sg_execution_times.rst

python_statemachine-2.6.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.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
+  # Ruff version.
+  rev: v0.15.0
+  hooks:
+    # Run the linter.
+    - id: ruff
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
+
+- repo: local
+  hooks:
+  - id: mypy
+    name: Mypy
+    entry: uv run mypy --namespace-packages --explicit-package-bases statemachine/ tests/
+    types: [python]
+    language: system
+    pass_filenames: false
+  - id: pytest
+    name: Pytest
+    entry: uv run pytest
+    types: [python]
+    language: system
+    pass_filenames: false

python_statemachine-2.6.0/.readthedocs.yaml

@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.14"
+  apt_packages:
+    - graphviz
+  jobs:
+    post_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --all-extras --frozen
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py

python_statemachine-2.6.0/AGENTS.md

@@ -0,0 +1,114 @@
+# python-statemachine
+
+Python Finite State Machines made easy.
+
+## Project overview
+
+A library for building finite state machines in Python, with support for sync and async engines,
+Django integration, diagram generation, and a flexible callback/listener system.
+
+- **Source code:** `statemachine/`
+- **Tests:** `tests/`
+- **Documentation:** `docs/` (Sphinx + MyST Markdown, hosted on ReadTheDocs)
+
+## Architecture
+
+- `statemachine.py` — Core `StateMachine` class
+- `factory.py` — `StateMachineMetaclass` handles class construction, state/transition validation
+- `state.py` / `event.py` — Descriptor-based `State` and `Event` definitions
+- `transition.py` / `transition_list.py` — Transition logic and composition (`|` operator)
+- `callbacks.py` — Priority-based callback registry (`CallbackPriority`, `CallbackGroup`)
+- `dispatcher.py` — Listener/observer pattern, `callable_method` wraps callables with signature adaptation
+- `signature.py` — `SignatureAdapter` for dependency injection into callbacks
+- `engines/sync.py`, `engines/async_.py` — Sync and async run-to-completion engines
+- `registry.py` — Global state machine registry (used by `MachineMixin`)
+- `mixins.py` — `MachineMixin` for domain model integration (e.g., Django models)
+- `spec_parser.py` — Boolean expression parser for condition guards
+- `contrib/diagram.py` — Diagram generation via pydot/Graphviz
+
+## Environment setup
+
+```bash
+uv sync --all-extras --dev
+pre-commit install
+```
+
+## Running tests
+
+Always use `uv` to run commands:
+
+```bash
+# Run all tests (parallel)
+uv run pytest -n auto
+
+# Run a specific test file
+uv run pytest tests/test_signature.py
+
+# Run a specific test
+uv run pytest tests/test_signature.py::TestSignatureAdapter::test_wrap_fn_single_positional_parameter
+
+# Skip slow tests
+uv run pytest -m "not slow"
+```
+
+Tests include doctests from both source modules (`--doctest-modules`) and markdown docs
+(`--doctest-glob=*.md`). Coverage is enabled by default.
+
+## Linting and formatting
+
+```bash
+# Lint
+uv run ruff check .
+
+# Auto-fix lint issues
+uv run ruff check --fix .
+
+# Format
+uv run ruff format .
+
+# Type check
+uv run mypy statemachine/ tests/
+```
+
+## Code style
+
+- **Formatter/Linter:** ruff (line length 99, target Python 3.9)
+- **Rules:** pycodestyle, pyflakes, isort, pyupgrade, flake8-comprehensions, flake8-bugbear, flake8-pytest-style
+- **Imports:** single-line, sorted by isort
+- **Docstrings:** Google convention
+- **Naming:** PascalCase for classes, snake_case for functions/methods, UPPER_SNAKE_CASE for constants
+- **Type hints:** used throughout; `TYPE_CHECKING` for circular imports
+- Pre-commit hooks enforce ruff + mypy + pytest
+
+## Design principles
+
+- **Decouple infrastructure from domain:** Modules like `signature.py` and `dispatcher.py` are
+  general-purpose (signature adaptation, listener/observer pattern) and intentionally not coupled
+  to the state machine domain. Prefer this separation even for modules that are only used
+  internally — it keeps responsibilities clear and the code easier to reason about.
+- **Favor small, focused modules:** When adding new functionality, consider whether it can live in
+  its own module with a well-defined boundary, rather than growing an existing one.
+
+## Building documentation
+
+```bash
+# Build HTML docs
+uv run sphinx-build docs docs/_build/html
+
+# Live reload for development
+uv run sphinx-autobuild docs docs/_build/html --re-ignore "auto_examples/.*"
+```
+
+## Git workflow
+
+- Main branch: `develop`
+- PRs target `develop`
+- Releases are tagged as `v*.*.*`
+- Signed commits preferred (`git commit -s`)
+- Use [Conventional Commits](https://www.conventionalcommits.org/) messages
+  (e.g., `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, `perf:`)
+
+## Security
+
+- Do not commit secrets, credentials, or `.env` files
+- Validate at system boundaries; trust internal code

python_statemachine-2.6.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

{python_statemachine-2.4.0 → python_statemachine-2.6.0}/PKG-INFO

@@ -1,19 +1,18 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: python-statemachine
-Version: 2.4.0
+Version: 2.6.0
 Summary: Python Finite State Machines made easy.
-Home-page: https://github.com/fgmacedo/python-statemachine
-License: MIT
-Author: Fernando Macedo
-Author-email: fgmacedo@gmail.com
-Maintainer: Fernando Macedo
-Maintainer-email: fgmacedo@gmail.com
-Requires-Python: >=3.7
+Project-URL: homepage, https://github.com/fgmacedo/python-statemachine
+Author-email: Fernando Macedo <fgmacedo@gmail.com>
+Maintainer-email: Fernando Macedo <fgmacedo@gmail.com>
+License: MIT License
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: AsyncIO
+Classifier: Framework :: Django
 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
@@ -21,9 +20,12 @@ Classifier: Programming Language :: Python :: 3.10
 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: Topic :: Home Automation
 Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.7
 Provides-Extra: diagrams
-Requires-Dist: pydot (>=2.0.0) ; (python_full_version > "3.8.0") and (extra == "diagrams")
+Requires-Dist: pydot>=2.0.0; extra == 'diagrams'
 Description-Content-Type: text/markdown
 
 # Python StateMachine
@@ -127,6 +129,8 @@ You can now create an instance:
 This state machine can be represented graphically as follows:
 
 ```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)
 
@@ -196,19 +200,19 @@ Easily iterate over all states:
 
 ```py
 >>> [s.id for s in sm.states]
-['green', 'red', 'yellow']
+['green', 'yellow', 'red']
 
 ```
 
 Or over events:
 
 ```py
->>> [t.name for t in sm.events]
+>>> [t.id for t in sm.events]
 ['cycle']
 
 ```
 
-Call an event by its name:
+Call an event by its id:
 
 ```py
 >>> sm.cycle()
@@ -216,7 +220,7 @@ Don't move.
 'Running cycle from yellow to red'
 
 ```
-Or send an event with the event name:
+Or send an event with the event id:
 
 ```py
 >>> sm.send('cycle')
@@ -427,4 +431,3 @@ request. For more information on how to contribute, please see our [contributing
 - **Promote the project**: Help spread the word by sharing on social media,
   writing a blog post, or giving a talk about it. Tag me on Twitter
   [@fgmacedo](https://twitter.com/fgmacedo) so I can share it too!
-

{python_statemachine-2.4.0 → python_statemachine-2.6.0}/README.md

@@ -99,6 +99,8 @@ You can now create an instance:
 This state machine can be represented graphically as follows:
 
 ```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)
 
@@ -168,19 +170,19 @@ Easily iterate over all states:
 
 ```py
 >>> [s.id for s in sm.states]
-['green', 'red', 'yellow']
+['green', 'yellow', 'red']
 
 ```
 
 Or over events:
 
 ```py
->>> [t.name for t in sm.events]
+>>> [t.id for t in sm.events]
 ['cycle']
 
 ```
 
-Call an event by its name:
+Call an event by its id:
 
 ```py
 >>> sm.cycle()
@@ -188,7 +190,7 @@ Don't move.
 'Running cycle from yellow to red'
 
 ```
-Or send an event with the event name:
+Or send an event with the event id:
 
 ```py
 >>> sm.send('cycle')

python_statemachine-2.6.0/conftest.py

@@ -0,0 +1,46 @@
+import shutil
+import sys
+
+import pytest
+
+
+@pytest.fixture(autouse=True, scope="session")
+def add_doctest_context(doctest_namespace):  # noqa: PT004
+    from statemachine.utils import run_async_from_sync
+
+    from statemachine import State
+    from statemachine import StateMachine
+
+    class ContribAsyncio:
+        """
+        Using `run_async_from_sync` to be injected in the doctests to better integration with an
+        already running loop, as all of our examples are also automated executed as doctests.
+
+        On real life code you should use standard `import asyncio; asyncio.run(main())`.
+        """
+
+        def __init__(self):
+            self.run = run_async_from_sync
+
+    doctest_namespace["State"] = State
+    doctest_namespace["StateMachine"] = StateMachine
+    doctest_namespace["asyncio"] = ContribAsyncio()
+
+
+def pytest_ignore_collect(collection_path, path, config):
+    if sys.version_info >= (3, 10):  # noqa: UP036
+        return None
+
+    if "django_project" in str(path):
+        return True
+
+
+@pytest.fixture(scope="session")
+def has_dot_installed():
+    return bool(shutil.which("dot"))
+
+
+@pytest.fixture()
+def requires_dot_installed(request, has_dot_installed):
+    if not has_dot_installed:
+        pytest.skip(f"Test {request.node.nodeid} requires 'dot' that is not installed.")

python_statemachine-2.6.0/contributing.md

@@ -0,0 +1 @@
+Please see [docs/contributing.md](docs/contributing).

python_statemachine-2.6.0/docs/_static/custom_machine.css

@@ -0,0 +1,59 @@
+/* div.sphx-glr-download {
+    height: 0px;
+    visibility: hidden;
+} */
+
+@media only screen and (min-width: 650px) {
+
+    .sphx-glr-thumbnails {
+        grid-template-columns: repeat(auto-fill, minmax(600px, 1fr)) !important;
+    }
+
+    .sphx-glr-thumbcontainer {
+        min-height: 320px !important;
+        margin: 20px !important;
+        justify-content: center;
+    }
+    .sphx-glr-thumbcontainer .figure {
+        width: 600px !important;
+    }
+    .sphx-glr-thumbcontainer img {
+        max-height: 250px !important;
+        max-width: 600px !important;
+        width: 100% !important;
+    }
+    .sphx-glr-thumbcontainer a.internal {
+        padding: 20px 10px 0 !important;
+    }
+
+}
+
+/* Gallery Donwload buttons */
+div.sphx-glr-download a {
+    color: #404040 !important;
+    background-color: #f3f6f6 !important;
+    background-image: none;
+    border-radius: 4px;
+    border: none;
+    display: inline-block;
+    font-weight: bold;
+    padding: 1ex;
+    text-align: center;
+  }
+
+  div.sphx-glr-download code.download {
+    display: inline-block;
+    white-space: normal;
+    word-break: normal;
+    overflow-wrap: break-word;
+    /* border and background are given by the enclosing 'a' */
+    border: none;
+    background: none;
+  }
+
+  div.sphx-glr-download a:hover {
+    box-shadow: none;
+    text-decoration: none;
+    background-image: none;
+    background-color: #e5ebeb !important;
+  }