Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

chore/Python-version-pin · L-261023-976b8b (#1481)

Louis Choquel942906379681
diff --git a/.github/workflows/check-test-count-badge.yml b/.github/workflows/check-test-count-badge.yml
index 96c76ed24..4610a5ab7 100644
--- a/.github/workflows/check-test-count-badge.yml
+++ b/.github/workflows/check-test-count-badge.yml
@@ -22,7 +22,7 @@ jobs:
- name: Set up Python
uses: actions/setup-python@v5
with:
- python-version: "3.11"
+ python-version-file: .python-version
- name: Check UV installation
run: make check-uv
diff --git a/.github/workflows/dependency-canary.yml b/.github/workflows/dependency-canary.yml
index 03ff961e0..4922099f0 100644
--- a/.github/workflows/dependency-canary.yml
+++ b/.github/workflows/dependency-canary.yml
@@ -31,6 +31,7 @@ jobs:
matrix:
python-version: ["3.11", "3.13"]
env:
+ UV_PYTHON: ${{ matrix.python-version }}
VIRTUAL_ENV: ${{ github.workspace }}/.venv
ENV: dev
PIPELEX_NO_DECK_NOTICE: "1"
@@ -38,7 +39,7 @@ jobs:
- uses: actions/checkout@v4
- name: Install
- run: PYTHON_VERSION=${{ matrix.python-version }} make install
+ run: make install
- name: Upgrade dependencies to latest within ranges
run: uv lock --upgrade && uv sync --all-extras
@@ -52,6 +53,9 @@ jobs:
.venv/bin/pipelex validate bundle tests/data/packages/analytics_dep/analytics.mthds
.venv/bin/pipelex run bundle tests/data/packages/analytics_dep/analytics.mthds --dry-run --mock-inputs
+ - 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. Force the typer/click family PAST its pyproject cap, then run the CLI
# smoke test and the real CLI commands. This is the signal to bump the cap:
# when it goes red, a new typer/click broke the CLI -- validate, fix if
diff --git a/.github/workflows/doc-check.yml b/.github/workflows/doc-check.yml
index 50b7dd47b..396fb248b 100644
--- a/.github/workflows/doc-check.yml
+++ b/.github/workflows/doc-check.yml
@@ -25,13 +25,14 @@ jobs:
needs: check-changes
if: needs.check-changes.outputs.should-run == 'true'
runs-on: ubuntu-latest
+ env:
+ UV_PYTHON: "3.11"
steps:
- uses: actions/checkout@v4
- name: Install uv (with cache)
uses: astral-sh/setup-uv@v7
with:
- python-version: '3.11'
enable-cache: true
cache-dependency-glob: "uv.lock"
diff --git a/.github/workflows/lint-check.yml b/.github/workflows/lint-check.yml
index ede891327..f9f74592a 100644
--- a/.github/workflows/lint-check.yml
+++ b/.github/workflows/lint-check.yml
@@ -19,6 +19,7 @@ jobs:
name: Lint (ruff + plxt)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -31,7 +32,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run ruff format merge check
run: make merge-check-ruff-format
@@ -58,6 +59,7 @@ jobs:
matrix:
python-version: ["3.11"]
env:
+ UV_PYTHON: ${{ matrix.python-version }}
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -70,7 +72,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Restore mypy cache
uses: actions/cache@v4
@@ -87,6 +89,9 @@ jobs:
- name: Run mypy merge check (Python ${{ matrix.python-version }})
run: LINT_PYTHON_VERSION=${{ matrix.python-version }} 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}"'
+
# --------------------------------------------------------------------------
# 3. Config sync — single job, version-independent
# --------------------------------------------------------------------------
@@ -94,6 +99,7 @@ jobs:
name: Lint (config-sync)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -106,7 +112,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run config sync check
run: make check-config-sync
@@ -118,6 +124,7 @@ jobs:
name: Lint (keyword-only)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -130,7 +137,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run keyword-only convention check
run: make check-keyword-only
@@ -142,6 +149,7 @@ jobs:
name: Lint (hub layering)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -154,7 +162,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run hub layering check
run: make check-hub-layering
@@ -167,6 +175,7 @@ jobs:
name: Lint (rich imports)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -179,7 +188,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run Rich import check
run: make check-rich-imports
@@ -195,6 +204,7 @@ jobs:
name: Lint (actions allowlist)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -207,7 +217,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run Actions allowlist check
run: make check-actions-allowlist
@@ -225,6 +235,7 @@ jobs:
name: Lint (log calls)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -237,7 +248,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Fetch the pull request's base
run: git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.sha }}"
@@ -257,6 +268,7 @@ jobs:
name: Lint (drift-contracts)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -269,7 +281,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run drift contracts check
run: make drift-check
@@ -281,6 +293,7 @@ jobs:
name: Lint (agent-rules)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -293,7 +306,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run agent rules sync check
run: make check-rules
@@ -311,6 +324,8 @@ jobs:
lint-api:
name: Lint (api)
runs-on: ubuntu-latest
+ env:
+ UV_PYTHON: "3.11"
steps:
- uses: actions/checkout@v4
@@ -322,7 +337,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install the server's environment
- run: PYTHON_VERSION=3.11 make -C api install
+ run: make -C api install
- name: Run ruff format merge check
run: make -C api merge-check-ruff-format
diff --git a/.github/workflows/lint-fresh-check.yml b/.github/workflows/lint-fresh-check.yml
index e8e40140d..16b25d889 100644
--- a/.github/workflows/lint-fresh-check.yml
+++ b/.github/workflows/lint-fresh-check.yml
@@ -33,7 +33,10 @@ jobs:
fail-fast: false
matrix:
python-version: ["3.11", "3.12", "3.13", "3.14"]
+ # Every cell runs in a 3.11 environment: the matrix names the version pyright and mypy
+ # check against (LINT_PYTHON_VERSION), not the interpreter.
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
@@ -46,7 +49,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
# No mypy cache restore anywhere in this workflow — the clean run is the point.
@@ -102,7 +105,7 @@ jobs:
# lint-check.yml checks it on the floor version on every pull request, and this leg adds the
# version this matrix row names, so the versions its classifiers claim are the ones checked.
- name: Install the API server's environment
- run: PYTHON_VERSION=3.11 make -C api install
+ run: make -C api install
- name: Run the API server's ruff merge checks
run: make -C api merge-check-ruff-format merge-check-ruff-lint
diff --git a/.github/workflows/manual-trigger-tests-check.yml b/.github/workflows/manual-trigger-tests-check.yml
index 596b0b82a..3d7945a02 100644
--- a/.github/workflows/manual-trigger-tests-check.yml
+++ b/.github/workflows/manual-trigger-tests-check.yml
@@ -36,6 +36,7 @@ jobs:
actions: read
repository-projects: read
env:
+ UV_PYTHON: ${{ matrix.python-version }}
VIRTUAL_ENV: ${{ github.workspace }}/.venv
ENV: dev
@@ -60,10 +61,13 @@ jobs:
run: uv --version
- name: Install dependencies
- run: PYTHON_VERSION=${{ matrix.python-version }} make install
+ run: make install
- name: Boot test
run: make tp TEST=TestFundamentals
- name: Run tests
- run: make run-manual-trigger-gha-tests
\ No newline at end of file
+ run: make run-manual-trigger-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}"'
diff --git a/.github/workflows/mthds-standard-check.yml b/.github/workflows/mthds-standard-check.yml
index f1f155410..c1f25045c 100644
--- a/.github/workflows/mthds-standard-check.yml
+++ b/.github/workflows/mthds-standard-check.yml
@@ -31,6 +31,7 @@ jobs:
name: "Pinned natives vs the standard's page (a red with no pinned-set change in this PR means the standard moved)"
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/pipelex/.venv
ENV: dev
# The documented workspace layout, reproduced on the runner: this repo and the standard as
@@ -67,7 +68,7 @@ jobs:
cache-dependency-glob: "pipelex/uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 make install
+ run: make install
- name: Hold the pinned natives to the standard's page
run: .venv/bin/pytest tests/unit/pipelex/core/concepts/test_pinned_natives_vs_standard.py -v
diff --git a/.github/workflows/tests-check.yml b/.github/workflows/tests-check.yml
index 8ee4061fa..cb73fa83c 100644
--- a/.github/workflows/tests-check.yml
+++ b/.github/workflows/tests-check.yml
@@ -34,6 +34,7 @@ jobs:
matrix:
group: [1, 2, 3, 4, 5, 6, 7, 8]
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
ENV: dev
PIPELEX_HANG_DUMP_DIR: /tmp/pipelex-hang-dumps-${{ github.run_id }}-shard${{ matrix.group }}
@@ -47,7 +48,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 make install
+ run: make install
# Fast install-health canary on one shard only: a broken install fails
# every shard identically, so paying the boot smoke test 8x is waste.
@@ -86,6 +87,7 @@ jobs:
name: Tests (ts emission gates)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
VIRTUAL_ENV: ${{ github.workspace }}/.venv
ENV: dev
steps:
@@ -104,7 +106,7 @@ jobs:
node-version: "24"
- name: Install dependencies
- run: PYTHON_VERSION=3.11 TEST_PROFILE=ci make install
+ run: TEST_PROFILE=ci make install
- name: Run the TypeScript emission gates
run: make test-ts-gates
@@ -120,6 +122,7 @@ jobs:
name: Tests (api)
runs-on: ubuntu-latest
env:
+ UV_PYTHON: "3.11"
ENV: dev
steps:
- uses: actions/checkout@v4
@@ -131,7 +134,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install the server's environment
- run: PYTHON_VERSION=3.11 make -C api install
+ run: make -C api install
- name: Run the server's tests
run: make -C api gha-tests
diff --git a/.github/workflows/tests-full-check.yml b/.github/workflows/tests-full-check.yml
index bc9b61a19..45002221e 100644
--- a/.github/workflows/tests-full-check.yml
+++ b/.github/workflows/tests-full-check.yml
@@ -38,6 +38,7 @@ jobs:
python-version: ["3.11", "3.12", "3.13", "3.14"]
group: [1, 2, 3, 4, 5, 6, 7, 8]
env:
+ UV_PYTHON: ${{ matrix.python-version }}
VIRTUAL_ENV: ${{ github.workspace }}/.venv
ENV: dev
PIPELEX_HANG_DUMP_DIR: /tmp/pipelex-hang-dumps-${{ github.run_id }}-py${{ matrix.python-version }}-shard${{ matrix.group }}
@@ -55,7 +56,7 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install dependencies
- run: PYTHON_VERSION=${{ matrix.python-version }} make install
+ run: make install
- name: Run tests (py${{ matrix.python-version }}, shard ${{ matrix.group }}/8)
run: SPLITS=8 GROUP=${{ matrix.group }} make gha-tests
@@ -73,6 +74,9 @@ jobs:
echo "No hang dumps were produced."
fi
+ - 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}"'
+
# --------------------------------------------------------------------------
# The API server (`api/`) on every supported version, in its own environment
# against the pipelex of this commit. Its suite is small, so one job per
@@ -87,6 +91,7 @@ jobs:
matrix:
python-version: ["3.11", "3.12", "3.13", "3.14"]
env:
+ UV_PYTHON: ${{ matrix.python-version }}
ENV: dev
steps:
- uses: actions/checkout@v4
@@ -100,11 +105,14 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install the server's environment
- run: PYTHON_VERSION=${{ matrix.python-version }} make -C api install
+ run: make -C api install
- name: Run the server's tests (py${{ matrix.python-version }})
run: make -C api gha-tests
+ - name: The interpreter is the one this job names
+ run: api/.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}"'
+
# --------------------------------------------------------------------------
# Aggregator — the single required status check for the full-matrix gate.
# Green only if every shard of every version passes, and the API server's
diff --git a/.python-version b/.python-version
new file mode 100644
index 000000000..24ee5b1be
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.13
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 49df77f34..553a9f568 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,7 @@
- **A hosted run sends its method as a tree (Breaking)**: `pipelex run --hosted` and `pipelex-agent run --runner hosted` send a local method to `/v1/pipe-io`, `/v1/start` and `/v1/execute` as the MTHDS protocol's `files` map, each `.mthds` bundle under its path in the method's tree and each library directory beside the method under a top-level folder named after it, inline up to 256 KiB and by hash beyond, where the run took the bundles' bare contents and pipe-io a list the runner now refuses with a `422`, so a hosted run whose inputs name a local file reads the signature again, and a method that does not load is reported by the tree path of each faulty file. `HostedRunRequest` (`pipelex.hosted.hosted_run`) takes `contents`, each bundle's bytes by tree path, in place of `mthds_files`. A file of the tree that cannot be uploaded stops the run before anything starts, as pipelex-sdk's `MethodFileTransferError`, which both CLIs report with the SDK's verdict and a next step: run again, or report a file the storage refused. A bundle file given with `-L` that the membership rule keeps out of its tree, a hidden one under a dot segment or one `.gitignore` excludes, is refused before anything is sent, as a local run refuses it, where it was sent as it was.
- **A hosted run's lost connection follows pipelex-sdk's reading**: `pipelex run --hosted` and `pipelex-agent run --runner hosted` report a connection lost on the start or the execute request as `HostedRunOutcomeUnknownError` (`client.outcome_unknown`) whenever pipelex-sdk reads it as one that may have started the run (`run_may_have_started`), a proxy's failure and a TLS handshake that was dropped included, which read as an unreachable API, while a connection lost on a request sent before the run's, such as the blob check of a tree sent by hash, stays pipelex-sdk's `ApiUnreachableError`.
- **`pipelex-agent validate bundle` and `fix bundle` exit 2 on a configuration refused before the boot**: a configuration that does not validate, which these commands read before the boot for the limits a method's folder is listed under, exits 2, no verdict, where it exited 1, as `pipelex validate bundle` and `pipelex fix bundle` exit on it; the problem is unchanged, and `run bundle` and `inputs bundle` still exit 1.
+- **The development Python is pinned in `.python-version`**: the library's `.venv` and the API server's `api/.venv` are built on the version the root `.python-version` names, and the Makefiles hand that version to every uv command, so `PYTHON_VERSION=<version> make install` now moves an existing environment to the version asked for, where it used to keep the environment's own Python without a word. The CI jobs that run another version set it for the whole job, and the matrix jobs check that each cell ran the version it names.
### Fixed
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e7845c862..ebe6de814 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,6 +46,8 @@ We are open to contributions in all areas of our core Pipelex library:
- Dev deps: `uv add --optional dev <package>`
- Keep dependencies alphabetically ordered in pyproject.toml
+The development interpreter is the one `.python-version` names at the root of the repository, and it serves both the library's `.venv` and the API server's `api/.venv`. The next `make install` moves an environment built on another Python to that version, and so does the next `make -C api install` for the server's. `PYTHON_VERSION=<version> make install` builds the environment on another supported version instead, and the next plain `make install` returns it to the pinned one.
+
## Pull Request Process
- Fork the Pipelex repository
diff --git a/Makefile b/Makefile
index d23891822..a9cc9925a 100644
--- a/Makefile
+++ b/Makefile
@@ -8,8 +8,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)
LINT_PYTHON_VERSION ?=
# Note: VENV_* variables include quotes to handle paths with spaces (e.g., "My Projects/pipelex")
VENV_PYTHON := "$(VIRTUAL_ENV)/bin/python"
diff --git a/api/Makefiles/Makefile_basics.mk b/api/Makefiles/Makefile_basics.mk
index 734dfb545..df4335aac 100644
--- a/api/Makefiles/Makefile_basics.mk
+++ b/api/Makefiles/Makefile_basics.mk
@@ -14,8 +14,10 @@ PROJECT_NAME := $(shell grep '^name = ' pyproject.toml | sed -E 's/name = "(.*)"
export UV_PROJECT_ENVIRONMENT := $(VIRTUAL_ENV)
WORKSPACE_ROOT := $(abspath $(CURDIR)/..)
-# 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 the workspace root's .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 "$(WORKSPACE_ROOT)/.python-version"))
+export UV_PYTHON := $(PYTHON_VERSION)
# The Python version pyright and mypy check against, when it is not the environment's own: the root's
# pre-main gate (`lint-fresh-check.yml`) checks every supported version from one 3.11 environment.
LINT_PYTHON_VERSION ?=