|
| 1 | +# Python 3.11/3.12 Support Implementation Plan |
| 2 | + |
| 3 | +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. |
| 4 | +
|
| 5 | +**Goal:** Lower the supported-Python floor from 3.13 to 3.11 so the package installs and runs on 3.11, 3.12, 3.13, and 3.14. |
| 6 | + |
| 7 | +**Architecture:** Pure-Python library, no compiled extensions. Two source constructs require 3.12+ (`type` statement and `typing.override`); both are backported via `typing_extensions` (declared as a direct runtime dependency, no `sys.version_info` gating). The rest is metadata (`requires-python`, classifiers, ruff target) and a wider CI matrix. |
| 8 | + |
| 9 | +**Tech Stack:** Python, faststream 0.7, redis 8, anyio, `typing_extensions`, uv (package manager), just (task runner), ruff + ty (lint/type-check), pytest, docker compose (integration suite + Redis). |
| 10 | + |
| 11 | +## Global Constraints |
| 12 | + |
| 13 | +- New Python floor: `requires-python = ">=3.11,<4"`. All edits must remain valid on CPython 3.11 through 3.14. |
| 14 | +- `typing_extensions` floor is `>=4.12.0` (matches faststream's existing transitive pin; `override` has existed there since 4.4.0). |
| 15 | +- `import` statements live at module level only — never inside function bodies. |
| 16 | +- Type-checker suppressions use `# ty: ignore[...]`, never `# type: ignore`. |
| 17 | +- `uv.lock` is git-ignored — do not commit it. Regenerating it locally is still required so local runs resolve. |
| 18 | +- Coverage gate is 100% (`--cov-fail-under=100`); the full suite enforces it. Local 3.11 subset runs use `--no-cov` to bypass the gate (they are an import/runtime smoke check, not the coverage gate). |
| 19 | +- `typing.Self` (`broker.py:155`) stays as-is — it exists in the 3.11 stdlib. |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +### Task 1: Make the package compatible with Python 3.11/3.12 |
| 24 | + |
| 25 | +Lowers the floor, adds the `typing_extensions` dependency, and rewrites the two incompatible constructs. The pyproject floor change and the source fixes are inseparable: the `override` fix can only be proven by importing on a real 3.11 interpreter, which uv refuses until `requires-python` is lowered; and the ruff `target-version` must move to `py311` alongside the `configs.py` edit or `ruff --fix` (UP040) will revert it. |
| 26 | + |
| 27 | +**Files:** |
| 28 | +- Modify: `pyproject.toml` (dependencies, `requires-python`, classifiers, `[tool.ruff] target-version`) |
| 29 | +- Modify: `faststream_redis_timers/configs.py:17` |
| 30 | +- Modify: `faststream_redis_timers/registrator.py:3` |
| 31 | +- Modify: `faststream_redis_timers/broker.py` (import block + decorators at 150/154/159/164) |
| 32 | +- Modify: `faststream_redis_timers/subscriber/usecase.py` (import block + decorators at 69/164/169) |
| 33 | +- Regenerate (do not commit): `uv.lock` |
| 34 | + |
| 35 | +**Interfaces:** |
| 36 | +- Consumes: nothing from earlier tasks. |
| 37 | +- Produces: a package importable on 3.11; the public `RedisClient` type alias keeps its name and meaning (`"Redis[bytes] | Redis[str]"`). No public API names change. |
| 38 | + |
| 39 | +- [ ] **Step 1: Confirm the current break on 3.11 (RED)** |
| 40 | + |
| 41 | +Use the local uv-managed 3.11 interpreter to show `configs.py` does not even parse on 3.11: |
| 42 | + |
| 43 | +```bash |
| 44 | +PY311=/Users/kevinsmith/.local/share/uv/python/cpython-3.11.9-macos-aarch64-none/bin/python3.11 |
| 45 | +$PY311 -m py_compile faststream_redis_timers/configs.py |
| 46 | +``` |
| 47 | + |
| 48 | +Expected: FAIL with `SyntaxError: invalid syntax` (the PEP 695 `type` statement at line 17). This is the failing state the task fixes. (The `override` import break in the other files is an `ImportError`, not a `SyntaxError`, so it is proven later by the runtime test in Step 8, not here.) |
| 49 | + |
| 50 | +- [ ] **Step 2: Edit `pyproject.toml` — dependency, floor, classifiers, ruff target (all together)** |
| 51 | + |
| 52 | +In `[project]`, change the dependencies block from: |
| 53 | + |
| 54 | +```toml |
| 55 | +dependencies = [ |
| 56 | + "faststream>=0.7.1,<0.8", |
| 57 | + "redis>=5.0", |
| 58 | +] |
| 59 | +``` |
| 60 | + |
| 61 | +to: |
| 62 | + |
| 63 | +```toml |
| 64 | +dependencies = [ |
| 65 | + "faststream>=0.7.1,<0.8", |
| 66 | + "redis>=5.0", |
| 67 | + "typing-extensions>=4.12.0", |
| 68 | +] |
| 69 | +``` |
| 70 | + |
| 71 | +Change the floor from: |
| 72 | + |
| 73 | +```toml |
| 74 | +requires-python = ">=3.13,<4" |
| 75 | +``` |
| 76 | + |
| 77 | +to: |
| 78 | + |
| 79 | +```toml |
| 80 | +requires-python = ">=3.11,<4" |
| 81 | +``` |
| 82 | + |
| 83 | +In the `classifiers` list, change: |
| 84 | + |
| 85 | +```toml |
| 86 | + "Programming Language :: Python :: 3.13", |
| 87 | + "Programming Language :: Python :: 3.14", |
| 88 | +``` |
| 89 | + |
| 90 | +to (add 3.11 and 3.12 above 3.13): |
| 91 | + |
| 92 | +```toml |
| 93 | + "Programming Language :: Python :: 3.11", |
| 94 | + "Programming Language :: Python :: 3.12", |
| 95 | + "Programming Language :: Python :: 3.13", |
| 96 | + "Programming Language :: Python :: 3.14", |
| 97 | +``` |
| 98 | + |
| 99 | +In `[tool.ruff]`, change: |
| 100 | + |
| 101 | +```toml |
| 102 | +target-version = "py313" |
| 103 | +``` |
| 104 | + |
| 105 | +to: |
| 106 | + |
| 107 | +```toml |
| 108 | +target-version = "py311" |
| 109 | +``` |
| 110 | + |
| 111 | +- [ ] **Step 3: Regenerate the lock and sync** |
| 112 | + |
| 113 | +Run: `uv lock --upgrade && uv sync --all-extras --all-groups` |
| 114 | +Expected: resolves cleanly; `typing-extensions` appears in the lock (it was already present transitively). Do NOT `git add uv.lock` — it is git-ignored. |
| 115 | + |
| 116 | +- [ ] **Step 4: Fix `configs.py` — replace the PEP 695 `type` statement** |
| 117 | + |
| 118 | +Change line 17 from: |
| 119 | + |
| 120 | +```python |
| 121 | +type RedisClient = "Redis[bytes] | Redis[str]" |
| 122 | +``` |
| 123 | + |
| 124 | +to: |
| 125 | + |
| 126 | +```python |
| 127 | +RedisClient: TypeAlias = "Redis[bytes] | Redis[str]" |
| 128 | +``` |
| 129 | + |
| 130 | +Add the import at the top of `configs.py`. The current first import line is `import typing`; add after it: |
| 131 | + |
| 132 | +```python |
| 133 | +from typing_extensions import TypeAlias |
| 134 | +``` |
| 135 | + |
| 136 | +Leave the explanatory comment block immediately above the alias untouched. |
| 137 | + |
| 138 | +- [ ] **Step 5: Fix `registrator.py` — import `override` from `typing_extensions`** |
| 139 | + |
| 140 | +Change line 3 from: |
| 141 | + |
| 142 | +```python |
| 143 | +from typing import Any, override |
| 144 | +``` |
| 145 | + |
| 146 | +to two lines: |
| 147 | + |
| 148 | +```python |
| 149 | +from typing import Any |
| 150 | +from typing_extensions import override |
| 151 | +``` |
| 152 | + |
| 153 | +The `@override` decorator usages at lines 18 and 63 (and their `# ty: ignore[invalid-method-override]` comments) are unchanged. |
| 154 | + |
| 155 | +- [ ] **Step 6: Fix `broker.py` — import `override` from `typing_extensions`, swap decorators** |
| 156 | + |
| 157 | +`broker.py` uses `import typing` (line 2) and references `@typing.override` four times plus `typing.Self` once. Keep `import typing` (still needed for `typing.Self` and other `typing.*` uses). Add this import to the top-of-file import block (after the existing `import typing`): |
| 158 | + |
| 159 | +```python |
| 160 | +from typing_extensions import override |
| 161 | +``` |
| 162 | + |
| 163 | +Then replace every `@typing.override` with `@override` (4 occurrences: lines 150, 154, 159, 164). Do NOT touch `async def __aenter__(self) -> typing.Self:` at line 155 — `typing.Self` stays. |
| 164 | + |
| 165 | +- [ ] **Step 7: Fix `subscriber/usecase.py` — import `override` from `typing_extensions`, swap decorators** |
| 166 | + |
| 167 | +This file uses `import typing` (line 3) and `@typing.override` three times. Add to the top-of-file import block (after `import typing`): |
| 168 | + |
| 169 | +```python |
| 170 | +from typing_extensions import override |
| 171 | +``` |
| 172 | + |
| 173 | +Then replace every `@typing.override` with `@override` (3 occurrences: lines 69, 164, 169). Keep `import typing` (other `typing.*` uses remain). |
| 174 | + |
| 175 | +- [ ] **Step 8: Verify the package imports and the unit/fake suites pass on real 3.11 (GREEN)** |
| 176 | + |
| 177 | +These suites need no Redis. Run them on a true 3.11 interpreter via uv (now permitted because the floor is `>=3.11`): |
| 178 | + |
| 179 | +```bash |
| 180 | +uv run --python 3.11 pytest tests/test_unit.py tests/test_fake.py --no-cov -v |
| 181 | +``` |
| 182 | + |
| 183 | +Expected: PASS. This proves both fixes at runtime on 3.11 — the `configs.py` parse fix and that `typing_extensions.override` imports cleanly where `typing.override` would have raised `ImportError`. |
| 184 | + |
| 185 | +If `uv run --python 3.11` is awkward in the environment, the fallback is an explicit ephemeral env: |
| 186 | + |
| 187 | +```bash |
| 188 | +uv venv --python 3.11 /private/tmp/claude-501/-Users-kevinsmith-src-pypi-faststream-redis-timers/b6781fe7-4d7e-4081-b268-8696cf7ad9e6/scratchpad/v311 |
| 189 | +VIRTUAL_ENV=/private/tmp/claude-501/-Users-kevinsmith-src-pypi-faststream-redis-timers/b6781fe7-4d7e-4081-b268-8696cf7ad9e6/scratchpad/v311 uv sync --all-extras --all-groups |
| 190 | +VIRTUAL_ENV=/private/tmp/claude-501/-Users-kevinsmith-src-pypi-faststream-redis-timers/b6781fe7-4d7e-4081-b268-8696cf7ad9e6/scratchpad/v311 uv run --no-sync pytest tests/test_unit.py tests/test_fake.py --no-cov -v |
| 191 | +``` |
| 192 | + |
| 193 | +- [ ] **Step 9: Lint against the new floor** |
| 194 | + |
| 195 | +Run: `just lint-ci` |
| 196 | +Expected: PASS. Specifically confirms (a) ruff under `target-version = "py311"` accepts `RedisClient: TypeAlias = ...` and does NOT flag it for conversion back to the `type` statement (UP040 only fires at py312+), and (b) `ty` accepts `typing_extensions.override` and `typing.Self`. |
| 197 | + |
| 198 | +- [ ] **Step 10: Run the full suite (no regression on 3.13 + 100% coverage)** |
| 199 | + |
| 200 | +Run: `just test` |
| 201 | +Expected: PASS, coverage 100%. This is the docker integration run (Redis on 3.13); confirms the source changes did not regress the existing platform. |
| 202 | + |
| 203 | +- [ ] **Step 11: Commit** |
| 204 | + |
| 205 | +```bash |
| 206 | +git add pyproject.toml faststream_redis_timers/configs.py faststream_redis_timers/registrator.py faststream_redis_timers/broker.py faststream_redis_timers/subscriber/usecase.py |
| 207 | +git commit -m "feat: support Python 3.11 and 3.12 |
| 208 | +
|
| 209 | +Backport the PEP 695 type alias and typing.override via typing_extensions, |
| 210 | +lower requires-python to >=3.11, add 3.11/3.12 classifiers and ruff target. |
| 211 | +
|
| 212 | +Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>" |
| 213 | +``` |
| 214 | + |
| 215 | +--- |
| 216 | + |
| 217 | +### Task 2: Add 3.11 and 3.12 to the CI test matrix |
| 218 | + |
| 219 | +The pytest job in CI currently runs only 3.13 and 3.14. Extend it so the new floor is exercised on every PR. |
| 220 | + |
| 221 | +**Files:** |
| 222 | +- Modify: `.github/workflows/_checks.yml` (the `pytest` job's `strategy.matrix.python-version`) |
| 223 | + |
| 224 | +**Interfaces:** |
| 225 | +- Consumes: the 3.11-compatible package from Task 1. |
| 226 | +- Produces: nothing consumed by later tasks (terminal task). |
| 227 | + |
| 228 | +- [ ] **Step 1: Edit the matrix** |
| 229 | + |
| 230 | +In the `pytest` job, change: |
| 231 | + |
| 232 | +```yaml |
| 233 | + python-version: |
| 234 | + - "3.13" |
| 235 | + - "3.14" |
| 236 | +``` |
| 237 | +
|
| 238 | +to: |
| 239 | +
|
| 240 | +```yaml |
| 241 | + python-version: |
| 242 | + - "3.11" |
| 243 | + - "3.12" |
| 244 | + - "3.13" |
| 245 | + - "3.14" |
| 246 | +``` |
| 247 | +
|
| 248 | +Leave the `lint` job (which runs `uv python install 3.13`) unchanged — linting against one interpreter is sufficient and ruff's `target-version` already enforces the floor. |
| 249 | + |
| 250 | +- [ ] **Step 2: Validate the workflow YAML parses** |
| 251 | + |
| 252 | +Run: `uv run python -c "import yaml; yaml.safe_load(open('.github/workflows/_checks.yml')); print('yaml ok')"` |
| 253 | +Expected: prints `yaml ok` with no exception. (`pyyaml` is available transitively via the dev tooling; if it is not, `python -c "import yaml"` will fail and you can skip this step — the edit is a 2-line list addition.) |
| 254 | + |
| 255 | +- [ ] **Step 3: Commit** |
| 256 | + |
| 257 | +```bash |
| 258 | +git add .github/workflows/_checks.yml |
| 259 | +git commit -m "ci: run pytest matrix on Python 3.11 and 3.12 |
| 260 | +
|
| 261 | +Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>" |
| 262 | +``` |
| 263 | + |
| 264 | +--- |
| 265 | + |
| 266 | +## Notes for the finish |
| 267 | + |
| 268 | +- `Dockerfile` stays on `python:3.13-slim` — it is the dev/test image, not a supported-version gate; no change. |
| 269 | +- No `architecture/` page or doc references the version floor, so no capability promotion is required (verified during planning). |
| 270 | +- After both tasks: push the branch and open a PR (do not local-merge); watch CI — the new 3.11/3.12 matrix legs are the real cross-version proof. |
0 commit comments