chore/Python-version-pin · L-261023-028959

.github/workflows/deploy-docs.yml

@@ -18,7 +18,7 @@ jobs:
 
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.x'
+          python-version-file: .python-version
 
       - name: Check UV installation
         run: make check-uv

.github/workflows/doc-check.yml

@@ -13,6 +13,9 @@ on:
 jobs:
   doc-check:
     runs-on: ubuntu-latest
+    env:
+      # The docs check runs Python 3.11 on purpose, not the version .python-version pins: this keeps any uv command on it too.
+      UV_PYTHON: "3.11"
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/lint-check.yml

@@ -20,6 +20,7 @@ jobs:
         python-version: ["3.11", "3.12", "3.13", "3.14"]
     env:
       VIRTUAL_ENV: ${{ github.workspace }}/.venv
+      UV_PYTHON: ${{ matrix.python-version }}
 
     steps:
       - uses: actions/checkout@v4
@@ -36,7 +37,7 @@ jobs:
         run: uv --version
 
       - name: Install dependencies
-        run: PYTHON_VERSION=${{ matrix.python-version }} make install
+        run: make install
 
       - name: Run ruff format merge check
         run: make merge-check-ruff-format
@@ -50,6 +51,9 @@ jobs:
       - name: Run mypy merge check
         run: make merge-check-mypy
 
+      - name: The interpreter is the one this job names
+        run: .venv/bin/python -c 'import sys; want = "${{ matrix.python-version }}"; got = "%d.%d" % sys.version_info[:2]; assert got == want, f"ran {got}, expected {want}"'
+
 # --------------------------------------------------------------------------
 # 2.  Aggregator job — the *single* required status check
 # --------------------------------------------------------------------------

.github/workflows/tests-check.yml

@@ -24,6 +24,7 @@ jobs:
       # Our CI never sends usage statistics: the off switch every Pipelex tool honours. The pinned pipelex sends none and
       # reads DO_NOT_TRACK only to turn its own telemetry off, which it honours at any boot.
       DO_NOT_TRACK: "1"
+      UV_PYTHON: ${{ matrix.python-version }}
     steps:
       - uses: actions/checkout@v4
 
@@ -39,7 +40,10 @@ jobs:
         run: uv --version
 
       - name: Install dependencies
-        run: PYTHON_VERSION=${{ matrix.python-version }} make install
+        run: make install
 
       - name: Run tests
         run: make gha-tests
+
+      - name: The interpreter is the one this job names
+        run: .venv/bin/python -c 'import sys; want = "${{ matrix.python-version }}"; got = "%d.%d" % sys.version_info[:2]; assert got == want, f"ran {got}, expected {want}"'

.python-version

@@ -0,0 +1 @@
+3.13

CHANGELOG.md

@@ -10,6 +10,7 @@
 - **`pipelex` 0.83.0 (Breaking)**: Bumped `pipelex` from `0.46.4` to `0.83.0`, with its `cli` extra added beside `anthropic`, `bedrock`, `google` and `google-genai`. This release has no Pipelex Gateway and refuses to boot on a configuration a Gateway release set up, so anyone with their own `.pipelex/` directory runs `pipelex migrate`, then edits any storage `uri_format` that names `{primary_id}` or `{secondary_id}`, which 0.83.0 also refuses and the migration leaves alone.
 - **Model setup: one OpenAI key (Breaking)**: cocode's inference configuration switches on the OpenAI backend alone and carries Pipelex 0.83.0's model catalogs and model deck, which resolve every tier cocode uses to OpenAI's GPT-5.6 models, where cocode previously ran Claude and Gemini models through the Gateway. The package now carries that configuration and runs on it from any directory without an inference configuration of its own, so a `pip install` needs only `OPENAI_API_KEY`, in a `.env` file or in `~/.pipelex/.env`, where it used to work only from the cocode directory. To run on another provider, switch its backend on in a git-ignored `.pipelex/inference/backends_override.toml` and point the whole model deck at its models in a deck file of your own, as the README shows; the docs no longer offer the free Discord key, `PIPELEX_API_KEY` or `PIPELEX_GATEWAY_API_KEY`, and `.env.example` lists the variable of every provider.
 - **`make agent-test` and `make codex-tests`**: Run without inference, as `make gha-tests` does, so they boot with no provider key, and CI now dry-runs every pipe.
+- **Dev tooling: the development Python is pinned in `.python-version`**: the Makefile, uv and CI read the version from that file, and `PYTHON_VERSION=<version> make install` now rebuilds an existing `.venv` on the version it names, where it used to leave the environment on its old Python without a word. Each job of the CI lint and test matrices now fails unless its environment ran the version the job names. Nothing shipped changes.
 
 ### Fixed
 - **Docs:** `CLI_README.md`'s example of extracting Python files from the cookbook now reads its `recipes` directory. The cookbook's redesign removed the `examples` directory it pointed at, so the example extracted nothing.

CONTRIBUTING.md

@@ -46,6 +46,12 @@ We are open to contributions in all areas of our core cocode library:
   - Dev deps: `uv pip install --extra dev <package>`
   - Keep dependencies alphabetically ordered in pyproject.toml
 
+## The Python interpreter
+
+The development environment in `.venv` runs the Python version that `.python-version`, at the repository root, names. The Makefile reads that file and hands the version to every uv command it runs, and uv reads the same file on its own when you call it outside the Makefile, so the terminal, the editor and CI agree on one interpreter. An environment built on another Python moves back to the pinned one at the next `make install`, whose `uv sync` replaces a `.venv` that runs a version other than the one requested; the targets that only run tools out of `.venv`, such as `make test` or `make check`, use it as they find it.
+
+To try another version that `requires-python` in `pyproject.toml` allows, run `PYTHON_VERSION=3.11 make install`, or set `UV_PYTHON`, which the Makefile honours the same way, and a plain `make install` afterwards returns the environment to the pin. CI tests every supported version: each job of the lint and test matrices sets `UV_PYTHON` to its version for the whole job and ends by checking that `.venv` ran that version.
+
 ## Pull Request Process
 
 - Fork the cocode repository

Makefile

@@ -5,8 +5,10 @@ endif
 VIRTUAL_ENV := $(CURDIR)/.venv
 PROJECT_NAME := $(shell grep '^name = ' pyproject.toml | sed -E 's/name = "(.*)"/\1/')
 
-# The "?" is used to make the variable optional, so that it can be overridden by the user.
-PYTHON_VERSION ?= 3.13
+# The interpreter is the one .python-version names, unless PYTHON_VERSION or UV_PYTHON asks for another.
+# Exporting it hands the same version to every uv command, so `uv sync` never rebuilds .venv on the pin.
+PYTHON_VERSION ?= $(or $(UV_PYTHON),$(shell cat .python-version))
+export UV_PYTHON := $(PYTHON_VERSION)
 VENV_PYTHON := $(VIRTUAL_ENV)/bin/python
 VENV_PYTEST := $(VIRTUAL_ENV)/bin/pytest
 VENV_COCODE := $(VIRTUAL_ENV)/bin/cocode