Skip to content

Commit f2d71ff

Browse files
lesnik512claude
andauthored
Support Python 3.11 and 3.12 (#49)
* docs: design spec for Python 3.11/3.12 support Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: implementation plan for Python 3.11/3.12 support Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat: support Python 3.11 and 3.12 Backport the PEP 695 type alias and typing.override via typing_extensions, lower requires-python to >=3.11, add 3.11/3.12 classifiers and ruff target. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * ci: run pytest matrix on Python 3.11 and 3.12 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: note datetime.UTC as a 3.11-floor non-issue in design spec Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix ci * fix: cancel orphaned poll task when broker start times out A start_timeout that fires left the spawned _consume polling task running (add_task happens before the fail_after wait), since the caller never reaches __aexit__/stop. The orphan kept a Redis connection alive and deadlocked fixture/event-loop teardown on slow runners (observed as a hang in the new 3.11 CI leg; faster interpreters tore down before the orphan blocked). start() now cancels and awaits the poll task if the start signal times out, so a failed start leaves no orphan. Adds a deterministic regression test asserting no task leaks after a failed start. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent c765da2 commit f2d71ff

10 files changed

Lines changed: 443 additions & 15 deletions

File tree

‎.github/workflows/_checks.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ jobs:
2121
fail-fast: false
2222
matrix:
2323
python-version:
24+
- "3.11"
25+
- "3.12"
2426
- "3.13"
2527
- "3.14"
2628
services:
@@ -43,7 +45,7 @@ jobs:
4345
- run: uv python install ${{ matrix.python-version }}
4446
- run: |
4547
uv sync --all-extras --no-install-project
46-
uv run --no-sync pytest . --cov=. --cov-report xml
48+
uv run --no-sync pytest . --cov=. --cov-report xml -vvv
4749
env:
4850
PYTHONDONTWRITEBYTECODE: 1
4951
PYTHONUNBUFFERED: 1

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@ dist/
2020
.venv
2121
uv.lock
2222
/plan.md
23+
/site/
Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
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

Comments
 (0)