feat: Add Python 3.14 support (#552)

fgmacedo · web-flow · commit 7b5fb689f2ce · 2026-02-10T22:07:45.000-03:00
* style: apply ruff 0.15 import sorting and lint auto-fixes

Ruff 0.13+ changed isort behavior with force-single-line, requiring
import reordering. Also applies C420 (dict.fromkeys) and minor formatting.

* feat: add Python 3.14 support and make it the default

- Add Python 3.14 to CI test matrix and classifiers
- Update mypy python_version and ruff target-version to 3.14
- Update release workflow and ReadTheDocs to Python 3.14
- Remove stale Python 3.7 pydot step from CI
- Add UP037 and UP042 to ruff ignore (require future annotations / 3.11+)
- Remove stale UP038 ignore (rule removed from ruff)
- Add match parameter to pytest.warns (PT030)
- Upgrade ruff 0.8.1 -&gt; 0.15.0, mypy 1.4.1 -&gt; 1.14.1, watchfiles 0.24.0 -&gt; 1.1.1

* fix(ci): upgrade pillow 11.0.0 -&gt; 11.3.0 for Python 3.14 wheel support

Pillow 11.0.0 has no pre-built wheel for Python 3.14 and fails to
compile from source in CI due to missing libjpeg headers.

* fix(ci): upgrade pytest-cov/coverage for Python 3.14 annotation coverage

coverage.py &lt; 7.6.10 incorrectly reports class annotations as uncovered
on Python 3.14 due to PEP 649 deferred evaluation (coveragepy#1908).
Pin pytest-cov &gt;= 6.0.0 on Python &gt;= 3.9 to pull coverage &gt;= 7.6.10.
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
@@ -33,15 +33,11 @@ jobs:
         cache-suffix: "python${{ matrix.python-version }}"
     - name: Install the project
       run: uv sync --all-extras --dev
-    - name: Install old pydot for 3.7 only
-      if: matrix.python-version == 3.7
-      run: |
-        uv pip install pydot==2.0.0
       #----------------------------------------------
       #              run ruff
       #----------------------------------------------
     - name: Linter with ruff
-      if: matrix.python-version == 3.13
+      if: matrix.python-version == 3.14
       run: |
         uv run ruff check .
         uv run ruff format --check .
@@ -57,7 +53,7 @@ jobs:
       #----------------------------------------------
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
-      if: matrix.python-version == 3.13
+      if: matrix.python-version == 3.14
       with:
         token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
         directory: .
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -18,7 +18,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.13'
+          python-version: '3.14'
 
       - name: Setup Graphviz
         uses: ts-graphviz/setup-graphviz@v2
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -8,7 +8,7 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.12"
+    python: "3.14"
   apt_packages:
     - graphviz
   jobs:
diff --git a/AGENTS.md b/AGENTS.md
@@ -72,7 +72,7 @@ uv run mypy statemachine/ tests/
 
 ## Code style
 
-- **Formatter/Linter:** ruff (line length 99, target Python 3.13)
+- **Formatter/Linter:** ruff (line length 99, target Python 3.14)
 - **Rules:** pycodestyle, pyflakes, isort, pyupgrade, flake8-comprehensions, flake8-bugbear, flake8-pytest-style
 - **Imports:** single-line, sorted by isort
 - **Docstrings:** Google convention
diff --git a/conftest.py b/conftest.py
@@ -6,9 +6,10 @@
 
 @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
-    from statemachine.utils import run_async_from_sync
 
     class ContribAsyncio:
         """
diff --git a/pyproject.toml b/pyproject.toml
@@ -17,6 +17,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3.7",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
@@ -37,7 +38,8 @@ dev = [
     "pre-commit",
     "mypy",
     "pytest",
-    "pytest-cov",
+    "pytest-cov >=6.0.0; python_version >='3.9'",
+    "pytest-cov; python_version <'3.9'",
     "pytest-sugar >=1.0.0",
     "pytest-mock >=3.10.0",
     "pytest-benchmark >=4.0.0",
@@ -113,7 +115,7 @@ directory = "tmp/htmlcov"
 show_contexts = true
 
 [tool.mypy]
-python_version = "3.13"
+python_version = "3.14"
 warn_return_any = true
 warn_unused_configs = true
 disable_error_code = "annotation-unchecked"
@@ -127,7 +129,7 @@ ignore_missing_imports = true
 src = ["statemachine"]
 
 line-length = 99
-target-version = "py313"
+target-version = "py314"
 
 # Exclude a variety of commonly ignored directories.
 exclude = [
@@ -166,7 +168,8 @@ select = [
 ignore = [
     "UP006", # `use-pep585-annotation` Requires Python3.9+
     "UP035", # `use-pep585-annotation` Requires Python3.9+
-    "UP038", # `use-pep585-annotation` Requires Python3.9+
+    "UP037", # `remove-quotes-from-type-annotation` Not safe without `from __future__ import annotations`
+    "UP042", # `use-str-enum` Requires Python3.11+
 ]
 
 # Allow unused variables when underscore-prefixed.
diff --git a/statemachine/signature.py b/statemachine/signature.py
@@ -95,8 +95,7 @@ def bind_expected(self, *args: Any, **kwargs: Any) -> BoundArguments:  # noqa: C
                     elif param.name in kwargs:
                         if param.kind == Parameter.POSITIONAL_ONLY:
                             msg = (
-                                "{arg!r} parameter is positional only, "
-                                "but was passed as a keyword"
+                                "{arg!r} parameter is positional only, but was passed as a keyword"
                             )
                             msg = msg.format(arg=param.name)
                             raise TypeError(msg) from None
diff --git a/statemachine/statemachine.py b/statemachine/statemachine.py
@@ -182,7 +182,7 @@ def _add_listener(self, listeners: "Listeners", allowed_references: SpecReferenc
         return self
 
     def _register_callbacks(self, listeners: List[object]):
-        self._listeners.update({listener: None for listener in listeners})
+        self._listeners.update(dict.fromkeys(listeners))
         self._add_listener(
             Listeners.from_listeners(
                 (
@@ -223,7 +223,7 @@ def add_listener(self, *listeners):
 
             :ref:`listeners`.
         """
-        self._listeners.update({o: None for o in listeners})
+        self._listeners.update(dict.fromkeys(listeners))
         return self._add_listener(
             Listeners.from_listeners(Listener.from_obj(o) for o in listeners),
             allowed_references=SPECS_SAFE,
diff --git a/tests/django_project/workflow/models.py b/tests/django_project/workflow/models.py
@@ -1,6 +1,5 @@
 from django.contrib.auth import get_user_model
 from django.db import models
-
 from statemachine.mixins import MachineMixin
 
 User = get_user_model()
diff --git a/tests/django_project/workflow/statemachines.py b/tests/django_project/workflow/statemachines.py
@@ -1,6 +1,7 @@
-from statemachine import StateMachine
 from statemachine.states import States
 
+from statemachine import StateMachine
+
 from .models import WorkflowSteps
 
 
diff --git a/tests/django_project/workflow/tests.py b/tests/django_project/workflow/tests.py
@@ -1,6 +1,6 @@
 import pytest
-
 from statemachine.exceptions import TransitionNotAllowed
+
 from workflow.models import WorkflowSteps
 from workflow.statemachines import WorfklowStateMachine
 
diff --git a/tests/examples/air_conditioner_machine.py b/tests/examples/air_conditioner_machine.py
@@ -8,9 +8,10 @@
 
 import random
 
+from statemachine.utils import run_async_from_sync
+
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.utils import run_async_from_sync
 
 
 def sensor_temperature_reader(seed: int, lower: int = 15, higher: int = 35):
diff --git a/tests/examples/enum_campaign_machine.py b/tests/examples/enum_campaign_machine.py
@@ -9,9 +9,10 @@
 
 from enum import Enum
 
-from statemachine import StateMachine
 from statemachine.states import States
 
+from statemachine import StateMachine
+
 
 class CampaignStatus(Enum):
     DRAFT = 1
diff --git a/tests/examples/lor_machine.py b/tests/examples/lor_machine.py
@@ -6,9 +6,10 @@
 
 """
 
+from statemachine.exceptions import TransitionNotAllowed
+
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.exceptions import TransitionNotAllowed
 
 
 class LordOfTheRingsQuestStateMachine(StateMachine):
diff --git a/tests/examples/order_control_rich_model_machine.py b/tests/examples/order_control_rich_model_machine.py
@@ -6,9 +6,10 @@
 
 """
 
+from statemachine.exceptions import InvalidDefinition
+
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.exceptions import InvalidDefinition
 
 
 class Order:
diff --git a/tests/examples/user_machine.py b/tests/examples/user_machine.py
@@ -14,9 +14,10 @@
 from dataclasses import dataclass
 from enum import Enum
 
+from statemachine.states import States
+
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.states import States
 
 
 class UserStatus(str, Enum):
diff --git a/tests/test_async.py b/tests/test_async.py
@@ -1,10 +1,10 @@
 import re
 
 import pytest
+from statemachine.exceptions import InvalidStateValue
 
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.exceptions import InvalidStateValue
 
 
 @pytest.fixture()
diff --git a/tests/test_callbacks.py b/tests/test_callbacks.py
@@ -1,16 +1,16 @@
 from unittest import mock
 
 import pytest
-
-from statemachine import State
-from statemachine import StateMachine
 from statemachine.callbacks import CallbackGroup
 from statemachine.callbacks import CallbackSpec
 from statemachine.callbacks import CallbackSpecList
 from statemachine.callbacks import CallbacksRegistry
 from statemachine.dispatcher import resolver_factory_from_objects
 from statemachine.exceptions import InvalidDefinition
 
+from statemachine import State
+from statemachine import StateMachine
+
 
 @pytest.fixture()
 def ObjectWithCallbacks():
diff --git a/tests/test_conditions_algebra.py b/tests/test_conditions_algebra.py
@@ -1,8 +1,8 @@
 import pytest
+from statemachine.exceptions import InvalidDefinition
 
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.exceptions import InvalidDefinition
 
 
 class AnyConditionSM(StateMachine):
diff --git a/tests/test_contrib_diagram.py b/tests/test_contrib_diagram.py
@@ -2,7 +2,6 @@
 from unittest import mock
 
 import pytest
-
 from statemachine.contrib.diagram import DotGraphMachine
 from statemachine.contrib.diagram import main
 from statemachine.contrib.diagram import quickchart_write_svg
diff --git a/tests/test_copy.py b/tests/test_copy.py
@@ -5,11 +5,11 @@
 from enum import auto
 
 import pytest
+from statemachine.exceptions import TransitionNotAllowed
+from statemachine.states import States
 
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.exceptions import TransitionNotAllowed
-from statemachine.states import States
 
 logger = logging.getLogger(__name__)
 DEBUG = logging.DEBUG
diff --git a/tests/test_dispatcher.py b/tests/test_dispatcher.py
@@ -1,5 +1,4 @@
 import pytest
-
 from statemachine.callbacks import CallbackGroup
 from statemachine.callbacks import CallbackSpec
 from statemachine.dispatcher import Listener
diff --git a/tests/test_events.py b/tests/test_events.py
@@ -1,9 +1,9 @@
 import pytest
+from statemachine.event import Event
+from statemachine.exceptions import InvalidDefinition
 
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.event import Event
-from statemachine.exceptions import InvalidDefinition
 
 
 def test_assign_events_on_transitions():
diff --git a/tests/test_listener.py b/tests/test_listener.py
@@ -1,5 +1,4 @@
 import pytest
-
 from statemachine.state import State
 from statemachine.statemachine import StateMachine
 
diff --git a/tests/test_mixins.py b/tests/test_mixins.py
@@ -1,6 +1,6 @@
 import pytest
-
 from statemachine.mixins import MachineMixin
+
 from tests.models import MyModel
 
 
diff --git a/tests/test_registry.py b/tests/test_registry.py
@@ -28,7 +28,7 @@ class CampaignMachine(StateMachine):
     assert "CampaignMachine" in registry._REGISTRY
     assert registry.get_machine_cls("tests.test_registry.CampaignMachine") == CampaignMachine
 
-    with pytest.warns(DeprecationWarning):
+    with pytest.warns(DeprecationWarning, match="fully qualified names"):
         assert registry.get_machine_cls("CampaignMachine") == CampaignMachine
 
 
diff --git a/tests/test_rtc.py b/tests/test_rtc.py
@@ -2,11 +2,11 @@
 from unittest import mock
 
 import pytest
+from statemachine.exceptions import InvalidDefinition
+from statemachine.exceptions import TransitionNotAllowed
 
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.exceptions import InvalidDefinition
-from statemachine.exceptions import TransitionNotAllowed
 
 
 @pytest.fixture()
diff --git a/tests/test_signature.py b/tests/test_signature.py
@@ -2,7 +2,6 @@
 from functools import partial
 
 import pytest
-
 from statemachine.dispatcher import callable_method
 
 
diff --git a/tests/test_signature_positional_only.py b/tests/test_signature_positional_only.py
@@ -1,7 +1,6 @@
 import inspect
 
 import pytest
-
 from statemachine.dispatcher import callable_method
 
 
diff --git a/tests/test_spec_parser.py b/tests/test_spec_parser.py
@@ -1,7 +1,6 @@
 import logging
 
 import pytest
-
 from statemachine.spec_parser import operator_mapping
 from statemachine.spec_parser import parse_boolean_expr
 
diff --git a/tests/test_transition_list.py b/tests/test_transition_list.py
@@ -1,9 +1,9 @@
 import pytest
-
-from statemachine import State
 from statemachine.callbacks import CallbacksRegistry
 from statemachine.dispatcher import resolver_factory_from_objects
 
+from statemachine import State
+
 
 def test_transition_list_or_operator():
     s1 = State("s1", initial=True)
diff --git a/tests/test_transitions.py b/tests/test_transitions.py
@@ -1,9 +1,9 @@
 import pytest
+from statemachine.exceptions import InvalidDefinition
+from statemachine.transition import Transition
 
 from statemachine import State
 from statemachine import StateMachine
-from statemachine.exceptions import InvalidDefinition
-from statemachine.transition import Transition
 
 from .models import MyModel
 
diff --git a/uv.lock b/uv.lock
