Skip to content

Commit 9e62be8

Browse files
colesburycolesbury
authored
Support free threaded Python versions like '3.13t' (#973)
* Support free threaded Python versions like '3.13t' Python wheels, pyenv, and a number of other tools use 't' in the Python version number to identify free threaded builds. For example, '3.13t', '3.14.0a1', '3.14t-dev'. This PR supports that syntax in `actions/setup-python`, strips the "t", and adds "-freethreading" to the architecture to select the correct Python version. See #771 * Add free threading to advanced usage documentation * Fix desugaring of `3.13.1t` and add test case. * Add freethreaded input and fix handling of prerelease versions * Fix lint * Add 't' suffix to python-version output * Use distinct cache key for free threaded Python * Remove support for syntax like '3.14.0a1' * Clarify use of 't' suffix * Improve error message when trying to use free threaded Python versions before 3.13
1 parent 6ca8e85 commit 9e62be8

8 files changed

+226
-35
lines changed

‎README.md

+10
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,16 @@ steps:
4545
- run: python my_script.py
4646
```
4747
48+
**Free threaded Python**
49+
```yaml
50+
steps:
51+
- uses: actions/checkout@v4
52+
- uses: actions/setup-python@v5
53+
with:
54+
python-version: '3.13t'
55+
- run: python my_script.py
56+
```
57+
4858
The `python-version` input is optional. If not supplied, the action will try to resolve the version from the default `.python-version` file. If the `.python-version` file doesn't exist Python or PyPy version from the PATH will be used. The default version of Python or PyPy in PATH varies between runners and can be changed unexpectedly so we recommend always setting Python version explicitly using the `python-version` or `python-version-file` inputs.
4959

5060
The action will first check the local [tool cache](docs/advanced-usage.md#hosted-tool-cache) for a [semver](https://github.com/npm/node-semver#versions) match. If unable to find a specific version in the tool cache, the action will attempt to download a version of Python from [GitHub Releases](https://github.com/actions/python-versions/releases) and for PyPy from the official [PyPy's dist](https://downloads.python.org/pypy/).

‎__tests__/find-python.test.ts

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import {desugarVersion, pythonVersionToSemantic} from '../src/find-python';
2+
3+
describe('desugarVersion', () => {
4+
it.each([
5+
['3.13', {version: '3.13', freethreaded: false}],
6+
['3.13t', {version: '3.13', freethreaded: true}],
7+
['3.13.1', {version: '3.13.1', freethreaded: false}],
8+
['3.13.1t', {version: '3.13.1', freethreaded: true}],
9+
['3.14-dev', {version: '~3.14.0-0', freethreaded: false}],
10+
['3.14t-dev', {version: '~3.14.0-0', freethreaded: true}]
11+
])('%s -> %s', (input, expected) => {
12+
expect(desugarVersion(input)).toEqual(expected);
13+
});
14+
});
15+
16+
// Test the combined desugarVersion and pythonVersionToSemantic functions
17+
describe('pythonVersions', () => {
18+
it.each([
19+
['3.13', {version: '3.13', freethreaded: false}],
20+
['3.13t', {version: '3.13', freethreaded: true}],
21+
['3.13.1', {version: '3.13.1', freethreaded: false}],
22+
['3.13.1t', {version: '3.13.1', freethreaded: true}],
23+
['3.14-dev', {version: '~3.14.0-0', freethreaded: false}],
24+
['3.14t-dev', {version: '~3.14.0-0', freethreaded: true}]
25+
])('%s -> %s', (input, expected) => {
26+
const {version, freethreaded} = desugarVersion(input);
27+
const semanticVersionSpec = pythonVersionToSemantic(version, false);
28+
expect({version: semanticVersionSpec, freethreaded}).toEqual(expected);
29+
});
30+
31+
it.each([
32+
['3.13', {version: '~3.13.0-0', freethreaded: false}],
33+
['3.13t', {version: '~3.13.0-0', freethreaded: true}],
34+
['3.13.1', {version: '3.13.1', freethreaded: false}],
35+
['3.13.1t', {version: '3.13.1', freethreaded: true}],
36+
['3.14-dev', {version: '~3.14.0-0', freethreaded: false}],
37+
['3.14t-dev', {version: '~3.14.0-0', freethreaded: true}]
38+
])('%s (allowPreReleases=true) -> %s', (input, expected) => {
39+
const {version, freethreaded} = desugarVersion(input);
40+
const semanticVersionSpec = pythonVersionToSemantic(version, true);
41+
expect({version: semanticVersionSpec, freethreaded}).toEqual(expected);
42+
});
43+
});

‎__tests__/finder.test.ts

+32-11
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ describe('Finder tests', () => {
5656
await io.mkdirP(pythonDir);
5757
fs.writeFileSync(`${pythonDir}.complete`, 'hello');
5858
// This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
59-
await finder.useCpythonVersion('3.x', 'x64', true, false, false);
59+
await finder.useCpythonVersion('3.x', 'x64', true, false, false, false);
6060
expect(spyCoreAddPath).toHaveBeenCalled();
6161
expect(spyCoreExportVariable).toHaveBeenCalledWith(
6262
'pythonLocation',
@@ -73,7 +73,7 @@ describe('Finder tests', () => {
7373
await io.mkdirP(pythonDir);
7474
fs.writeFileSync(`${pythonDir}.complete`, 'hello');
7575
// This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
76-
await finder.useCpythonVersion('3.x', 'x64', false, false, false);
76+
await finder.useCpythonVersion('3.x', 'x64', false, false, false, false);
7777
expect(spyCoreAddPath).not.toHaveBeenCalled();
7878
expect(spyCoreExportVariable).not.toHaveBeenCalled();
7979
});
@@ -96,7 +96,7 @@ describe('Finder tests', () => {
9696
});
9797
// This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
9898
await expect(
99-
finder.useCpythonVersion('1.2.3', 'x64', true, false, false)
99+
finder.useCpythonVersion('1.2.3', 'x64', true, false, false, false)
100100
).resolves.toEqual({
101101
impl: 'CPython',
102102
version: '1.2.3'
@@ -135,7 +135,14 @@ describe('Finder tests', () => {
135135
});
136136
// This will throw if it doesn't find it in the manifest (because no such version exists)
137137
await expect(
138-
finder.useCpythonVersion('1.2.4-beta.2', 'x64', false, false, false)
138+
finder.useCpythonVersion(
139+
'1.2.4-beta.2',
140+
'x64',
141+
false,
142+
false,
143+
false,
144+
false
145+
)
139146
).resolves.toEqual({
140147
impl: 'CPython',
141148
version: '1.2.4-beta.2'
@@ -186,7 +193,7 @@ describe('Finder tests', () => {
186193

187194
fs.writeFileSync(`${pythonDir}.complete`, 'hello');
188195
// This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
189-
await finder.useCpythonVersion('1.2', 'x64', true, true, false);
196+
await finder.useCpythonVersion('1.2', 'x64', true, true, false, false);
190197

191198
expect(infoSpy).toHaveBeenCalledWith("Resolved as '1.2.3'");
192199
expect(infoSpy).toHaveBeenCalledWith(
@@ -197,7 +204,14 @@ describe('Finder tests', () => {
197204
);
198205
expect(installSpy).toHaveBeenCalled();
199206
expect(addPathSpy).toHaveBeenCalledWith(expPath);
200-
await finder.useCpythonVersion('1.2.4-beta.2', 'x64', false, true, false);
207+
await finder.useCpythonVersion(
208+
'1.2.4-beta.2',
209+
'x64',
210+
false,
211+
true,
212+
false,
213+
false
214+
);
201215
expect(spyCoreAddPath).toHaveBeenCalled();
202216
expect(spyCoreExportVariable).toHaveBeenCalledWith(
203217
'pythonLocation',
@@ -224,7 +238,7 @@ describe('Finder tests', () => {
224238
});
225239
// This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
226240
await expect(
227-
finder.useCpythonVersion('1.2', 'x64', false, false, false)
241+
finder.useCpythonVersion('1.2', 'x64', false, false, false, false)
228242
).resolves.toEqual({
229243
impl: 'CPython',
230244
version: '1.2.3'
@@ -251,25 +265,32 @@ describe('Finder tests', () => {
251265
});
252266
// This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
253267
await expect(
254-
finder.useCpythonVersion('1.1', 'x64', false, false, false)
268+
finder.useCpythonVersion('1.1', 'x64', false, false, false, false)
255269
).rejects.toThrow();
256270
await expect(
257-
finder.useCpythonVersion('1.1', 'x64', false, false, true)
271+
finder.useCpythonVersion('1.1', 'x64', false, false, true, false)
258272
).resolves.toEqual({
259273
impl: 'CPython',
260274
version: '1.1.0-beta.2'
261275
});
262276
// Check 1.1.0 version specifier does not fallback to '1.1.0-beta.2'
263277
await expect(
264-
finder.useCpythonVersion('1.1.0', 'x64', false, false, true)
278+
finder.useCpythonVersion('1.1.0', 'x64', false, false, true, false)
265279
).rejects.toThrow();
266280
});
267281

268282
it('Errors if Python is not installed', async () => {
269283
// This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
270284
let thrown = false;
271285
try {
272-
await finder.useCpythonVersion('3.300000', 'x64', true, false, false);
286+
await finder.useCpythonVersion(
287+
'3.300000',
288+
'x64',
289+
true,
290+
false,
291+
false,
292+
false
293+
);
273294
} catch {
274295
thrown = true;
275296
}

‎action.yml

+3
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ inputs:
2626
allow-prereleases:
2727
description: "When 'true', a version range passed to 'python-version' input will match prerelease versions if no GA versions are found. Only 'x.y' version range is supported for CPython."
2828
default: false
29+
freethreaded:
30+
description: "When 'true', use the freethreaded version of Python."
31+
default: false
2932
outputs:
3033
python-version:
3134
description: "The installed Python or PyPy version. Useful when given a version range as input."

‎dist/setup/index.js

+51-10
Original file line numberDiff line numberDiff line change
@@ -99514,7 +99514,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
9951499514
});
9951599515
};
9951699516
Object.defineProperty(exports, "__esModule", ({ value: true }));
99517-
exports.pythonVersionToSemantic = exports.useCpythonVersion = void 0;
99517+
exports.pythonVersionToSemantic = exports.desugarVersion = exports.useCpythonVersion = void 0;
9951899518
const os = __importStar(__nccwpck_require__(857));
9951999519
const path = __importStar(__nccwpck_require__(6928));
9952099520
const utils_1 = __nccwpck_require__(1798);
@@ -99542,13 +99542,22 @@ function binDir(installDir) {
9954299542
return path.join(installDir, 'bin');
9954399543
}
9954499544
}
99545-
function useCpythonVersion(version, architecture, updateEnvironment, checkLatest, allowPreReleases) {
99545+
function useCpythonVersion(version, architecture, updateEnvironment, checkLatest, allowPreReleases, freethreaded) {
9954699546
return __awaiter(this, void 0, void 0, function* () {
9954799547
var _a;
9954899548
let manifest = null;
99549-
const desugaredVersionSpec = desugarDevVersion(version);
99549+
const { version: desugaredVersionSpec, freethreaded: versionFreethreaded } = desugarVersion(version);
9955099550
let semanticVersionSpec = pythonVersionToSemantic(desugaredVersionSpec, allowPreReleases);
99551+
if (versionFreethreaded) {
99552+
// Use the freethreaded version if it was specified in the input, e.g., 3.13t
99553+
freethreaded = true;
99554+
}
9955199555
core.debug(`Semantic version spec of ${version} is ${semanticVersionSpec}`);
99556+
if (freethreaded) {
99557+
// Free threaded versions use an architecture suffix like `x64-freethreaded`
99558+
core.debug(`Using freethreaded version of ${semanticVersionSpec}`);
99559+
architecture += '-freethreaded';
99560+
}
9955299561
if (checkLatest) {
9955399562
manifest = yield installer.getManifest();
9955499563
const resolvedVersion = (_a = (yield installer.findReleaseFromManifest(semanticVersionSpec, architecture, manifest))) === null || _a === void 0 ? void 0 : _a.version;
@@ -99572,12 +99581,16 @@ function useCpythonVersion(version, architecture, updateEnvironment, checkLatest
9957299581
}
9957399582
if (!installDir) {
9957499583
const osInfo = yield (0, utils_1.getOSInfo)();
99575-
throw new Error([
99584+
const msg = [
9957699585
`The version '${version}' with architecture '${architecture}' was not found for ${osInfo
9957799586
? `${osInfo.osName} ${osInfo.osVersion}`
99578-
: 'this operating system'}.`,
99579-
`The list of all available versions can be found here: ${installer.MANIFEST_URL}`
99580-
].join(os.EOL));
99587+
: 'this operating system'}.`
99588+
];
99589+
if (freethreaded) {
99590+
msg.push(`Free threaded versions are only available for Python 3.13.0 and later.`);
99591+
}
99592+
msg.push(`The list of all available versions can be found here: ${installer.MANIFEST_URL}`);
99593+
throw new Error(msg.join(os.EOL));
9958199594
}
9958299595
const _binDir = binDir(installDir);
9958399596
const binaryExtension = utils_1.IS_WINDOWS ? '.exe' : '';
@@ -99617,12 +99630,39 @@ function useCpythonVersion(version, architecture, updateEnvironment, checkLatest
9961799630
// On Linux and macOS, pip will create the --user directory and add it to PATH as needed.
9961899631
}
9961999632
const installed = versionFromPath(installDir);
99620-
core.setOutput('python-version', installed);
99633+
let pythonVersion = installed;
99634+
if (freethreaded) {
99635+
// Add the freethreaded suffix to the version (e.g., 3.13.1t)
99636+
pythonVersion += 't';
99637+
}
99638+
core.setOutput('python-version', pythonVersion);
9962199639
core.setOutput('python-path', pythonPath);
99622-
return { impl: 'CPython', version: installed };
99640+
return { impl: 'CPython', version: pythonVersion };
9962399641
});
9962499642
}
9962599643
exports.useCpythonVersion = useCpythonVersion;
99644+
/* Desugar free threaded and dev versions */
99645+
function desugarVersion(versionSpec) {
99646+
const { version, freethreaded } = desugarFreeThreadedVersion(versionSpec);
99647+
return { version: desugarDevVersion(version), freethreaded };
99648+
}
99649+
exports.desugarVersion = desugarVersion;
99650+
/* Identify freethreaded versions like, 3.13t, 3.13.1t, 3.13t-dev.
99651+
* Returns the version without the `t` and the architectures suffix, if freethreaded */
99652+
function desugarFreeThreadedVersion(versionSpec) {
99653+
const majorMinor = /^(\d+\.\d+(\.\d+)?)(t)$/;
99654+
if (majorMinor.test(versionSpec)) {
99655+
return { version: versionSpec.replace(majorMinor, '$1'), freethreaded: true };
99656+
}
99657+
const devVersion = /^(\d+\.\d+)(t)(-dev)$/;
99658+
if (devVersion.test(versionSpec)) {
99659+
return {
99660+
version: versionSpec.replace(devVersion, '$1$3'),
99661+
freethreaded: true
99662+
};
99663+
}
99664+
return { version: versionSpec, freethreaded: false };
99665+
}
9962699666
/** Convert versions like `3.8-dev` to a version like `~3.8.0-0`. */
9962799667
function desugarDevVersion(versionSpec) {
9962899668
const devVersion = /^(\d+)\.(\d+)-dev$/;
@@ -100365,6 +100405,7 @@ function run() {
100365100405
const versions = resolveVersionInput();
100366100406
const checkLatest = core.getBooleanInput('check-latest');
100367100407
const allowPreReleases = core.getBooleanInput('allow-prereleases');
100408+
const freethreaded = core.getBooleanInput('freethreaded');
100368100409
if (versions.length) {
100369100410
let pythonVersion = '';
100370100411
const arch = core.getInput('architecture') || os.arch();
@@ -100385,7 +100426,7 @@ function run() {
100385100426
if (version.startsWith('2')) {
100386100427
core.warning('The support for python 2.7 was removed on June 19, 2023. Related issue: https://github.com/actions/setup-python/issues/672');
100387100428
}
100388-
const installed = yield finder.useCpythonVersion(version, arch, updateEnvironment, checkLatest, allowPreReleases);
100429+
const installed = yield finder.useCpythonVersion(version, arch, updateEnvironment, checkLatest, allowPreReleases, freethreaded);
100389100430
pythonVersion = installed.version;
100390100431
core.info(`Successfully set up ${installed.impl} (${pythonVersion})`);
100391100432
}

‎docs/advanced-usage.md

+25
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,31 @@ steps:
7777
- run: python my_script.py
7878
```
7979
80+
You can specify the [free threading](https://docs.python.org/3/howto/free-threading-python.html) version of Python by setting the `freethreaded` input to `true` or by using the special **t** suffix in some cases.
81+
You can use the **t** suffix when specifying the major and minor version (e.g., `3.13t`), with a patch version (e.g., `3.13.1t`), or with the **x.y-dev syntax** (e.g., `3.14t-dev`).
82+
Free threaded Python is only available starting with the 3.13 release.
83+
84+
```yaml
85+
steps:
86+
- uses: actions/checkout@v4
87+
- uses: actions/setup-python@v5
88+
with:
89+
python-version: '3.13t'
90+
- run: python my_script.py
91+
```
92+
93+
Note that the **t** suffix is not `semver` syntax. If you wish to specify a range, you must use the `freethreaded` input instead of the `t` suffix.
94+
95+
```yaml
96+
steps:
97+
- uses: actions/checkout@v4
98+
- uses: actions/setup-python@v5
99+
with:
100+
python-version: '>=3.13'
101+
freethreaded: true
102+
- run: python my_script.py
103+
```
104+
80105
You can also use several types of ranges that are specified in [semver](https://github.com/npm/node-semver#ranges), for instance:
81106

82107
- **[ranges](https://github.com/npm/node-semver#ranges)** to download and set up the latest available version of Python satisfying a range:

0 commit comments

Comments
 (0)