🐛 fix(discovery): resolve base interpreter executable-only symlinks (#3166)

Creating an environment with `-p` pointing at a symlink to just the
interpreter binary recorded the symlink in `pyvenv.cfg`: `home` ended up
as the symlink's directory, which contains no `lib/`, and
`base-executable` kept the unresolved link. 🐛 Standard CPython survives
because `getpath` re-resolves the link when reading `home`, but layouts
where `home` must directly locate the base stdlib, such as
python-build-standalone, produce a broken environment (#3157).

The resolution lives in python-discovery (tox-dev/python-discovery#85,
refined by tox-dev/python-discovery#87): `system_executable` follows the
symlink chain of the executable's final path component only, stopping as
soon as the stdlib landmark is reachable and never touching macOS
framework builds, the same semantics CPython's `getpath` uses and its
`venv` adopts in python/cpython#115237. A barren-directory symlink
resolves to the real interpreter while stable aliases like Homebrew's
`opt` paths, Debian's `/usr/bin/python3`, or a fully symlinked
interpreter tree keep their recorded form. This PR raises the dependency
floor to `python-discovery>=1.4.2` and bumps the app-data `py_info`
cache key from `4` to `5` so interpreter records probed by older
virtualenv versions are not shared with the corrected ones.

CI needs python-discovery `1.4.2` on PyPI (tox-dev/python-discovery#87
merge + release) to go green.

Fixes #3157.

Author: gaborbernat

docs/changelog/3157.bugfix.rst

@@ -0,0 +1,4 @@
+Resolve executable-only symlinks when recording ``home`` and ``base-executable`` in ``pyvenv.cfg``, mirroring CPython's
+``getpath.realpath`` (python/cpython#115237), so environments created from a symlink to the interpreter binary locate
+the base stdlib (for example python-build-standalone); a fully symlinked interpreter tree is kept as-is - by
+:user:`gaborbernat`.

pyproject.toml

@@ -50,7 +50,7 @@ dependencies = [
   "filelock>=3.24.2,<4; python_version>='3.10'",
   "importlib-metadata>=6.6; python_version<'3.8'",
   "platformdirs>=3.9.1,<5",
-  "python-discovery>=1.4",
+  "python-discovery>=1.4.2",
   "typing-extensions>=4.13.2; python_version<'3.11'",
 ]
 urls.Documentation = "https://virtualenv.pypa.io"

src/virtualenv/app_data/via_disk_folder.py

@@ -86,7 +86,7 @@ def extract(self, path: Path, to_folder: Path | None) -> Generator[Path]:
 
     @property
     def py_info_at(self) -> ReentrantFileLock:
-        return self.lock / "py_info" / "4"  # ty: ignore[invalid-return-type]
+        return self.lock / "py_info" / "5"  # ty: ignore[invalid-return-type]
 
     def py_info(self, path: Path) -> PyInfoStoreDisk:
         return PyInfoStoreDisk(self.py_info_at, path)

tests/unit/create/test_creator.py

@@ -385,6 +385,28 @@ def test_home_path_is_exe_parent(tmp_path, creator) -> None:
     assert any(os.path.exists(os.path.join(cfg["home"], exe)) for exe in exes)
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX only")
+@pytest.mark.skipif(
+    bool(CURRENT.sysconfig_vars.get("PYTHONFRAMEWORK")),
+    reason="framework builds self-locate via dyld and keep the recorded path",
+)
+@pytest.mark.usefixtures("temp_app_data")
+def test_home_resolves_executable_only_symlink(tmp_path: Path) -> None:
+    """An executable-only symlink must not be recorded as home / base-executable (issue #3157)."""
+    system_exe = CURRENT.system_executable
+    assert system_exe is not None
+    link = tmp_path / "symdir" / "python3"
+    link.parent.mkdir()
+    link.symlink_to(system_exe)
+
+    result = cli_run(["-p", str(link), str(tmp_path / "env"), "--seeder", "app-data", "--without-pip"])
+    cfg = PyEnvCfg.from_file(result.creator.pyenv_cfg.path)
+
+    assert Path(cfg["home"]) != link.parent
+    assert os.path.samefile(cfg["base-executable"], system_exe)
+    assert Path(cfg["home"]) == Path(cfg["base-executable"]).parent
+
+
 @pytest.mark.usefixtures("temp_app_data")
 def test_create_parallel(tmp_path) -> None:
     def create(count) -> None: