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

__tests__/find-python.test.ts

@@ -0,0 +1,43 @@
+import {desugarVersion, pythonVersionToSemantic} from '../src/find-python';
+
+describe('desugarVersion', () => {
+  it.each([
+    ['3.13', {version: '3.13', freethreaded: false}],
+    ['3.13t', {version: '3.13', freethreaded: true}],
+    ['3.13.1', {version: '3.13.1', freethreaded: false}],
+    ['3.13.1t', {version: '3.13.1', freethreaded: true}],
+    ['3.14-dev', {version: '~3.14.0-0', freethreaded: false}],
+    ['3.14t-dev', {version: '~3.14.0-0', freethreaded: true}]
+  ])('%s -> %s', (input, expected) => {
+    expect(desugarVersion(input)).toEqual(expected);
+  });
+});
+
+// Test the combined desugarVersion and pythonVersionToSemantic functions
+describe('pythonVersions', () => {
+  it.each([
+    ['3.13', {version: '3.13', freethreaded: false}],
+    ['3.13t', {version: '3.13', freethreaded: true}],
+    ['3.13.1', {version: '3.13.1', freethreaded: false}],
+    ['3.13.1t', {version: '3.13.1', freethreaded: true}],
+    ['3.14-dev', {version: '~3.14.0-0', freethreaded: false}],
+    ['3.14t-dev', {version: '~3.14.0-0', freethreaded: true}]
+  ])('%s -> %s', (input, expected) => {
+    const {version, freethreaded} = desugarVersion(input);
+    const semanticVersionSpec = pythonVersionToSemantic(version, false);
+    expect({version: semanticVersionSpec, freethreaded}).toEqual(expected);
+  });
+
+  it.each([
+    ['3.13', {version: '~3.13.0-0', freethreaded: false}],
+    ['3.13t', {version: '~3.13.0-0', freethreaded: true}],
+    ['3.13.1', {version: '3.13.1', freethreaded: false}],
+    ['3.13.1t', {version: '3.13.1', freethreaded: true}],
+    ['3.14-dev', {version: '~3.14.0-0', freethreaded: false}],
+    ['3.14t-dev', {version: '~3.14.0-0', freethreaded: true}]
+  ])('%s (allowPreReleases=true) -> %s', (input, expected) => {
+    const {version, freethreaded} = desugarVersion(input);
+    const semanticVersionSpec = pythonVersionToSemantic(version, true);
+    expect({version: semanticVersionSpec, freethreaded}).toEqual(expected);
+  });
+});

__tests__/finder.test.ts

@@ -56,7 +56,7 @@ describe('Finder tests', () => {
     await io.mkdirP(pythonDir);
     fs.writeFileSync(`${pythonDir}.complete`, 'hello');
     // This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
-    await finder.useCpythonVersion('3.x', 'x64', true, false, false);
+    await finder.useCpythonVersion('3.x', 'x64', true, false, false, false);
     expect(spyCoreAddPath).toHaveBeenCalled();
     expect(spyCoreExportVariable).toHaveBeenCalledWith(
       'pythonLocation',
@@ -73,7 +73,7 @@ describe('Finder tests', () => {
     await io.mkdirP(pythonDir);
     fs.writeFileSync(`${pythonDir}.complete`, 'hello');
     // This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
-    await finder.useCpythonVersion('3.x', 'x64', false, false, false);
+    await finder.useCpythonVersion('3.x', 'x64', false, false, false, false);
     expect(spyCoreAddPath).not.toHaveBeenCalled();
     expect(spyCoreExportVariable).not.toHaveBeenCalled();
   });
@@ -96,7 +96,7 @@ describe('Finder tests', () => {
     });
     // This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
     await expect(
-      finder.useCpythonVersion('1.2.3', 'x64', true, false, false)
+      finder.useCpythonVersion('1.2.3', 'x64', true, false, false, false)
     ).resolves.toEqual({
       impl: 'CPython',
       version: '1.2.3'
@@ -135,7 +135,14 @@ describe('Finder tests', () => {
     });
     // This will throw if it doesn't find it in the manifest (because no such version exists)
     await expect(
-      finder.useCpythonVersion('1.2.4-beta.2', 'x64', false, false, false)
+      finder.useCpythonVersion(
+        '1.2.4-beta.2',
+        'x64',
+        false,
+        false,
+        false,
+        false
+      )
     ).resolves.toEqual({
       impl: 'CPython',
       version: '1.2.4-beta.2'
@@ -186,7 +193,7 @@ describe('Finder tests', () => {
 
     fs.writeFileSync(`${pythonDir}.complete`, 'hello');
     // This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
-    await finder.useCpythonVersion('1.2', 'x64', true, true, false);
+    await finder.useCpythonVersion('1.2', 'x64', true, true, false, false);
 
     expect(infoSpy).toHaveBeenCalledWith("Resolved as '1.2.3'");
     expect(infoSpy).toHaveBeenCalledWith(
@@ -197,7 +204,14 @@ describe('Finder tests', () => {
     );
     expect(installSpy).toHaveBeenCalled();
     expect(addPathSpy).toHaveBeenCalledWith(expPath);
-    await finder.useCpythonVersion('1.2.4-beta.2', 'x64', false, true, false);
+    await finder.useCpythonVersion(
+      '1.2.4-beta.2',
+      'x64',
+      false,
+      true,
+      false,
+      false
+    );
     expect(spyCoreAddPath).toHaveBeenCalled();
     expect(spyCoreExportVariable).toHaveBeenCalledWith(
       'pythonLocation',
@@ -224,7 +238,7 @@ describe('Finder tests', () => {
     });
     // This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
     await expect(
-      finder.useCpythonVersion('1.2', 'x64', false, false, false)
+      finder.useCpythonVersion('1.2', 'x64', false, false, false, false)
     ).resolves.toEqual({
       impl: 'CPython',
       version: '1.2.3'
@@ -251,17 +265,17 @@ describe('Finder tests', () => {
     });
     // This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
     await expect(
-      finder.useCpythonVersion('1.1', 'x64', false, false, false)
+      finder.useCpythonVersion('1.1', 'x64', false, false, false, false)
     ).rejects.toThrow();
     await expect(
-      finder.useCpythonVersion('1.1', 'x64', false, false, true)
+      finder.useCpythonVersion('1.1', 'x64', false, false, true, false)
     ).resolves.toEqual({
       impl: 'CPython',
       version: '1.1.0-beta.2'
     });
     // Check 1.1.0 version specifier does not fallback to '1.1.0-beta.2'
     await expect(
-      finder.useCpythonVersion('1.1.0', 'x64', false, false, true)
+      finder.useCpythonVersion('1.1.0', 'x64', false, false, true, false)
     ).rejects.toThrow();
   });
 
@@ -269,7 +283,14 @@ describe('Finder tests', () => {
     // This will throw if it doesn't find it in the cache and in the manifest (because no such version exists)
     let thrown = false;
     try {
-      await finder.useCpythonVersion('3.300000', 'x64', true, false, false);
+      await finder.useCpythonVersion(
+        '3.300000',
+        'x64',
+        true,
+        false,
+        false,
+        false
+      );
     } catch {
       thrown = true;
     }