Add support for Python 3.14 (#312)

Author: joshuadavidthomas

.readthedocs.yaml

@@ -6,8 +6,8 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.13"
-    rust: "latest"
+    python: latest
+    rust: latest
   commands:
     - asdf plugin add just && asdf install just latest && asdf global just latest
     - asdf plugin add uv && asdf install uv latest && asdf global uv latest

CHANGELOG.md

@@ -18,6 +18,10 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Added
+
+- Added support for Python 3.14
+
 ## [5.2.2]
 
 ### Added

CONTRIBUTING.md

@@ -8,6 +8,81 @@ Not all contributions need to start with an issue, such as typo fixes in documen
 
 We adhere to Django's Code of Conduct in all interactions and expect all contributors to do the same. Please read the [Code of Conduct](https://www.djangoproject.com/conduct/) before contributing.
 
+## Development
+
+### Version Updates
+
+#### Python
+
+The project uses [`noxfile.py`](noxfile.py) as the single source of truth for supported Python versions. The `PY_VERSIONS` list in this file controls:
+
+- **Auto-generated documentation**: [cogapp](https://nedbatchelder.com/code/cog/) reads `PY_VERSIONS` to generate Python version classifiers in [`pyproject.toml`](pyproject.toml) and the supported versions list in [`README.md`](README.md)
+- **CI/CD test matrix**: GitHub Actions workflows call the `gha_matrix` nox session to dynamically generate the test matrix from `PY_VERSIONS`, ensuring all supported Python versions are tested automatically
+- **Local testing**: The `tests` nox session uses `PY_VERSIONS` to parametrize test runs across all supported Python versions
+
+> [!NOTE]
+> When possible, prefer submitting additions and removals in separate pull requests. This makes it easier to review changes and track the impact of each version update independently.
+
+**To update the list of supported Python versions:**
+
+1. Update [`noxfile.py`](noxfile.py), adding or removing version constants as needed and updating the `PY_VERSIONS` list accordingly.
+
+   For example, given the following versions:
+
+   ```python
+   PY39 = "3.9"
+   PY310 = "3.10"
+   PY311 = "3.11"
+   PY312 = "3.12"
+   PY313 = "3.13"
+   PY_VERSIONS = [PY39, PY310, PY311, PY312, PY313]
+   ```
+
+   To add Python 3.14 and remove Python 3.9, the final list will be:
+
+   ```python
+   PY310 = "3.10"
+   PY311 = "3.11"
+   PY312 = "3.12"
+   PY313 = "3.13"
+   PY314 = "3.14"
+   PY_VERSIONS = [PY310, PY311, PY312, PY313, PY314]
+   ```
+
+2. Regenerate auto-generated content:
+
+   ```bash
+   just cog
+   ```
+
+   This updates:
+
+   - The `requires-python` field in [`pyproject.toml`](pyproject.toml)
+   - Python version trove classifiers in [`pyproject.toml`](pyproject.toml)
+   - Supported versions list in [`README.md`](README.md)
+
+3. Update the lock file:
+
+   ```bash
+   uv lock
+   ```
+
+4. Test the changes:
+
+   ```bash
+   just testall
+   ```
+
+   Use `just testall` rather than `just test` to ensure all Python versions are tested. The `just test` command only runs against the default versions (the oldest supported Python and Django LTS) and won't catch issues with newly added versions.
+
+   If you want, you can also test only a specific Python version across all Django versions by `nox` directly:
+
+   ```bash
+   nox --python 3.14 --session tests
+   ```
+
+5. Update [`CHANGELOG.md`](CHANGELOG.md), adding entries for any versions added or removed.
+
 ### `Justfile`
 
 The repository includes a [`Justfile`](./Justfile) that provides all common development tasks with a consistent interface. Running `just` without arguments shows all available commands and their descriptions.

README.md

@@ -63,7 +63,7 @@ django_versions = [
 cog.outl(f"- Python {', '.join(PY_VERSIONS)}")
 cog.outl(f"- Django {', '.join(django_versions)}")
 ]]] -->
-- Python 3.9, 3.10, 3.11, 3.12, 3.13
+- Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
 - Django 4.2, 5.1, 5.2, 6.0
 <!-- [[[end]]] -->
 

noxfile.py

@@ -4,9 +4,11 @@
 import os
 import re
 import shutil
+import tempfile
 from pathlib import Path
 
 import nox
+from nox.command import CommandFailed
 
 nox.options.default_venv_backend = "uv|virtualenv"
 nox.options.reuse_existing_virtualenvs = True
@@ -16,7 +18,8 @@
 PY311 = "3.11"
 PY312 = "3.12"
 PY313 = "3.13"
-PY_VERSIONS = [PY39, PY310, PY311, PY312, PY313]
+PY314 = "3.14"
+PY_VERSIONS = [PY39, PY310, PY311, PY312, PY313, PY314]
 PY_DEFAULT = PY_VERSIONS[0]
 PY_LATEST = PY_VERSIONS[-1]
 
@@ -114,21 +117,51 @@ def tests(session, django):
 
 @nox.session
 def lint(session):
-    session.run(
-        "uv",
-        "run",
-        "--no-project",
-        "--with",
-        "pre-commit-uv",
-        "--python",
-        PY_LATEST,
-        "pre-commit",
-        "run",
-        "--all-files",
-        "--show-diff-on-failure",
-        "--color",
-        "always",
-    )
+    for python_version in reversed(PY_VERSIONS):
+        with tempfile.TemporaryFile(mode="w+") as output_file:
+            try:
+                session.run(
+                    "uv",
+                    "run",
+                    "--no-project",
+                    "--with",
+                    "pre-commit-uv",
+                    "--python",
+                    python_version,
+                    "pre-commit",
+                    "run",
+                    "--all-files",
+                    "--show-diff-on-failure",
+                    "--color",
+                    "always",
+                    stdout=output_file,
+                    stderr=output_file,
+                )
+                output_file.seek(0)
+                output = output_file.read().rstrip("\n")
+                if output:
+                    print(output)
+                break
+            except CommandFailed as e:
+                # Parse exit code from exception reason: "Returned code X"
+                match = re.search(r"Returned code (\d+)", e.reason or "")
+                exit_code = int(match.group(1)) if match else None
+
+                # Only retry on exit code 3 (infrastructure error)
+                if exit_code == 3:
+                    session.log(
+                        f"Linting with Python {python_version} failed due to pre-commit infrastructure issue (exit code 3), trying next version"
+                    )
+                    continue
+                else:
+                    # Real lint failure (exit code 1) or unknown error - re-raise
+                    output_file.seek(0)
+                    error_output = output_file.read().rstrip("\n")
+                    if error_output:
+                        print(error_output)
+                    raise
+    else:
+        session.error("Linting failed with all Python versions")
 
 
 @nox.session
@@ -221,19 +254,6 @@ def cog(session):
         "-r",
         *COG_FILES,
     )
-    git_status = session.run("git", "status", "--porcelain", external=True, silent=True)
-    if not any(cog_file in git_status for cog_file in COG_FILES):
-        session.log("No changes to documentation files, skipping commit")
-        return
-    session.run("git", "add", *COG_FILES, external=True)
-    session.run(
-        "git",
-        "commit",
-        "-m",
-        "auto-regenerate docs using cog",
-        external=True,
-        silent=True,
-    )
 
 
 @nox.session

pyproject.toml

@@ -24,7 +24,15 @@ readme = "README.md"
 authors = [
   { name = "Josh Thomas", email = "[email protected]" }
 ]
+# [[[cog
+# import cog
+#
+# from noxfile import PY_DEFAULT
+#
+# cog.outl(f'requires-python = ">={PY_DEFAULT}"')
+# ]]] -->
 requires-python = ">=3.9"
+# [[[end]]]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Framework :: Django",
@@ -65,6 +73,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   # [[[end]]]
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Rust",
@@ -143,8 +152,6 @@ extend-include = ["*.pyi?"]
 indent-width = 4
 # Same as Black.
 line-length = 88
-# Assume Python 3.9
-target-version = "py39"
 
 [tool.ruff.format]
 # Like Black, indent with spaces, rather than tabs.