Skip to content

Commit 46f427b

Browse files
authored
Read Python version from .tool-versions (#996)
## Summary - read the Python version from an explicitly selected `.tool-versions` file - preserve `python-version` and existing `UV_PYTHON` precedence - add parser, input, and workflow coverage and update documentation and bundled action artifacts ## Validation - `npm run all` - `actionlint .github/workflows/test.yml` - `uvx zizmor .github/workflows/test.yml` Closes #983 Refs: pi-session 019ff01a-544c-79f3-8f73-a00132af39f5
1 parent 8ed89c5 commit 46f427b

12 files changed

Lines changed: 400 additions & 49 deletions

File tree

‎.github/workflows/test.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,31 @@ jobs:
234234
exit 1
235235
fi
236236
237+
test-tool-versions-python-version:
238+
runs-on: ubuntu-latest
239+
steps:
240+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
241+
with:
242+
persist-credentials: false
243+
- name: Install versions from .tool-versions
244+
id: setup-uv
245+
uses: ./
246+
with:
247+
version-file: "__tests__/fixtures/.tool-versions"
248+
- name: Verify Python version from .tool-versions
249+
run: |
250+
if [ "$UV_PYTHON" != "3.13.1t" ]; then
251+
echo "Wrong UV_PYTHON: $UV_PYTHON"
252+
exit 1
253+
fi
254+
if [ "$PYTHON_VERSION" != "3.13.1t" ]; then
255+
echo "Wrong python-version output: $PYTHON_VERSION"
256+
exit 1
257+
fi
258+
shell: bash
259+
env:
260+
PYTHON_VERSION: ${{ steps.setup-uv.outputs.python-version }}
261+
237262
test-malformed-pyproject-file-fallback:
238263
runs-on: ubuntu-latest
239264
steps:
@@ -1126,6 +1151,7 @@ jobs:
11261151
- test-from-working-directory-version
11271152
- test-malformed-pyproject-file-fallback
11281153
- test-version-file-version
1154+
- test-tool-versions-python-version
11291155
- test-checksum
11301156
- test-with-explicit-token
11311157
- test-uvx

‎README.md‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,13 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
4747
# The version of uv to install, e.g., "0.5.0", "latest", or "latest-known" (default: searches for version in config files, then latest)
4848
version: ""
4949
50-
# Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock (default: searches uv.toml then pyproject.toml)
50+
# Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. A selected .tool-versions file can also provide the Python version (default: searches uv.toml then pyproject.toml)
5151
version-file: ""
5252
5353
# Resolution strategy when resolving version ranges: 'highest' or 'lowest'
5454
resolution-strategy: "highest"
5555
56-
# The version of Python to set UV_PYTHON to
56+
# The version of Python to set UV_PYTHON to (overrides the Python version from .tool-versions)
5757
python-version: ""
5858
5959
# Use uv venv to activate a venv ready to be used by later steps
@@ -144,7 +144,25 @@ Have a look under [Advanced Configuration](#advanced-configuration) for detailed
144144

145145
You can use the input `python-version` to set the environment variable `UV_PYTHON` for the rest of your workflow
146146

147-
This will override any python version specifications in `pyproject.toml` and `.python-version`
147+
This will override any python version specifications in `pyproject.toml`, `.python-version`, and
148+
an explicitly selected `.tool-versions` file.
149+
150+
When `version-file` points to `.tool-versions`, its `python` entry is used if neither
151+
`python-version` nor `UV_PYTHON` is set:
152+
153+
```text
154+
uv 0.12.3
155+
python 3.13
156+
```
157+
158+
```yaml
159+
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
160+
with:
161+
version-file: ".tool-versions"
162+
```
163+
164+
Only a single Python version is supported. Multiple fallback versions and the asdf `ref:`, `path:`,
165+
and `system` forms are ignored with a warning.
148166

149167
```yaml
150168
- name: Install the latest version of uv and set the python version to 3.13t

‎__tests__/fixtures/.tool-versions‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
uv 0.5.15
2+
python 3.13.1t

‎__tests__/utils/inputs.test.ts‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ const ORIGINAL_HOME = process.env.HOME;
1818
const ORIGINAL_RUNNER_ENVIRONMENT = process.env.RUNNER_ENVIRONMENT;
1919
const ORIGINAL_RUNNER_TEMP = process.env.RUNNER_TEMP;
2020
const ORIGINAL_UV_CACHE_DIR = process.env.UV_CACHE_DIR;
21+
const ORIGINAL_UV_PYTHON = process.env.UV_PYTHON;
2122
const ORIGINAL_UV_PYTHON_INSTALL_DIR = process.env.UV_PYTHON_INSTALL_DIR;
2223

2324
const mockDebug = jest.fn();
@@ -60,6 +61,7 @@ function resetEnvironment(): void {
6061
delete process.env.RUNNER_ENVIRONMENT;
6162
delete process.env.RUNNER_TEMP;
6263
delete process.env.UV_CACHE_DIR;
64+
delete process.env.UV_PYTHON;
6365
delete process.env.UV_PYTHON_INSTALL_DIR;
6466
}
6567

@@ -74,6 +76,7 @@ function restoreEnvironment(): void {
7476
process.env.RUNNER_ENVIRONMENT = ORIGINAL_RUNNER_ENVIRONMENT;
7577
process.env.RUNNER_TEMP = ORIGINAL_RUNNER_TEMP;
7678
process.env.UV_CACHE_DIR = ORIGINAL_UV_CACHE_DIR;
79+
process.env.UV_PYTHON = ORIGINAL_UV_PYTHON;
7780
process.env.UV_PYTHON_INSTALL_DIR = ORIGINAL_UV_PYTHON_INSTALL_DIR;
7881
}
7982

@@ -100,6 +103,52 @@ describe("loadInputs", () => {
100103
expect(inputs.resolutionStrategy).toBe("highest");
101104
});
102105

106+
it("uses the Python version from an explicitly selected .tool-versions file", () => {
107+
mockInputs["working-directory"] = createTempProject({
108+
".tool-versions": "uv 0.12.3\npython 3.13.1t\n",
109+
});
110+
mockInputs["version-file"] = ".tool-versions";
111+
112+
const inputs = loadInputs();
113+
114+
expect(inputs.pythonVersion).toBe("3.13.1t");
115+
});
116+
117+
it("prefers the python-version input over .tool-versions", () => {
118+
mockInputs["working-directory"] = createTempProject({
119+
".tool-versions": "uv 0.12.3\npython 3.13\n",
120+
});
121+
mockInputs["version-file"] = ".tool-versions";
122+
mockInputs["python-version"] = "3.12";
123+
124+
const inputs = loadInputs();
125+
126+
expect(inputs.pythonVersion).toBe("3.12");
127+
});
128+
129+
it("preserves UV_PYTHON instead of overriding it from .tool-versions", () => {
130+
mockInputs["working-directory"] = createTempProject({
131+
".tool-versions": "uv 0.12.3\npython 3.13\n",
132+
});
133+
mockInputs["version-file"] = ".tool-versions";
134+
process.env.UV_PYTHON = "3.11";
135+
136+
const inputs = loadInputs();
137+
138+
expect(inputs.pythonVersion).toBe("");
139+
expect(process.env.UV_PYTHON).toBe("3.11");
140+
});
141+
142+
it("does not discover .tool-versions from the working directory", () => {
143+
mockInputs["working-directory"] = createTempProject({
144+
".tool-versions": "uv 0.12.3\npython 3.13\n",
145+
});
146+
147+
const inputs = loadInputs();
148+
149+
expect(inputs.pythonVersion).toBe("");
150+
});
151+
103152
it.each(["pull_request_target", "workflow_run", "release"])(
104153
"disables automatic caching for the %s event",
105154
(eventName) => {

‎__tests__/version/tool-versions-file.test.ts‎

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,11 @@ async function getVersionFromToolVersions(filePath: string) {
2121
return getUvVersionFromToolVersions(filePath);
2222
}
2323

24+
async function getPythonVersionFromToolVersions(filePath: string) {
25+
const module = await import("../../src/version/tool-versions-file");
26+
return module.getPythonVersionFromToolVersions(filePath);
27+
}
28+
2429
describe("getUvVersionFromToolVersions", () => {
2530
beforeEach(() => {
2631
jest.resetModules();
@@ -61,8 +66,8 @@ describe("getUvVersionFromToolVersions", () => {
6166
expect(result).toBe("0.3.0");
6267
});
6368

64-
it("should skip commented lines", async () => {
65-
const fileContent = "# uv 0.1.0\npython 3.11.0\nuv 0.2.0";
69+
it("should skip comments", async () => {
70+
const fileContent = "# uv 0.1.0\npython 3.11.0\nuv 0.2.0 # inline comment";
6671
mockReadFileSync.mockReturnValue(fileContent);
6772

6873
const result = await getVersionFromToolVersions(".tool-versions");
@@ -121,3 +126,68 @@ describe("getUvVersionFromToolVersions", () => {
121126
);
122127
});
123128
});
129+
130+
describe("getPythonVersionFromToolVersions", () => {
131+
beforeEach(() => {
132+
jest.resetModules();
133+
jest.clearAllMocks();
134+
});
135+
136+
it("should return version for a valid Python entry", async () => {
137+
mockReadFileSync.mockReturnValue(
138+
"nodejs 24.0.0\r\npython v3.13.1t # use free-threaded Python\r\nuv 0.12.3",
139+
);
140+
141+
const result = await getPythonVersionFromToolVersions(".tool-versions");
142+
143+
expect(result).toBe("3.13.1t");
144+
});
145+
146+
it("should return the first matching Python version", async () => {
147+
mockReadFileSync.mockReturnValue("python 3.12\npython 3.13");
148+
149+
const result = await getPythonVersionFromToolVersions(".tool-versions");
150+
151+
expect(result).toBe("3.12");
152+
});
153+
154+
it("should return undefined when no Python entry is found", async () => {
155+
mockReadFileSync.mockReturnValue("uv 0.12.3\nnodejs 24.0.0");
156+
157+
const result = await getPythonVersionFromToolVersions(".tool-versions");
158+
159+
expect(result).toBeUndefined();
160+
});
161+
162+
it("should warn and return undefined for multiple Python versions", async () => {
163+
mockReadFileSync.mockReturnValue("python 3.13 3.12 system");
164+
165+
const result = await getPythonVersionFromToolVersions(".tool-versions");
166+
167+
expect(result).toBeUndefined();
168+
expect(mockWarning).toHaveBeenCalledWith(
169+
"Multiple Python versions in .tool-versions are not supported. The Python entry will be ignored.",
170+
);
171+
});
172+
173+
it.each(["ref:main", "path:~/src/python", "system"])(
174+
"should warn and return undefined for %s",
175+
async (version) => {
176+
mockReadFileSync.mockReturnValue(`python ${version}`);
177+
178+
const result = await getPythonVersionFromToolVersions(".tool-versions");
179+
180+
expect(result).toBeUndefined();
181+
expect(mockWarning).toHaveBeenCalledWith(
182+
`The Python version ${version} in .tool-versions is not supported. The Python entry will be ignored.`,
183+
);
184+
},
185+
);
186+
187+
it("should return undefined for non-.tool-versions files", async () => {
188+
const result = await getPythonVersionFromToolVersions(".python-version");
189+
190+
expect(result).toBeUndefined();
191+
expect(mockReadFileSync).not.toHaveBeenCalled();
192+
});
193+
});

‎action.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@ inputs:
77
description: "The version of uv to install, e.g., `0.5.0`, `latest`, or `latest-known`. Defaults to the version in pyproject.toml or `latest`."
88
default: ""
99
version-file:
10-
description: "Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. Defaults to searching for uv.toml and if not found pyproject.toml."
10+
description: "Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. A selected .tool-versions file can also provide the Python version. Defaults to searching for uv.toml and if not found pyproject.toml."
1111
default: ""
1212
python-version:
13-
description: "The version of Python to set UV_PYTHON to"
13+
description: "The version of Python to set UV_PYTHON to. Overrides the Python version from .tool-versions."
1414
required: false
1515
activate-environment:
1616
description: "Use uv venv to activate a venv ready to be used by later steps. "

‎dist/save-cache/index.cjs‎

Lines changed: 71 additions & 7 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)