From f2ecbd34e661de1bb58d742ac6f36c7e1c171455 Mon Sep 17 00:00:00 2001
From: darrenhuai <60621295+darrenhuai@users.noreply.github.com>
Date: Thu, 12 Nov 2026 15:01:11 -0800
Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20fix(discovery):=20let=20a=20?=
=?UTF-8?q?relative=20path=20beat=20try=5Ffirst=5Fwith?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
A spec like venv/bin/python can only be satisfied by that exact file, but
it was probed after the try_first_with entries. When a hint resolved to
the same file (a symlinked venv on POSIX, a different case on Windows) the
spec path was skipped as already tested, and when a hint shared its base
interpreter (the base itself or a sibling venv) the spec's own venv was
skipped once the hint failed the path check. Discovery then returned None.
Probe a spec path that has a directory part before the hints. Absolute
paths and bare names behave as before.
---
docs/changelog/+relative-try-first.bugfix.rst | 2 ++
docs/explanation.rst | 6 ++--
src/python_discovery/_discovery.py | 12 ++++----
tests/test_discovery.py | 30 +++++++++++++++++++
4 files changed, 42 insertions(+), 8 deletions(-)
create mode 100644 docs/changelog/+relative-try-first.bugfix.rst
diff --git a/docs/changelog/+relative-try-first.bugfix.rst b/docs/changelog/+relative-try-first.bugfix.rst
new file mode 100644
index 0000000..82967bd
--- /dev/null
+++ b/docs/changelog/+relative-try-first.bugfix.rst
@@ -0,0 +1,2 @@
+Discovery now finds an interpreter given as a relative path such as ``./venv/bin/python`` when ``try_first_with`` lists
+the same file, its base interpreter, or another virtual environment on that base, instead of finding nothing.
diff --git a/docs/explanation.rst b/docs/explanation.rst
index 6abd000..5a0b563 100644
--- a/docs/explanation.rst
+++ b/docs/explanation.rst
@@ -12,10 +12,10 @@ order. It stops as soon as it finds an interpreter that matches your spec.
flowchart TD
Start["get_interpreter()"] --> AbsPath{"Is spec an
absolute path?"}
AbsPath -->|Yes| TryAbs["Use path directly"]
- AbsPath -->|No| TryFirst["try_first_with paths"]
- TryFirst --> RelPath{"Does spec name a
relative directory?"}
+ AbsPath -->|No| RelPath{"Does spec name a
relative directory?"}
RelPath -->|Yes| TryRel["Resolve relative to cwd"]
- RelPath -->|No| Bare{"Bare executable name?"}
+ RelPath -->|No| TryFirst["try_first_with paths"]
+ TryFirst --> Bare{"Bare executable name?"}
Bare -->|Yes| PATH
Bare -->|No| Current["Current interpreter"]
Current --> Win{"Windows?"}
diff --git a/src/python_discovery/_discovery.py b/src/python_discovery/_discovery.py
index a2667ac..c03ad85 100644
--- a/src/python_discovery/_discovery.py
+++ b/src/python_discovery/_discovery.py
@@ -127,15 +127,17 @@ def _propose_explicit(
env: Mapping[str, str],
tested_exes: set[str],
) -> Generator[tuple[PythonInfo | None, bool], None, None]:
+ # Unparsed bare names reach spec.path; only an explicit directory should search the working directory. Probe that
+ # path before try_first_with: only it can satisfy the spec, and a hint on the same file or base interpreter would
+ # otherwise fail first and get it skipped as a duplicate.
+ if spec.path is not None and os.path.dirname(spec.path) and (exe_raw := _check_exe(spec.path, tested_exes)):
+ yield PythonInfo.from_exe(exe_raw, cache, env=env), True
+
for py_exe in try_first_with:
if Path(py_exe).exists() and (exe_raw := _check_exe(py_exe, tested_exes)):
yield PythonInfo.from_exe(exe_raw, cache, env=env), True
- if spec.path is not None:
- # Unparsed bare names reach spec.path; only an explicit directory should search the working directory.
- if os.path.dirname(spec.path) and (exe_raw := _check_exe(spec.path, tested_exes)):
- yield PythonInfo.from_exe(exe_raw, cache, env=env), True
- else:
+ if spec.path is None:
yield from _propose_current_and_windows(spec, cache, env, tested_exes)
diff --git a/tests/test_discovery.py b/tests/test_discovery.py
index b03ab33..bc5d229 100644
--- a/tests/test_discovery.py
+++ b/tests/test_discovery.py
@@ -307,6 +307,36 @@ def test_discovery_absolute_path_with_try_first(
assert Path(interpreter.executable) == good_exe
+@pytest.mark.parametrize(
+ "hint",
+ [
+ pytest.param("sibling", id="sibling-venv"),
+ pytest.param("base", id="base-interpreter"),
+ pytest.param("case", id="other-case", marks=pytest.mark.skipif(not IS_WIN, reason="case-insensitive paths")),
+ ],
+)
+def test_discovery_relative_path_with_try_first(
+ tmp_path: Path, session_cache: DiskCache, monkeypatch: pytest.MonkeyPatch, hint: str
+) -> None:
+ for name in ("good", "bad"):
+ check_call([sys.executable, "-m", "venv", "--without-pip", str(tmp_path / name)])
+ monkeypatch.chdir(tmp_path)
+ spec = str(Path("good", _SCRIPTS_DIR, _PYTHON_NAME))
+ good_exe = tmp_path / spec
+ first = {
+ "sibling": tmp_path / "bad" / _VENV_PYTHON,
+ "base": PythonInfo.current_system(session_cache).system_executable,
+ "case": str(good_exe).upper(),
+ }[hint]
+ env = {**os.environ, "PATH": "", "UV_PYTHON_INSTALL_DIR": str(tmp_path / "missing")}
+
+ found = get_interpreter(spec, try_first_with=[str(first)], cache=session_cache, env=env)
+ listed = iter_interpreters(spec, try_first_with=[str(first)], cache=session_cache, env=env)
+
+ assert found is not None
+ assert (Path(found.executable), [Path(info.executable) for info in listed]) == (good_exe, [good_exe])
+
+
def test_discovery_venvs_on_one_base_keep_their_executable(tmp_path: Path, session_cache: DiskCache) -> None:
scripts_dir = _SCRIPTS_DIR
exe_name = _PYTHON_NAME
From 3db5b65c5d6084a64fa25a8709d21aa098681425 Mon Sep 17 00:00:00 2001
From: darrenhuai <60621295+darrenhuai@users.noreply.github.com>
Date: Thu, 12 Nov 2026 16:23:21 -0800
Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=9D=20docs(changelog):=20name=20th?=
=?UTF-8?q?e=20same-file=20hints=20that=20failed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
A hint with the exact spec path already worked. What failed was the same
file reached another way: venv/bin/python3 next to venv/bin/python on
POSIX, or a different case on Windows.
---
docs/changelog/+relative-try-first.bugfix.rst | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docs/changelog/+relative-try-first.bugfix.rst b/docs/changelog/+relative-try-first.bugfix.rst
index 82967bd..1293942 100644
--- a/docs/changelog/+relative-try-first.bugfix.rst
+++ b/docs/changelog/+relative-try-first.bugfix.rst
@@ -1,2 +1,3 @@
Discovery now finds an interpreter given as a relative path such as ``./venv/bin/python`` when ``try_first_with`` lists
-the same file, its base interpreter, or another virtual environment on that base, instead of finding nothing.
+the same file under another name or case, its base interpreter, or another virtual environment on that base, instead of
+finding nothing.