Add support for free-threading Python builds

This change adds support for Python's free-threading builds (e.g., Python 3.14t)
by detecting the Py_GIL_DISABLED configuration variable and appending a "t" suffix
to version keys when running on a free-threading build.

Changes include:
- Updated plugin to check sysconfig.get_config_var("Py_GIL_DISABLED")
- Added "t" suffix to version keys for free-threading builds
- Updated documentation with example configuration
- Added test case for free-threading Python version detection

Author: ymyzk

README.md

@@ -174,6 +174,22 @@ python =
 ...
 ```
 
+_Added in 3.5.0_: To use a free-threaded Python build, add the `t` suffix.
+
+ `tox.ini`:
+```ini
+[tox]
+envlist = py314, py314t
+
+[gh-actions]
+python =
+    3.14: py314
+    3.14t: py314t
+
+[testenv]
+...
+```
+
 PyPy is also supported in the `python` configuration key.
 Support of Pyston is experimental and not tested by our CI.
 

src/tox_gh_actions/plugin.py

@@ -2,6 +2,7 @@
 from logging import getLogger
 import os
 import sys
+import sysconfig
 from typing import Any, Dict, Iterable, List
 
 from tox.config.cli.parser import Parsed
@@ -163,25 +164,27 @@ def get_python_version_keys() -> List[str]:
 
     Examples:
     - CPython 3.8.z => [3.8, 3]
+    - CPython 3.14.z free-threading build => [3.14t, 3t]
     - PyPy 3.6 (v7.3.z) => [pypy-3.6, pypy-3, pypy3]
     - Pyston based on Python CPython 3.8.8 (v2.2) => [pyston-3.8, pyston-3]
 
     """
     major_version = str(sys.version_info[0])
     major_minor_version = ".".join([str(i) for i in sys.version_info[:2]])
+    suffix = "t" if sysconfig.get_config_var("Py_GIL_DISABLED") == 1 else ""
     if "PyPy" in sys.version:
         return [
-            "pypy-" + major_minor_version,
-            "pypy-" + major_version,
+            "pypy-" + major_minor_version + suffix,
+            "pypy-" + major_version + suffix,
         ]
     elif hasattr(sys, "pyston_version_info"):  # Pyston
         return [
-            "pyston-" + major_minor_version,
-            "pyston-" + major_version,
+            "pyston-" + major_minor_version + suffix,
+            "pyston-" + major_version + suffix,
         ]
     else:
         # Assume this is running on CPython
-        return [major_minor_version, major_version]
+        return [major_minor_version + suffix, major_version + suffix]
 
 
 def is_running_on_actions() -> bool:

tests/test_plugin.py

@@ -247,29 +247,40 @@ def test_get_envlist_from_factors(
 
 
 @pytest.mark.parametrize(
-    "version,info,expected",
+    "version,info,gil,expected",
     [
+        (
+            "3.14.0 free-threading build (main, Oct  7 2025, 09:34:52)"
+            " [Clang 17.0.0 (clang-1700.3.19.1)]",
+            (3, 14, 0, "final", 0),
+            1,
+            ["3.14t", "3t"],
+        ),
         (
             "3.8.1 (default, Jan 22 2020, 06:38:00) \n[GCC 9.2.0]",
             (3, 8, 1, "final", 0),
+            0,
             ["3.8", "3"],
         ),
         (
             "3.6.9 (1608da62bfc7, Dec 23 2019, 10:50:04)\n"
             "[PyPy 7.3.0 with GCC 7.3.1 20180303 (Red Hat 7.3.1-5)]",
             (3, 6, 9, "final", 0),
+            0,
             ["pypy-3.6", "pypy-3"],
         ),
     ],
 )
 def test_get_version_keys(
     mocker: MockerFixture,
     version: str,
+    gil: int,
     info: Tuple[int, int, int, str, int],
     expected: List[str],
 ) -> None:
     mocker.patch("tox_gh_actions.plugin.sys.version", version)
     mocker.patch("tox_gh_actions.plugin.sys.version_info", info)
+    mocker.patch("tox_gh_actions.plugin.sysconfig.get_config_var", return_value=gil)
     assert plugin.get_python_version_keys() == expected