Feat: free-threaded python support

Author: robsdedude

docs/changelog/3391.feature.rst

@@ -0,0 +1,3 @@
+Add support for free-threaded python builds.
+Factors like ``py313t`` will only pick builds with the GIL disabled while factors without trailing ``t`` will only pick
+builds without no-GIL support.

docs/config.rst

@@ -866,6 +866,29 @@ Python options
 
    The Python executable from within the tox environment.
 
+.. conf::
+   :keys: py_dot_ver
+   :constant:
+   :version_added: 4.0.10
+
+   Major.Minor version of the Python interpreter in the tox environment (e.g., ``3.13``).
+
+.. conf::
+   :keys: py_impl
+   :constant:
+   :version_added: 4.0.10
+
+   Name of the Python implementation in the tox environment in lowercase (e.g., ``cpython``, ``pypy``).
+
+.. conf::
+   :keys: py_free_threaded
+   :constant:
+   :version_added: 4.26
+
+   ``True`` if the Python interpreter in the tox environment is an experimental free-threaded CPython build,
+   else ``False``.
+
+
 Python run
 ~~~~~~~~~~
 .. conf::

pyproject.toml

@@ -60,7 +60,7 @@ dependencies = [
   "pyproject-api>=1.8",
   "tomli>=2.2.1; python_version<'3.11'",
   "typing-extensions>=4.12.2; python_version<'3.11'",
-  "virtualenv>=20.29.1",
+  "virtualenv>=20.31",
 ]
 optional-dependencies.test = [
   "devpi-process>=1.0.2",

src/tox/pytest.py

@@ -281,7 +281,8 @@ def our_setup_state(value: Sequence[str]) -> State:
                 m.setenv("VIRTUALENV_SYMLINK_APP_DATA", "1")
                 m.setenv("VIRTUALENV_SYMLINKS", "1")
                 m.setenv("VIRTUALENV_PIP", "embed")
-                m.setenv("VIRTUALENV_WHEEL", "embed")
+                if sys.version_info[:2] < (3, 9):
+                    m.setenv("VIRTUALENV_WHEEL", "embed")
                 m.setenv("VIRTUALENV_SETUPTOOLS", "embed")
                 try:
                     tox_run(args)

src/tox/session/env_select.py

@@ -136,7 +136,7 @@ class _ToxEnvInfo:
     package_skip: tuple[str, Skip] | None = None  #: if set the creation of the packaging environment failed
 
 
-_DYNAMIC_ENV_FACTORS = re.compile(r"(pypy|py|cython|)((\d(\.\d+(\.\d+)?)?)|\d+)?")
+_DYNAMIC_ENV_FACTORS = re.compile(r"(pypy|py|cython|)(((\d(\.\d+(\.\d+)?)?)|\d+)t?)?")
 _PY_PRE_RELEASE_FACTOR = re.compile(r"alpha|beta|rc\.\d+")
 
 

src/tox/tox_env/python/api.py

@@ -5,6 +5,7 @@
 import logging
 import re
 import sys
+import sysconfig
 from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, List, NamedTuple, cast
@@ -30,6 +31,7 @@ class PythonInfo(NamedTuple):
     implementation: str
     version_info: VersionInfo
     version: str
+    free_threaded: bool
     is_64: bool
     platform: str
     extra: dict[str, Any]
@@ -51,11 +53,14 @@ def version_dot(self) -> str:
     r"""
     ^(?!py$)                                               # don't match 'py' as it doesn't provide any info
     (?P<impl>py|pypy|cpython|jython|graalpy|rustpython|ironpython) # the interpreter; most users will simply use 'py'
-    (?P<version>[2-9]\.?[0-9]?[0-9]?)?$                    # the version; one of: MAJORMINOR, MAJOR.MINOR
+    (?:
+    (?P<version>[2-9]\.?[0-9]?[0-9]?)                      # the version; one of: MAJORMINOR, MAJOR.MINOR
+    (?P<threaded>t?)                                       # version followed by t for free-threading
+    )?$
     """,
     re.VERBOSE,
 )
-PY_FACTORS_RE_EXPLICIT_VERSION = re.compile(r"^((?P<impl>cpython|pypy)-)?(?P<version>[2-9]\.[0-9]+)$")
+PY_FACTORS_RE_EXPLICIT_VERSION = re.compile(r"^((?P<impl>cpython|pypy)-)?(?P<version>[2-9]\.[0-9]+)(?P<threaded>t?)$")
 
 
 class Python(ToxEnv, ABC):
@@ -100,6 +105,7 @@ def validate_base_python(value: list[str]) -> list[str]:
         )
         self.conf.add_constant("py_dot_ver", "<python major>.<python minor>", value=self.py_dot_ver)
         self.conf.add_constant("py_impl", "python implementation", value=self.py_impl)
+        self.conf.add_constant("py_free_threaded", "is no-gil interpreted", value=self.py_free_threaded)
 
     def _default_set_env(self) -> dict[str, str]:
         env = super()._default_set_env()
@@ -111,6 +117,9 @@ def _default_set_env(self) -> dict[str, str]:
     def py_dot_ver(self) -> str:
         return self.base_python.version_dot
 
+    def py_free_threaded(self) -> bool:
+        return self.base_python.free_threaded
+
     def py_impl(self) -> str:
         return self.base_python.impl_lower
 
@@ -145,7 +154,7 @@ def extract_base_python(cls, env_name: str) -> str | None:
         match = PY_FACTORS_RE_EXPLICIT_VERSION.match(env_name)
         if match:
             found = match.groupdict()
-            candidates.append(f"{'pypy' if found['impl'] == 'pypy' else ''}{found['version']}")
+            candidates.append(f"{'pypy' if found['impl'] == 'pypy' else ''}{found['version']}{found['threaded']}")
         else:
             for factor in env_name.split("-"):
                 match = PY_FACTORS_RE.match(factor)
@@ -163,7 +172,8 @@ def _python_spec_for_sys_executable(cls) -> PythonSpec:
         implementation = sys.implementation.name
         version = sys.version_info
         bits = "64" if sys.maxsize > 2**32 else "32"
-        string_spec = f"{implementation}{version.major}{version.minor}-{bits}"
+        threaded = "t" if sysconfig.get_config_var("Py_GIL_DISABLED") == 1 else ""
+        string_spec = f"{implementation}{version.major}{version.minor}{threaded}-{bits}"
         return PythonSpec.from_string_spec(string_spec)
 
     @classmethod
@@ -186,7 +196,7 @@ def _validate_base_python(
                         spec_base = cls.python_spec_for_path(path)
                 if any(
                     getattr(spec_base, key) != getattr(spec_name, key)
-                    for key in ("implementation", "major", "minor", "micro", "architecture")
+                    for key in ("implementation", "major", "minor", "micro", "architecture", "free_threaded")
                     if getattr(spec_name, key) is not None
                 ):
                     msg = f"env name {env_name} conflicting with base python {base_python}"

src/tox/tox_env/python/virtual_env/api.py

@@ -143,6 +143,7 @@ def _get_python(self, base_python: list[str]) -> PythonInfo | None:  # noqa: ARG
             implementation=interpreter.implementation,
             version_info=interpreter.version_info,
             version=interpreter.version,
+            free_threaded=interpreter.free_threaded,
             is_64=(interpreter.architecture == 64),  # noqa: PLR2004
             platform=interpreter.platform,
             extra={"executable": Path(interpreter.system_executable).resolve()},

tests/conftest.py

@@ -97,6 +97,7 @@ def get_python(self: VirtualEnv, base_python: list[str]) -> PythonInfo | None:
                 implementation=impl,
                 version_info=ver_info,
                 version="",
+                free_threaded=False,
                 is_64=True,
                 platform=sys.platform,
                 extra={"executable": Path(sys.executable)},

tests/session/cmd/test_sequential.py

@@ -114,7 +114,9 @@ def test_result_json_sequential(
     py_test = get_cmd_exit_run_id(log_report, "py", "test")
     assert py_test == [(1, "commands[0]"), (0, "commands[1]")]
     packaging_installed = log_report["testenvs"]["py"].pop("installed_packages")
-    expected_pkg = {"pip", "setuptools", "wheel", "a"}
+    expected_pkg = {"pip", "setuptools", "a"}
+    if sys.version_info[0:2] == (3, 8):
+        expected_pkg.add("wheel")
     assert {i[: i.find("==")] if "@" not in i else "a" for i in packaging_installed} == expected_pkg
     install_package = log_report["testenvs"]["py"].pop("installpkg")
     assert re.match(r"^[a-fA-F0-9]{64}$", install_package.pop("sha256"))

tests/session/test_env_select.py

@@ -261,10 +261,15 @@ def test_matches_combined_env(env_name: str, tox_project: ToxProjectCreator) ->
         "pypy312",
         "py3",
         "py3.12",
+        "py3.12t",
         "py312",
+        "py312t",
         "3",
+        "3t",
         "3.12",
+        "3.12t",
         "3.12.0",
+        "3.12.0t",
     ],
 )
 def test_dynamic_env_factors_match(env: str) -> None: