ADR 0003 — Support Python 3.11 to 3.13¶

Status: Accepted
Date: 2026-10-14
Supersedes: ADR 0001, the "Python 3.13 for the whole repo" decision only. The rest of ADR 0001 stands.

[!NOTE] This page records why the decision was made, as it stood on the date in its header. It is not updated when the code changes. For the current requirements, read Installation.

Context¶

ADR 0001 moved the whole repository to Python 3.13 because stacklok's mcp-builder requires it and nw calls the vendored generator in-process. The published packages (node-wire-runtime, -bindings, -toolhive, the connectors and the meta package) kept requires-python = ">=3.11" and cp311/cp312/cp313 wheels, so the repository and its packages disagreed about which Pythons are supported.

Decision¶

Decision	Why
The repository supports Python 3.11, 3.12 and 3.13. The root project, `nw-cli`, `nw-connector-builder`, `nw-mcp-builder` and `nw-stacklok-builder` declare `requires-python = ">=3.11"`, like the published packages.	One supported range for the whole repo. The vendored stacklok code needs no 3.12+ language or library features: every source file parses under 3.11, and the full test suite passed on 3.11, 3.12 and 3.13 on the date of this record.
Ruff targets `py311` and mypy checks as 3.11.	Lint and type checks then flag code that would not run on the oldest supported version.
CI runs the test suite on 3.11, 3.12 and 3.13 on Ubuntu. macOS and Windows run 3.13 only.	Every supported version is tested on every pull request, without tripling the slower runners.
Generated MCP hosts (`nw-mcp-builder`) and stacklok servers (`nw gen-stacklok`) still target 3.13 images (`python:3.13-slim`, `dhi.io/python:3.13-alpine`).	Their wheels are compiled for the image's cp313 ABI. Those projects are deployment artifacts, not part of the supported development range.

Consequences¶

requires-python has no upper bound, so 3.14 is allowed to install but is not tested.
The open question in ADR 0001 about dropping 3.11/3.12 from published wheels no longer applies.
Branch protection lists required checks by name. Adding the 3.11 and 3.12 Ubuntu legs, or relying on the Pytest matrix complete gate, is a repository-settings change.