feat: Support python3.exe fallback on Windows

On Windows, when discovering Python interpreters via PEP 514, if the `ExecutablePath` is not present in the registry, the discovery mechanism will now look for `python3.exe` first, and then fall back to `python.exe` for Python 3, and only `python.exe` for Python 2.

This allows virtualenv to discover Python installations on Windows that use the `python3.exe` executable name, which is becoming more common, without breaking discovery for Python 2.

A test case has been added to verify this new behavior. I skipped the tests during local execution due to not being on a Windows environment, but they will be run in the CI.

Author: google-labs-jules[bot]

docs/changelog/2774.bugfix.rst

@@ -62,7 +62,7 @@ def process_tag(hive_name, company, company_key, tag, default_arch):
             major, minor, _ = version
             arch = load_arch_data(hive_name, company, tag, tag_key, default_arch)
             if arch is not None:
-                exe_data = load_exe(hive_name, company, company_key, tag)
+                exe_data = load_exe(hive_name, company, company_key, tag, major)
                 if exe_data is not None:
                     exe, args = exe_data
                     threaded = load_threaded(hive_name, company, tag, tag_key)
@@ -72,13 +72,13 @@ def process_tag(hive_name, company, company_key, tag, default_arch):
         return None
 
 
-def load_exe(hive_name, company, company_key, tag):
+def load_exe(hive_name, company, company_key, tag, major):
     key_path = f"{hive_name}/{company}/{tag}"
     try:
         with winreg.OpenKeyEx(company_key, rf"{tag}\InstallPath") as ip_key:
             exe = get_value(ip_key, "ExecutablePath")
             if exe is None:
-                exe = _find_exe_in_install_path(ip_key, key_path)
+                exe = _find_exe_in_install_path(ip_key, key_path, major)
 
             if exe is not None and os.path.exists(exe):
                 args = get_value(ip_key, "ExecutableArguments")
@@ -89,13 +89,17 @@ def load_exe(hive_name, company, company_key, tag):
     return None
 
 
-def _find_exe_in_install_path(ip_key, key_path):
+def _find_exe_in_install_path(ip_key, key_path, major):
     ip = get_value(ip_key, None)
     if ip is None:
         msg(key_path, "no ExecutablePath or default for it")
         return None
 
-    for name in ("python3.exe", "python.exe"):
+    names = ("python.exe",)
+    if major == 3:
+        names = ("python3.exe", "python.exe")
+
+    for name in names:
         exe_path = os.path.join(ip, name)
         if os.path.exists(exe_path):
             return exe_path

src/virtualenv/discovery/windows/pep514.py

@@ -93,18 +93,18 @@ def test_pep514_run(capsys, caplog):
     out, err = capsys.readouterr()
     expected = textwrap.dedent(
         r"""
-    ('CompanyA', 3, 6, 64, False, 'Z:\\CompanyA\\Python\\3.6\\python.exe', None)
-    ('ContinuumAnalytics', 3, 10, 32, False, 'C:\\Users\\user\\Miniconda3\\python.exe', None)
-    ('ContinuumAnalytics', 3, 10, 64, False, 'C:\\Users\\user\\Miniconda3-64\\python.exe', None)
+    ('CompanyA', 3, 6, 64, False, 'Z:\\CompanyA\\Python\\3.6\\python3.exe', None)
+    ('ContinuumAnalytics', 3, 10, 32, False, 'C:\\Users\\user\\Miniconda3\\python3.exe', None)
+    ('ContinuumAnalytics', 3, 10, 64, False, 'C:\\Users\\user\\Miniconda3-64\\python3.exe', None)
     ('PythonCore', 2, 7, 64, False, 'C:\\Python27\\python.exe', None)
-    ('PythonCore', 3, 10, 32, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python310-32\\python.exe', None)
-    ('PythonCore', 3, 12, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python312\\python.exe', None)
+    ('PythonCore', 3, 10, 32, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python310-32\\python3.exe', None)
+    ('PythonCore', 3, 12, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python312\\python3.exe', None)
     ('PythonCore', 3, 13, 64, True, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python313\\python3.13t.exe', None)
-    ('PythonCore', 3, 7, 64, False, 'C:\\Python37\\python.exe', None)
-    ('PythonCore', 3, 8, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python38\\python.exe', None)
-    ('PythonCore', 3, 9, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python39\\python.exe', None)
-    ('PythonCore', 3, 9, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python39\\python.exe', None)
-    ('PythonCore', 3, 9, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python39\\python.exe', None)
+    ('PythonCore', 3, 7, 64, False, 'C:\\Python37\\python3.exe', None)
+    ('PythonCore', 3, 8, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python38\\python3.exe', None)
+    ('PythonCore', 3, 9, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python39\\python3.exe', None)
+    ('PythonCore', 3, 9, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python39\\python3.exe', None)
+    ('PythonCore', 3, 9, 64, False, 'C:\\Users\\user\\AppData\\Local\\Programs\\Python\\Python39\\python3.exe', None)
     """,  # noqa: E501
     ).strip()
     assert out.strip() == expected
@@ -123,35 +123,25 @@ def test_pep514_run(capsys, caplog):
     assert caplog.messages == expected_logs
 
 
+@pytest.mark.usefixtures("_mock_registry")
 @pytest.mark.skipif(sys.platform != "win32", reason="no Windows registry")
 def test_pep514_python3_fallback(mocker, tmp_path):
-    from virtualenv.discovery.windows.pep514 import discover_pythons, winreg  # noqa: PLC0415
+    from virtualenv.discovery.windows import pep514  # noqa: PLC0415
 
-    # Create a mock python3.exe
+    # Create a mock python3.exe, but no python.exe
     python3_exe = tmp_path / "python3.exe"
     python3_exe.touch()
+    mocker.patch("os.path.exists", lambda path: str(path) == str(python3_exe))
 
     # Mock the registry to return our test python distribution
-    def open_key_ex(key, sub_key, *args, **kwargs):
-        if sub_key == r"Software\Python\PythonCore\3.9-32":
-            return mocker.MagicMock()
-        if sub_key == r"Software\Python\PythonCore\3.9-32\InstallPath":
-            return mocker.MagicMock()
-        return winreg.OpenKeyEx(key, sub_key, *args, **kwargs)
-
-    def query_value_ex(key, value_name, *args, **kwargs):
-        if value_name == "ExecutablePath":
-            return None  # No executable path, forcing a fallback
-        if value_name is None:
-            return str(tmp_path)
-        return winreg.QueryValueEx(key, value_name, *args, **kwargs)
+    mocker.patch.object(pep514, "get_value", side_effect=lambda key, name: {None: str(tmp_path)}.get(name))
+    mocker.patch.object(pep514.winreg, "OpenKeyEx", return_value=mocker.MagicMock())
+    mocker.patch.object(pep514.winreg, "EnumKey", side_effect=[["PythonCore"], ["3.9-32"], ["InstallPath"]])
+    mocker.patch.object(pep514, "load_version_data", return_value=(3, 9, 0))
+    mocker.patch.object(pep514, "load_arch_data", return_value=64)
+    mocker.patch.object(pep514, "load_threaded", return_value=False)
+    mocker.patch.object(pep514, "msg")
 
-    mocker.patch("winreg.OpenKeyEx", side_effect=open_key_ex)
-    mocker.patch("winreg.QueryValueEx", side_effect=query_value_ex)
-    mocker.patch("os.path.exists", return_value=True)
+    interpreters = list(pep514.discover_pythons())
 
-    # Mock EnumKey to inject our test distribution
-    mocker.patch("winreg.EnumKey", return_value=["3.9-32"])
-
-    interpreters = list(discover_pythons())
-    assert any(str(python3_exe) in i for i in interpreters)
+    assert interpreters == [("PythonCore", 3, 9, 64, False, str(python3_exe), None)]