python-discovery 1.5.3__tar.gz → 1.6.1__tar.gz

{python_discovery-1.5.3 → python_discovery-1.6.1}/.pre-commit-config.yaml

@@ -15,11 +15,11 @@ repos:
       - id: codespell
         additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.28.0"
+    rev: "v2.29.4"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.16.3"
+    rev: "v0.16.7"
     hooks:
       - id: ruff-format
       - id: ruff
@@ -39,7 +39,7 @@ repos:
           - mdformat-gfm>=1
           - mdformat-ruff>=0.1.3
   - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: v1.29.0
+    rev: v1.30.1
     hooks:
       - id: zizmor
   - repo: meta

{python_discovery-1.5.3 → python_discovery-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-discovery
-Version: 1.5.3
+Version: 1.6.1
 Summary: Python interpreter discovery
 Project-URL: Changelog, https://github.com/tox-dev/python-discovery/releases
 Project-URL: Documentation, https://python-discovery.readthedocs.io

{python_discovery-1.5.3 → python_discovery-1.6.1}/docs/changelog.rst

@@ -6,6 +6,33 @@
 
 .. towncrier release notes start
 
+********************
+ v1.6.1 (2026-09-18)
+********************
+
+Bug fixes - 1.6.1
+=================
+- Skip empty ``PATH`` entries during interpreter discovery - by :user:`gaborbernat`. (:issue:`129`)
+
+Improved documentation - 1.6.1
+==============================
+- Document :attr:`~python_discovery.PythonInfo.system_exe` across the tutorial, the how-to guide and the explanation of
+  how resolution reaches a base interpreter. The class diagram in the how-to guide had
+  :attr:`~python_discovery.PythonInfo.system_executable` typed ``str`` rather than ``str | None`` - by
+  :user:`gaborbernat`. (:issue:`128`)
+
+********************
+ v1.6.0 (2026-08-28)
+********************
+
+Features - 1.6.0
+================
+- :attr:`~python_discovery.PythonInfo.system_exe` returns the executable of the system Python an interpreter is based on,
+  falling back to :attr:`~python_discovery.PythonInfo.executable` the way
+  :meth:`~python_discovery.PythonInfo.resolve_to_system` does. :attr:`~python_discovery.PythonInfo.system_executable` is
+  ``None`` until resolution runs, so every consumer had to narrow a value discovery has already settled - by
+  :user:`gaborbernat`. (:issue:`127`)
+
 ********************
  v1.5.3 (2026-08-24)
 ********************

{python_discovery-1.5.3 → python_discovery-1.6.1}/docs/explanation.rst

@@ -186,7 +186,7 @@ APIs whenever a spec is given.
 
 **Deduplication.** :func:`~python_discovery.get_interpreter` deduplicates per call so it does not interrogate the
 same binary twice while searching, and stops as soon as a match is found. :func:`~python_discovery.iter_interpreters`
-deduplicates by the resolved real path of each candidate's ``system_executable`` (falling back to ``executable``).
+deduplicates by the resolved real path of each candidate's :attr:`~python_discovery.PythonInfo.system_exe`.
 That means symlinked aliases like ``/bin/python3`` and ``/usr/bin/python3``, or a virtualenv whose ``python``
 symlinks to its base interpreter, collapse to a single yield. The semantic is "one entry per distinct install,"
 which is what callers building choosers or version-range pickers usually want.
@@ -198,6 +198,40 @@ version first, smallest install root, etc.), wrap the call in :func:`sorted` --
 include a ``sort_by`` parameter because keeping discovery order preserves the priority signal for callers who
 want it.
 
+Resolving a virtual environment to its base
+--------------------------------------------
+
+A :class:`~python_discovery.PythonInfo` reaches you in one of two states, and the difference shows up in a single
+field.
+
+Collection fills in :attr:`~python_discovery.PythonInfo.system_executable` by inspection alone, which works whenever
+the interpreter is not in a virtual environment or names its base outright. When inspection comes up short the field
+holds ``None``, and :meth:`~python_discovery.PythonInfo.resolve_to_system` walks the prefix chain a layer at a time,
+interrogating each prefix until it reaches a real install. Every discovery entry point runs that walk, so an
+interpreter you got from :func:`~python_discovery.get_interpreter`,
+:func:`~python_discovery.iter_interpreters` or :meth:`~python_discovery.PythonInfo.from_exe` is resolved before you
+see it.
+
+.. mermaid::
+
+    flowchart TD
+        Collect["collection<br>system_executable = None"] --> Walk["resolve_to_system()<br>walk prefix chain"]
+        Walk --> Done["system_executable set"]
+        Collect -- "base named outright" --> Done
+        Done --> Read["system_exe"]
+
+        style Collect fill:#ffe3a3,stroke:#d29200,color:#3a2c00
+        style Walk fill:#4a90d9,stroke:#2a5f8f,color:#fff
+        style Done fill:#4a9f4a,stroke:#2a6f2a,color:#fff
+        style Read fill:#4a9f4a,stroke:#2a6f2a,color:#fff
+
+The annotation cannot describe that ordering, so ``system_executable`` stays ``str | None`` and a type checker asks
+every reader to narrow a value resolution has settled.
+:attr:`~python_discovery.PythonInfo.system_exe` closes that gap by falling back to
+:attr:`~python_discovery.PythonInfo.executable`, which is the value ``resolve_to_system`` writes anyway when a prefix
+links back to its own interpreter. Reading the raw field still tells the two states apart, which is what
+:meth:`~python_discovery.PythonInfo.from_exe` with ``resolve_to_host=False`` leaves you holding.
+
 How caching works
 -------------------
 

{python_discovery-1.5.3 → python_discovery-1.6.1}/docs/how-to/standalone-usage.rst

@@ -145,7 +145,8 @@ Once you have a :class:`~python_discovery.PythonInfo`, you can inspect everythin
     classDiagram
         class PythonInfo {
             +executable: str
-            +system_executable: str
+            +system_exe: str
+            +system_executable: str | None
             +implementation: str
             +version_info: VersionInfo
             +architecture: int
@@ -167,7 +168,7 @@ Once you have a :class:`~python_discovery.PythonInfo`, you can inspect everythin
    info = get_interpreter("python3.12", cache=cache)
 
    info.executable           # Resolved path to the binary.
-   info.system_executable    # The underlying system interpreter (outside any venv).
+   info.system_exe           # The underlying system interpreter (outside any venv).
    info.implementation       # "CPython", "PyPy", "GraalPy", etc.
    info.version_info         # VersionInfo(major, minor, micro, releaselevel, serial).
    info.architecture         # 64 or 32.
@@ -178,6 +179,13 @@ Once you have a :class:`~python_discovery.PythonInfo`, you can inspect everythin
    info.sysconfig_vars       # All sysconfig.get_config_vars() values.
    info.sysconfig_paths      # All sysconfig.get_paths() values.
 
+Prefer :attr:`~python_discovery.PythonInfo.system_exe` over the raw
+:attr:`~python_discovery.PythonInfo.system_executable` field it reads. The field is typed ``str | None`` because it
+holds nothing until resolution runs, so a type checker makes you narrow it at every use even though discovery has
+filled it in by the time you hold a :class:`~python_discovery.PythonInfo`. Read the raw field only when you build a
+:class:`~python_discovery.PythonInfo` yourself, or call
+:meth:`~python_discovery.PythonInfo.from_exe` with ``resolve_to_host=False``, and want to tell the two states apart.
+
 Implement a custom cache backend
 -----------------------------------
 

{python_discovery-1.5.3 → python_discovery-1.6.1}/docs/tutorial/getting-started.rst

@@ -17,6 +17,7 @@ Before diving into code, here are the key ideas:
 - **Spec** -- a short string describing what you are looking for (e.g., ``python3.12``, ``pypy3.9``, ``>=3.11``).
 - **Discovery** -- the process of searching your system for an interpreter that matches a spec.
 - **Cache** -- a disk store that remembers previously discovered interpreters so the next lookup is instant.
+- **Resolution** -- following a virtual environment back to the base interpreter it was built from.
 
 Inspecting the current interpreter
 ------------------------------------
@@ -45,6 +46,7 @@ The simplest use case: get information about the Python that is running right no
    info = PythonInfo.current_system(cache)
 
    print(info.executable)        # /usr/bin/python3.12
+   print(info.system_exe)        # /usr/bin/python3.12
    print(info.version_info[:3])  # (3, 12, 1)
    print(info.implementation)    # CPython  (or PyPy, GraalPy, etc.)
    print(info.architecture)      # 64       (or 32)
@@ -52,6 +54,11 @@ The simplest use case: get information about the Python that is running right no
 The returned :class:`~python_discovery.PythonInfo` object contains everything the library knows about that interpreter:
 paths, version numbers, sysconfig variables, platform details, and more.
 
+Run the same snippet from inside a virtual environment and the two paths part company.
+:attr:`~python_discovery.PythonInfo.executable` stays the environment's own ``python``, while
+:attr:`~python_discovery.PythonInfo.system_exe` names the base interpreter that environment was built from. Reach for
+``system_exe`` whenever you want the real install rather than a link to it.
+
 Finding a different interpreter
 --------------------------------
 

{python_discovery-1.5.3 → python_discovery-1.6.1}/pyproject.toml

@@ -133,6 +133,7 @@ lint.per-file-ignores."tests/**/*.py" = [
   "import-private-name",                  # private imports needed to test internal APIs
   "magic-value-comparison",               # Magic value used in comparison
   "private-member-access",                # private member access needed to test internals
+  "pytest-fixture-autouse",               # shared setup fixtures are meant to apply to every test
   "subprocess-without-shell-equals-true", # `subprocess` call: check for execution of untrusted input
   "suspicious-subprocess-import",         # subprocess import
   "too-many-arguments",                   # too many arguments (pytest fixtures)

{python_discovery-1.5.3 → python_discovery-1.6.1}/src/python_discovery/_discovery.py

@@ -423,7 +423,12 @@ def get_paths(env: Mapping[str, str]) -> Generator[Path, None, None]:
         except (AttributeError, ValueError):  # pragma: no cover # Windows only (no confstr)
             path = os.defpath
     if path:
-        for entry in map(Path, path.split(os.pathsep)):
+        # An empty component (a leading/trailing/doubled separator) means "the current directory", the
+        # same footgun a shell has when PATH is misconfigured - Path("") resolves to it. Since every
+        # yielded path here is later searched for interpreters to execute and interrogate, silently
+        # including the caller's CWD would let whatever directory virtualenv happens to run from smuggle
+        # in a candidate binary.
+        for entry in map(Path, filter(None, path.split(os.pathsep))):
             with suppress(OSError):
                 if entry.is_dir() and next(entry.iterdir(), None):
                     yield entry

{python_discovery-1.5.3 → python_discovery-1.6.1}/src/python_discovery/_py_info.py

@@ -167,6 +167,17 @@ class PythonInfo:  # ruff:ignore[too-many-public-methods]
         """The exec prefix of the system Python this interpreter is based on."""
         return self.real_prefix or self.base_exec_prefix or self.exec_prefix
 
+    @property
+    def system_exe(self) -> str:
+        """
+        The executable of the system Python this interpreter is based on.
+
+        :attr:`system_executable` stays ``None`` until :meth:`resolve_to_system` walks the prefix chain, so reading it
+        forces every caller to narrow a value discovery has already settled. The fallback here matches what resolution
+        itself writes when a prefix links back to its own interpreter.
+        """
+        return self.system_executable or self.executable
+
     def __repr__(self) -> str:
         return "{}({!r})".format(
             self.__class__.__name__,

{python_discovery-1.5.3 → python_discovery-1.6.1}/tests/py_info/test_py_info.py

@@ -511,3 +511,17 @@ def test_select_most_likely_prefers_machine_match(
         d.sysconfig_platform = plat
     result = PythonInfo._select_most_likely(discovered, target)
     assert result.sysconfig_platform == discovered_platforms[expected_idx]
+
+
+@pytest.mark.parametrize(
+    ("system_executable", "expected"),
+    [
+        pytest.param("/usr/bin/python3", "/usr/bin/python3", id="resolved"),
+        pytest.param(None, "/venv/bin/python", id="unresolved falls back to executable"),
+    ],
+)
+def test_py_info_system_exe(system_executable: str | None, expected: str) -> None:
+    info = copy.deepcopy(CURRENT)
+    info.executable = "/venv/bin/python"
+    info.system_executable = system_executable
+    assert info.system_exe == expected

{python_discovery-1.5.3 → python_discovery-1.6.1}/tests/test_discovery.py

@@ -161,6 +161,38 @@ def test_get_paths_no_path_env(monkeypatch: pytest.MonkeyPatch) -> None:
     assert paths
 
 
+@pytest.mark.parametrize(
+    ("raw_path", "expected"),
+    [
+        pytest.param("{first}{sep}", ["first"], id="trailing"),
+        pytest.param("{sep}{first}", ["first"], id="leading"),
+        pytest.param("{first}{sep}{sep}{second}", ["first", "second"], id="doubled"),
+    ],
+)
+def test_get_paths_skips_empty_entries(tmp_path: Path, raw_path: str, expected: list[str]) -> None:
+    """An empty PATH entry means "current directory" - it must never be searched for interpreters."""
+    dirs = {}
+    for name in ("first", "second"):
+        dirs[name] = tmp_path / name
+        dirs[name].mkdir()
+        (dirs[name] / "dummy").touch()
+
+    paths = list(get_paths({"PATH": raw_path.format(first=dirs["first"], second=dirs["second"], sep=os.pathsep)}))
+
+    assert paths == [dirs[name] for name in expected]
+
+
+def test_get_paths_empty_entry_does_not_yield_cwd(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Reproduces the exploit: an empty PATH entry used to resolve to the caller's CWD."""
+    cwd_marker = tmp_path / "python3.11"
+    cwd_marker.touch(mode=0o755)
+    monkeypatch.chdir(tmp_path)
+
+    paths = list(get_paths({"PATH": f"{os.pathsep}"}))
+
+    assert not any(path.resolve() == tmp_path.resolve() for path in paths)
+
+
 def test_lazy_path_dump_debug(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
     monkeypatch.setenv("_VIRTUALENV_DEBUG", "1")
     a_dir = tmp_path