python-discovery 1.6.0__tar.gz → 1.6.2__tar.gz

{python_discovery-1.6.0 → python_discovery-1.6.2}/.github/workflows/check.yaml

@@ -14,7 +14,7 @@ permissions:
   contents: read
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     strategy:
       fail-fast: false
       matrix:
@@ -27,9 +27,8 @@ jobs:
           - "3.11"
           - "3.10"
           - "3.9"
-          - "3.8"
-          - type-3.8
-          - type-3.14
+          - type-3.9
+          - type-3.15
           - dev
           - pkg_meta
     steps:
@@ -38,15 +37,16 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
+          python-version: "3.15"
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
           github-token: ${{ secrets.GITHUB_TOKEN }}
       - name: Install tox
-        run: uv tool install --python-preference only-managed --python 3.14 tox --with tox-uv
+        run: uv tool install --python-preference only-managed --python 3.15 tox --with tox-uv
       - name: Install Python
-        if: startsWith(matrix.env, '3.') && matrix.env != '3.14'
+        if: startsWith(matrix.env, '3.') && matrix.env != '3.15'
         run: uv python install --python-preference only-managed ${{ matrix.env }}
       - name: Setup test suite
         run: tox run -vv --notest --skip-missing-interpreters false -e ${{ matrix.env }}
@@ -56,25 +56,27 @@ jobs:
           PYTEST_ADDOPTS: "-vv --durations=20"
           DIFF_AGAINST: HEAD
   old-target:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
+          python-version: "3.15"
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
           github-token: ${{ secrets.GITHUB_TOKEN }}
       - name: Build the wheel
         run: uv build --wheel --out-dir dist .
-      - name: Discover Python 3.6
-        run: tasks/old_target_check.sh 3.6 discover
-      - name: Discover Python 3.7
-        run: tasks/old_target_check.sh 3.7 discover
-      - name: Reject Python 3.5
-        run: tasks/old_target_check.sh 3.5 rejected
-      - name: Reject Python 2.7
-        run: tasks/old_target_check.sh 2.7 rejected
+      - parallel:
+          - name: Discover Python 3.6
+            run: tasks/old_target_check.sh 3.6 discover
+          - name: Discover Python 3.7
+            run: tasks/old_target_check.sh 3.7 discover
+          - name: Reject Python 3.5
+            run: tasks/old_target_check.sh 3.5 rejected
+          - name: Reject Python 2.7
+            run: tasks/old_target_check.sh 2.7 rejected

{python_discovery-1.6.0 → python_discovery-1.6.2}/.github/workflows/prepare-release.yaml

@@ -29,8 +29,9 @@ jobs:
           token: ${{ secrets.RELEASE_PAT }}
           persist-credentials: true
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
+          python-version: "3.15"
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -79,7 +80,7 @@ jobs:
           echo "Next version: $next"
           echo "version=$next" >> $GITHUB_OUTPUT
       - name: Install tox
-        run: uv tool install --python-preference only-managed --python 3.14 tox@latest --with tox-uv
+        run: uv tool install --python-preference only-managed --python 3.15 tox@latest --with tox-uv
       - name: Run release process
         run: tox run -e release -- ${STEPS_VERSION_OUTPUTS_VERSION}
         env:

{python_discovery-1.6.0 → python_discovery-1.6.2}/.github/workflows/release.yaml

@@ -8,29 +8,30 @@ env:
   dists-artifact-name: python-package-distributions
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
+          python-version: "3.15"
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
           github-token: ${{ secrets.GITHUB_TOKEN }}
       - name: Build package
-        run: uv build --python 3.14 --python-preference only-managed --sdist --wheel . --out-dir dist
+        run: uv build --python 3.15 --python-preference only-managed --sdist --wheel . --out-dir dist
       - name: Store the distribution packages
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: ${{ env.dists-artifact-name }}
           path: dist/*
   release:
     needs:
       - build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     environment:
       name: release
       url: https://pypi.org/project/python-discovery/${{ github.ref_name }}
@@ -38,7 +39,7 @@ jobs:
       id-token: write
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: ${{ env.dists-artifact-name }}
           path: dist/

{python_discovery-1.6.0 → python_discovery-1.6.2}/.pre-commit-config.yaml

@@ -1,3 +1,5 @@
+default_language_version:
+  python: python3.15
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -5,7 +7,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.38.0
+    rev: 0.38.2
     hooks:
       - id: check-github-workflows
         args: ["--verbose"]
@@ -13,13 +15,12 @@ repos:
     rev: v2.4.3
     hooks:
       - id: codespell
-        additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.28.1"
+    rev: "v2.30.1"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.16.4"
+    rev: "v0.16.10"
     hooks:
       - id: ruff-format
       - id: ruff
@@ -39,7 +40,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.6.0 → python_discovery-1.6.2}/.readthedocs.yaml

@@ -4,5 +4,5 @@ build:
   tools: {}
   commands:
     - curl -LsSf https://astral.sh/uv/install.sh | sh
-    - ~/.local/bin/uv tool install tox --with tox-uv -p 3.14 --managed-python
+    - ~/.local/bin/uv tool install tox --with tox-uv -p 3.15 --managed-python
     - ~/.local/bin/tox run -e docs -- "$READTHEDOCS_OUTPUT/html"

python_discovery-1.6.2/.readthedocs.yml

@@ -0,0 +1,8 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools: {}
+  commands:
+    - curl -LsSf https://astral.sh/uv/install.sh | sh
+    - ~/.local/bin/uv tool install tox --with tox-uv -p 3.15 --managed-python
+    - ~/.local/bin/tox run -e docs -- "${READTHEDOCS_OUTPUT}"/html

{python_discovery-1.6.0 → python_discovery-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-discovery
-Version: 1.6.0
+Version: 1.6.2
 Summary: Python interpreter discovery
 Project-URL: Changelog, https://github.com/tox-dev/python-discovery/releases
 Project-URL: Documentation, https://python-discovery.readthedocs.io
@@ -35,7 +35,6 @@ Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -46,8 +45,8 @@ Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
-Requires-Python: >=3.8
-Requires-Dist: filelock>=3.15.4
+Requires-Python: >=3.9
+Requires-Dist: filelock>=3.16.1
 Description-Content-Type: text/markdown
 
 # [`python-discovery`](https://python-discovery.readthedocs.io/en/latest/)
@@ -68,7 +67,7 @@ the right one for you.
 Give it a requirement like `python3.12` or `>=3.11,<3.13`, and it searches all known locations, verifies each candidate,
 and returns detailed metadata about the match. Results are cached to disk so repeated lookups are fast.
 
-The library runs on Python 3.8+ and discovers interpreters as old as Python 3.6; anything older is skipped with a
+The library runs on Python 3.9+ and discovers interpreters as old as Python 3.6; anything older is skipped with a
 warning naming the version it found.
 
 ## Usage

{python_discovery-1.6.0 → python_discovery-1.6.2}/README.md

@@ -16,7 +16,7 @@ the right one for you.
 Give it a requirement like `python3.12` or `>=3.11,<3.13`, and it searches all known locations, verifies each candidate,
 and returns detailed metadata about the match. Results are cached to disk so repeated lookups are fast.
 
-The library runs on Python 3.8+ and discovers interpreters as old as Python 3.6; anything older is skipped with a
+The library runs on Python 3.9+ and discovers interpreters as old as Python 3.6; anything older is skipped with a
 warning naming the version it found.
 
 ## Usage

{python_discovery-1.6.0 → python_discovery-1.6.2}/docs/changelog.rst

@@ -6,6 +6,32 @@
 
 .. towncrier release notes start
 
+********************
+ v1.6.2 (2026-10-10)
+********************
+
+Bug fixes - 1.6.2
+=================
+- Discard malformed interpreter cache entries and query the interpreter again, including entries with missing,
+  non-string or unusable ``system_executable`` paths - by :user:`darrenhuai`. (:issue:`141`)
+- Use the default interpreter query timeout and warn for invalid ``PY_DISCOVERY_TIMEOUT`` values. Accept ``inf``
+  or values above the subprocess wait limit to disable the timeout - by :user:`darrenhuai`. (:issue:`143`)
+
+********************
+ 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)
 ********************

{python_discovery-1.6.0 → python_discovery-1.6.2}/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
 -------------------
 
@@ -241,12 +275,13 @@ If your system consistently hits timeouts, you can customize the timeout via the
 
 The timeout applies to each individual interpreter being queried. If you set a value that is too low,
 legitimate interpreters may be skipped; if too high, the discovery process may take longer to fail
-when encountering problematic interpreters.
+when encountering problematic interpreters. For invalid values, python-discovery logs a warning and uses
+the default of 15 seconds. Set ``inf`` to disable the timeout.
 
 Supported Python versions
 -------------------------
 
-Two floors apply: python-discovery itself runs on Python 3.8+ (``requires-python``), while discovery
+Two floors apply: python-discovery itself runs on Python 3.9+ (``requires-python``), while discovery
 reaches down to Python 3.6 - old enough to cover RHEL 8's system Python.
 
 python-discovery skips candidates below 3.6 with one warning naming the executable, the version

{python_discovery-1.6.0 → python_discovery-1.6.2}/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.6.0 → python_discovery-1.6.2}/docs/reference/environment-variables.rst

@@ -36,3 +36,7 @@ Setting this variable extends the allowed time for each interpreter query.
 - Setting the value too low may skip legitimate interpreters
 - Setting it too high increases discovery time when encountering problematic interpreters
 - The value is read from the environment dict passed to :func:`~python_discovery.get_interpreter`
+- For invalid values, including empty strings, ``nan``, ``0`` and negative numbers, python-discovery logs a warning
+  and uses the default of 15 seconds
+- ``inf`` or a value above 2,147,483.647 seconds (about 24.9 days) disables the timeout. This limit applies on all
+  platforms because some subprocess waits accept a signed 32-bit count of milliseconds

{python_discovery-1.6.0 → python_discovery-1.6.2}/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.6.0 → python_discovery-1.6.2}/pyproject.toml

@@ -19,7 +19,7 @@ license.file = "LICENSE"
 maintainers = [
   { name = "Bernát Gábor", email = "gaborjbernat@gmail.com" },
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
@@ -28,7 +28,6 @@ classifiers = [
   "Operating System :: Microsoft :: Windows",
   "Operating System :: POSIX",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
@@ -44,7 +43,7 @@ dynamic = [
   "version",
 ]
 dependencies = [
-  "filelock>=3.15.4",
+  "filelock>=3.16.1",
 ]
 urls.Changelog = "https://github.com/tox-dev/python-discovery/releases"
 urls.Documentation = "https://python-discovery.readthedocs.io"
@@ -55,24 +54,25 @@ urls.Tracker = "https://github.com/tox-dev/python-discovery/issues"
 [dependency-groups]
 test = [
   "covdefaults>=2.3",
-  "coverage>=7.5.4",
+  "coverage>=7.6.1",
   "pytest>=8.3.5",
-  "pytest-mock>=3.14",
-  "setuptools>=75.1",
-  "vermin>=1.6",
+  "pytest-mock>=3.14.1",
+  "setuptools>=75.3.4",
+  "typing-extensions>=4.12",
+  "vermin>=1.8",
 ]
 docs = [
   "furo>=2025.12.19",
   "sphinx>=9.1",
   "sphinx-autodoc-typehints>=3.6.3",
-  "sphinx-llm>=0.4.1",
+  "sphinx-llm>=0.4.1,!=1.1",
   "sphinxcontrib-mermaid>=2",
   "sphinxcontrib-towncrier>=0.4",
   "towncrier>=25.8",
 ]
 release = [
-  "gitpython>=3.1.46",
-  "packaging>=26",
+  "gitpython>=3.2",
+  "packaging>=26.2",
   "pre-commit>=4.5.1",
   "towncrier>=25.8",
 ]
@@ -81,6 +81,7 @@ release = [
 version.source = "vcs"
 
 [tool.ruff]
+target-version = "py39"
 line-length = 120
 format.preview = true
 format.docstring-code-line-length = 100
@@ -133,6 +134,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.6.0 → python_discovery-1.6.2}/src/python_discovery/_cached_py_info.py

@@ -41,6 +41,9 @@ _CACHE: OrderedDict[Path, PythonInfo | Exception] = OrderedDict()
 _CACHE[Path(sys.executable)] = PythonInfo()
 _LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
 _PY_INFO_SCRIPT: Final[Path] = Path(__file__).resolve().parent / "_py_info_collect.py"
+_DEFAULT_QUERY_TIMEOUT: Final[float] = 15.0
+# poll(2) limits milliseconds to a signed C int.
+_MAX_QUERY_TIMEOUT: Final[float] = (2**31 - 1) / 1000
 
 
 class _UnsupportedInterpreterError(RuntimeError):
@@ -136,7 +139,7 @@ def _read_cache_entry(
 ) -> PythonInfo | _UnsupportedInterpreterError | None:
     if not py_info_store.exists() or (data := py_info_store.read()) is None:
         return None
-    if all(data.get(key) == value for key, value in entry_meta.items()):
+    if isinstance(data, dict) and all(data.get(key) == value for key, value in entry_meta.items()):
         if isinstance(unsupported := data.get("unsupported"), str):
             return _UnsupportedInterpreterError(unsupported)
         if isinstance(content := data.get("content"), dict):
@@ -152,10 +155,10 @@ def _load_cached_py_info(
 ) -> PythonInfo | None:
     try:
         py_info = cls.from_dict(content.copy())
-    except (KeyError, TypeError):
-        py_info_store.remove()
-        return None
-    if (sys_exe := py_info.system_executable) is not None and not Path(sys_exe).exists():
+        stale = (sys_exe := py_info.system_executable) is not None and not Path(sys_exe).is_file()
+    except (AttributeError, KeyError, OSError, TypeError):
+        stale = True
+    if stale:
         py_info_store.remove()
         return None
     return py_info
@@ -214,7 +217,7 @@ def _run_subprocess(
 ) -> tuple[Exception | None, PythonInfo | None]:
     start_cookie = gen_cookie()
     end_cookie = gen_cookie()
-    timeout = float(env.get("PY_DISCOVERY_TIMEOUT", "15"))
+    timeout = _query_timeout(env.get("PY_DISCOVERY_TIMEOUT"))
     with _resolve_py_info_script() as py_info_script:
         cmd = [exe, str(py_info_script), start_cookie, end_cookie]
         env = dict(env)
@@ -264,6 +267,22 @@ def _run_subprocess(
     return None, result
 
 
+@lru_cache(maxsize=128)
+def _query_timeout(raw: str | None) -> float | None:
+    if raw is None:
+        return _DEFAULT_QUERY_TIMEOUT
+    try:
+        timeout = float(raw)
+    except ValueError:
+        timeout = 0.0
+    if timeout > 0:
+        return timeout if timeout <= _MAX_QUERY_TIMEOUT else None
+    _LOGGER.warning(
+        "ignoring PY_DISCOVERY_TIMEOUT=%r, not a positive number of seconds; using %s", raw, _DEFAULT_QUERY_TIMEOUT
+    )
+    return _DEFAULT_QUERY_TIMEOUT
+
+
 def _query_failure(exe: str, out: str, err: str | None, code: int | None) -> RuntimeError:
     # the gate's exit code and stderr marker must both be present: either alone can collide, an errno of 79 from a
     # failed exec or a shim that echoes the marker phrase, but only the gate produces the combination

{python_discovery-1.6.0 → python_discovery-1.6.2}/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.6.0 → python_discovery-1.6.2}/src/python_discovery/_py_info_collect.py

@@ -321,7 +321,7 @@ class PythonInfoCollector:
             "script_args": "--no-user-cfg",
         })  # conf files not parsed so they do not hijack paths
         if hasattr(sys, "_framework"):  # pragma: no cover # macOS framework builds only
-            sys._framework = None  # ruff:ignore[private-member-access]  # disable macOS static paths for framework
+            sys._framework = None  # ty: ignore[invalid-assignment]  # ruff:ignore[private-member-access]  # disable macOS static paths for framework
 
         with warnings.catch_warnings():  # disable warning for PEP-632
             warnings.simplefilter("ignore")

python_discovery-1.6.2/tests/test_cache_recovery.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING
+
+import pytest
+
+from python_discovery import DiskCache, PythonInfo
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        pytest.param("[]", id="list"),
+        pytest.param('"python"', id="string"),
+        pytest.param("3", id="number"),
+        pytest.param("true", id="bool"),
+        pytest.param("null", id="null"),
+    ],
+)
+def test_from_exe_recovers_non_object_cache(cached_interpreter: tuple[DiskCache, Path, dict], payload: str) -> None:
+    cache, cache_file, expected = cached_interpreter
+    cache_file.write_text(payload, encoding="utf-8")
+    result = PythonInfo.from_exe(sys.executable, cache, ignore_cache=True, resolve_to_host=False)
+    assert result is not None
+    assert (json.loads(result.to_json()), json.loads(cache_file.read_text(encoding="utf-8"))) == (
+        expected["content"],
+        expected,
+    )
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        pytest.param(None, id="missing"),
+        pytest.param("5", id="int"),
+        pytest.param('["python"]', id="list"),
+        pytest.param("{}", id="dict"),
+        pytest.param("true", id="bool"),
+        pytest.param('""', id="empty"),
+        pytest.param('"."', id="directory"),
+        pytest.param('"missing-python"', id="nonexistent"),
+        pytest.param('"python\\u0000"', id="nul"),
+        pytest.param(json.dumps("a" * 1024), id="path-too-long"),
+    ],
+)
+def test_from_exe_recovers_invalid_system_executable(
+    cached_interpreter: tuple[DiskCache, Path, dict], payload: str | None
+) -> None:
+    cache, cache_file, expected = cached_interpreter
+    data = json.loads(cache_file.read_text(encoding="utf-8"))
+    if payload is None:
+        del data["content"]["system_executable"]
+    else:
+        data["content"]["system_executable"] = json.loads(payload)
+    cache_file.write_text(json.dumps(data), encoding="utf-8")
+    result = PythonInfo.from_exe(sys.executable, cache, ignore_cache=True, resolve_to_host=False)
+    assert result is not None
+    assert (json.loads(result.to_json()), json.loads(cache_file.read_text(encoding="utf-8"))) == (
+        expected["content"],
+        expected,
+    )
+
+
+@pytest.fixture
+def cached_interpreter(tmp_path: Path) -> tuple[DiskCache, Path, dict]:
+    cache = DiskCache(tmp_path)
+    assert PythonInfo.from_exe(sys.executable, cache, ignore_cache=True, resolve_to_host=False) is not None
+    cache_file = next(tmp_path.rglob("*.json"))
+    return cache, cache_file, json.loads(cache_file.read_text(encoding="utf-8"))

{python_discovery-1.6.0 → python_discovery-1.6.2}/tests/test_cached_py_info.py

@@ -124,17 +124,6 @@ def test_run_subprocess_timeout(mocker: MockerFixture) -> None:
     assert mock_process.communicate.call_count == 2
 
 
-def test_run_subprocess_custom_timeout(mocker: MockerFixture) -> None:
-    mock_process = MagicMock()
-    mock_process.communicate.return_value = (json.dumps(PythonInfo().to_dict()), "")
-    mock_process.returncode = 0
-    mocker.patch("python_discovery._cached_py_info.Popen", return_value=mock_process)
-    env = dict(os.environ)
-    env["PY_DISCOVERY_TIMEOUT"] = "30"
-    _run_subprocess(PythonInfo, sys.executable, env)
-    mock_process.communicate.assert_called_once_with(timeout=30.0)
-
-
 def test_run_subprocess_nonzero_exit(mocker: MockerFixture) -> None:
     mock_process = MagicMock()
     mock_process.communicate.return_value = ("some output", "some error")

{python_discovery-1.6.0 → python_discovery-1.6.2}/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

{python_discovery-1.6.0 → python_discovery-1.6.2}/tests/test_py_info_collect.py

@@ -79,7 +79,7 @@ def no_framework(mocker: MockerFixture) -> None:
     mocker.patch.object(
         sysconfig,
         "get_config_var",
-        side_effect=lambda name: "" if name == "PYTHONFRAMEWORK" else get_config_var(name),
+        side_effect=lambda name: "" if name == "PYTHONFRAMEWORK" else get_config_var(name),  # ty: ignore[deprecated]  # resolves the deprecated Literal["SO"] overload even though name is a generic str
     )
 
 
@@ -187,7 +187,7 @@ def test_system_executable_framework_symlink_kept(tmp_path: Path, mocker: Mocker
     mocker.patch.object(
         sysconfig,
         "get_config_var",
-        side_effect=lambda name: "Python" if name == "PYTHONFRAMEWORK" else get_config_var(name),
+        side_effect=lambda name: "Python" if name == "PYTHONFRAMEWORK" else get_config_var(name),  # ty: ignore[deprecated]  # resolves the deprecated Literal["SO"] overload even though name is a generic str
     )
     mocker.patch.object(sys, "executable", str(link))
     assert PythonInfo().system_executable == str(link)

{python_discovery-1.6.0 → python_discovery-1.6.2}/tests/test_py_info_extra.py

@@ -225,7 +225,7 @@ def test_satisfies_path_not_abs_basename_match() -> None:
     # stem drops everything from the first dot, so python3.15t arrives as python3 and stops naming a free-threaded
     # build; only the Windows .exe belongs off the end.
     name = Path(info.original_executable).name
-    basename = name[: -len(".exe")] if name.endswith(".exe") else name
+    basename = name.removesuffix(".exe")
     spec = PythonSpec.from_string_spec(basename)
     assert info.satisfies(spec, impl_must_match=False) is True
 

python_discovery-1.6.2/tests/test_query_timeout.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from subprocess import Popen
+from typing import TYPE_CHECKING
+
+import pytest
+
+from python_discovery import PythonInfo
+
+if TYPE_CHECKING:
+    from pytest_mock import MockerFixture
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        pytest.param(None, 15.0, id="default"),
+        pytest.param("30", 30.0, id="seconds"),
+        pytest.param(" 0.5 ", 0.5, id="padded-fraction"),
+        pytest.param("inf", None, id="inf"),
+        pytest.param("1e30", None, id="beyond-platform-wait"),
+        pytest.param("2147483.647", 2147483.647, id="wait-limit"),
+        pytest.param("2147483.648", None, id="above-wait-limit"),
+    ],
+)
+def test_from_exe_query_timeout(
+    mocker: MockerFixture, caplog: pytest.LogCaptureFixture, raw: str | None, expected: float | None
+) -> None:
+    communicate = mocker.spy(Popen, "communicate")
+    env = {key: value for key, value in os.environ.items() if key != "PY_DISCOVERY_TIMEOUT"}
+    if raw is not None:
+        env["PY_DISCOVERY_TIMEOUT"] = raw
+    result = PythonInfo.from_exe(sys.executable, env=env, ignore_cache=True, resolve_to_host=False)
+    assert result is not None
+    assert result.version_info == sys.version_info
+    assert communicate.call_args_list[0].kwargs == {"timeout": expected}
+    assert not caplog.records
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        pytest.param("", id="empty"),
+        pytest.param("abc", id="words"),
+        pytest.param("0x10", id="hex"),
+        pytest.param("nan", id="nan"),
+        pytest.param("0", id="zero"),
+        pytest.param("-1", id="negative"),
+        pytest.param("-inf", id="negative-inf"),
+        pytest.param("1e-999", id="underflow"),
+    ],
+)
+def test_from_exe_invalid_timeout_warns_once(mocker: MockerFixture, caplog: pytest.LogCaptureFixture, raw: str) -> None:
+    communicate = mocker.spy(Popen, "communicate")
+    env = {**os.environ, "PY_DISCOVERY_TIMEOUT": raw}
+    for _ in range(2):
+        result = PythonInfo.from_exe(sys.executable, env=env, ignore_cache=True, resolve_to_host=False)
+        assert result is not None
+        assert result.version_info == sys.version_info
+    assert [call.kwargs for call in communicate.call_args_list] == [{"timeout": 15.0}] * 2
+    assert [(record.levelno, record.getMessage()) for record in caplog.records] == [
+        (logging.WARNING, f"ignoring PY_DISCOVERY_TIMEOUT={raw!r}, not a positive number of seconds; using 15.0")
+    ]
+
+
+def test_from_exe_timeout_warning_cache_is_bounded(caplog: pytest.LogCaptureFixture) -> None:
+    for index in range(129):
+        result = PythonInfo.from_exe(
+            sys.executable,
+            env={**os.environ, "PY_DISCOVERY_TIMEOUT": f"invalid-timeout-{index}"},
+            ignore_cache=True,
+            resolve_to_host=False,
+        )
+        assert result is not None
+        assert result.version_info == sys.version_info
+    caplog.clear()
+    for raw in ("invalid-timeout-128", "invalid-timeout-0"):
+        result = PythonInfo.from_exe(
+            sys.executable, env={**os.environ, "PY_DISCOVERY_TIMEOUT": raw}, ignore_cache=True, resolve_to_host=False
+        )
+        assert result is not None
+        assert result.version_info == sys.version_info
+    assert [record.getMessage() for record in caplog.records] == [
+        "ignoring PY_DISCOVERY_TIMEOUT='invalid-timeout-0', not a positive number of seconds; using 15.0"
+    ]

{python_discovery-1.6.0 → python_discovery-1.6.2}/tests/windows/conftest.py

@@ -43,7 +43,7 @@ def _load_registry_data(
     glob: dict[str, object] = {"winreg": winreg}
     mock_value_str = (Path(__file__).parent / "winreg_mock_values.py").read_text(encoding="utf-8")
     exec(mock_value_str, glob, loc)  # ruff:ignore[exec-builtin]
-    return loc["enum_collect"], loc["value_collect"], loc["key_open"], loc["hive_open"]  # type: ignore[return-value]
+    return loc["enum_collect"], loc["value_collect"], loc["key_open"], loc["hive_open"]  # ty: ignore[invalid-return-type]
 
 
 class _Key:
@@ -65,7 +65,7 @@ def _make_enum_key(enum_collect: dict[object, dict[int, object]]) -> object:
         result = enum_collect[key_id][at]
         if isinstance(result, OSError):
             raise result
-        return result  # type: ignore[return-value]
+        return result  # ty: ignore[invalid-return-type]
 
     return _enum_key
 

python_discovery-1.6.2/tox.toml

@@ -0,0 +1,89 @@
+requires = [ "tox>=4.64.7", "tox-uv>=1.29" ]
+env_list = [ "3.15", "type-3.15", "3.14", "3.13", "3.12", "3.11", "3.10", "3.9", "type-3.9", "3.15t", "docs", "fix", "pkg_meta" ]
+skip_missing_interpreters = true
+
+[env_run_base]
+description = "run the tests with pytest"
+default_base_python = [ "3.15" ]
+package = "wheel"
+wheel_build_env = ".pkg"
+dependency_groups = [ "test" ]
+pass_env = [ "DIFF_AGAINST", "PYTEST_*" ]
+set_env.COVERAGE_FILE = "{work_dir}{/}.coverage.{env_name}"
+commands = [
+  [ "coverage", "erase" ],
+  [
+    "coverage",
+    "run",
+    "-m",
+    "pytest",
+    { replace = "posargs", default = [
+      "--junitxml",
+      "{work_dir}{/}junit.{env_name}.xml",
+      "tests",
+    ], extend = true },
+  ],
+  [ "coverage", "combine" ],
+  [ "coverage", "report" ],
+  [ "coverage", "html", "-d", "{env_tmp_dir}{/}htmlcov" ],
+]
+
+[env_pkg_base]
+default_base_python = [ "3.15" ]
+
+[env."type-3.15"]
+description = "run type check on code base (3.15)"
+deps = [ "gitpython>=3.2", "packaging>=26.2", "ty==0.0.84" ]
+commands = [ [ "ty", "check", "--output-format", "concise", "--error-on-warning", "--python-version", "3.15", "." ] ]
+
+[env."type-3.9"]
+description = "run type check on code base (3.9)"
+deps = [ "gitpython>=3.2", "packaging>=26.2", "ty==0.0.84" ]
+commands = [ [ "ty", "check", "--output-format", "concise", "--error-on-warning", "--python-version", "3.9", "." ] ]
+
+[env.docs]
+description = "build documentation"
+dependency_groups = [ "docs" ]
+commands = [
+  [
+    "sphinx-build",
+    "-d",
+    "{env_tmp_dir}{/}doctree",
+    "docs",
+    "--color",
+    "-b",
+    "html",
+    "-W",
+    { replace = "posargs", default = [ "{work_dir}{/}docs_out" ], extend = true },
+  ],
+]
+
+[env.fix]
+description = "run static analysis and style check using flake8"
+skip_install = true
+deps = [ "pre-commit-uv>=4.2.1" ]
+pass_env = [ "HOMEPATH", "PROGRAMDATA" ]
+commands = [ [ "pre-commit", "run", "--all-files", "--show-diff-on-failure" ] ]
+
+[env.pkg_meta]
+description = "check that the long description is valid"
+skip_install = true
+deps = [ "check-wheel-contents>=0.6.3", "twine>=6.2", "uv>=0.12.22" ]
+commands = [
+  [ "uv", "build", "--sdist", "--wheel", "--out-dir", "{env_tmp_dir}", "." ],
+  [ "twine", "check", "{env_tmp_dir}{/}*" ],
+  [ "check-wheel-contents", "--no-config", "{env_tmp_dir}" ],
+]
+
+[env.dev]
+description = "generate a DEV environment"
+package = "editable"
+dependency_groups = [ "test" ]
+commands = [ [ "uv", "pip", "tree" ], [ "python", "-c", "import sys; print(sys.executable)" ] ]
+
+[env.release]
+description = "do a release, required posargs of the version number"
+skip_install = true
+dependency_groups = [ "release" ]
+pass_env = [ "GH_TOKEN" ]
+commands = [ [ "python", "{tox_root}/tasks/release.py", "--version", "{posargs}" ] ]

python_discovery-1.6.0/.readthedocs.yml

@@ -1,8 +0,0 @@
-version: 2
-build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.12"
-  commands:
-    - pip install tox
-    - tox r -e docs -- "${READTHEDOCS_OUTPUT}"/html

python_discovery-1.6.0/tox.toml

@@ -1,85 +0,0 @@
-requires = ["tox>=4.38", "tox-uv>=1.29"]
-env_list = ["fix", "3.15", "3.15t", "3.14", "3.13", "3.12", "3.11", "3.10", "3.9", "3.8", "type-3.8", "type-3.14", "docs", "pkg_meta"]
-skip_missing_interpreters = true
-
-[env_run_base]
-description = "run the tests with pytest"
-package = "wheel"
-wheel_build_env = ".pkg"
-dependency_groups = ["test"]
-pass_env = ["DIFF_AGAINST", "PYTEST_*"]
-set_env.COVERAGE_FILE = "{work_dir}{/}.coverage.{env_name}"
-commands = [
-  ["coverage", "erase"],
-  [
-    "coverage",
-    "run",
-    "-m",
-    "pytest",
-    { replace = "posargs", extend = true, default = [
-      "--junitxml",
-      "{work_dir}{/}junit.{env_name}.xml",
-      "tests",
-    ] },
-  ],
-  ["coverage", "combine"],
-  ["coverage", "report"],
-  ["coverage", "html", "-d", "{env_tmp_dir}{/}htmlcov"],
-]
-
-[env.fix]
-description = "run static analysis and style check using flake8"
-skip_install = true
-deps = ["pre-commit-uv>=4.2.1"]
-pass_env = ["HOMEPATH", "PROGRAMDATA"]
-commands = [["pre-commit", "run", "--all-files", "--show-diff-on-failure"]]
-
-[env."type-3.8"]
-description = "run type check on code base (3.8)"
-deps = ["gitpython>=3.1.46", "packaging>=26", "ty==0.0.17"]
-commands = [["ty", "check", "--output-format", "concise", "--error-on-warning", "--python-version", "3.8", "."]]
-
-[env."type-3.14"]
-description = "run type check on code base (3.14)"
-deps = ["gitpython>=3.1.46", "packaging>=26", "ty==0.0.17"]
-commands = [["ty", "check", "--output-format", "concise", "--error-on-warning", "--python-version", "3.14", "."]]
-
-[env.docs]
-description = "build documentation"
-dependency_groups = ["docs"]
-commands = [
-  [
-    "sphinx-build",
-    "-d",
-    "{env_tmp_dir}{/}doctree",
-    "docs",
-    "--color",
-    "-b",
-    "html",
-    "-W",
-    { replace = "posargs", extend = true, default = ["{work_dir}{/}docs_out"] },
-  ],
-]
-
-[env.pkg_meta]
-description = "check that the long description is valid"
-skip_install = true
-deps = ["check-wheel-contents>=0.6.3", "twine>=6.2", "uv>=0.10.4"]
-commands = [
-  ["uv", "build", "--sdist", "--wheel", "--out-dir", "{env_tmp_dir}", "."],
-  ["twine", "check", "{env_tmp_dir}{/}*"],
-  ["check-wheel-contents", "--no-config", "{env_tmp_dir}"],
-]
-
-[env.release]
-description = "do a release, required posargs of the version number"
-skip_install = true
-dependency_groups = ["release"]
-pass_env = ["GH_TOKEN"]
-commands = [["python", "{tox_root}/tasks/release.py", "--version", "{posargs}"]]
-
-[env.dev]
-description = "generate a DEV environment"
-package = "editable"
-dependency_groups = ["test"]
-commands = [["uv", "pip", "tree"], ["python", "-c", "import sys; print(sys.executable)"]]