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

{python_discovery-1.5.1 → python_discovery-1.5.3}/.github/dependabot.yaml

@@ -3,6 +3,11 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "daily"
+      interval: "weekly"
+      day: "tuesday"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
     cooldown:
       default-days: 7

{python_discovery-1.5.1 → python_discovery-1.5.3}/.github/workflows/check.yaml

@@ -38,7 +38,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
@@ -55,3 +55,26 @@ jobs:
         env:
           PYTEST_ADDOPTS: "-vv --durations=20"
           DIFF_AGAINST: HEAD
+  old-target:
+    runs-on: ubuntu-latest
+    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
+        with:
+          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

{python_discovery-1.5.1 → python_discovery-1.5.3}/.github/workflows/prepare-release.yaml

@@ -29,7 +29,7 @@ jobs:
           token: ${{ secrets.RELEASE_PAT }}
           persist-credentials: true
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"

{python_discovery-1.5.1 → python_discovery-1.5.3}/.github/workflows/release.yaml

@@ -15,7 +15,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
@@ -43,6 +43,6 @@ jobs:
           name: ${{ env.dists-artifact-name }}
           path: dist/
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
         with:
           attestations: true

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

@@ -5,7 +5,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.37.4
+    rev: 0.38.0
     hooks:
       - id: check-github-workflows
         args: ["--verbose"]
@@ -15,11 +15,11 @@ repos:
       - id: codespell
         additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.26.0"
+    rev: "v2.28.0"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.16.0"
+    rev: "v0.16.3"
     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.28.0
+    rev: v1.29.0
     hooks:
       - id: zizmor
   - repo: meta

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-discovery
-Version: 1.5.1
+Version: 1.5.3
 Summary: Python interpreter discovery
 Project-URL: Changelog, https://github.com/tox-dev/python-discovery/releases
 Project-URL: Documentation, https://python-discovery.readthedocs.io
@@ -68,6 +68,9 @@ 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
+warning naming the version it found.
+
 ## Usage
 
 ```python

{python_discovery-1.5.1 → python_discovery-1.5.3}/README.md

@@ -16,6 +16,9 @@ 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
+warning naming the version it found.
+
 ## Usage
 
 ```python

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

@@ -6,6 +6,23 @@
 
 .. towncrier release notes start
 
+********************
+ v1.5.3 (2026-08-24)
+********************
+
+Bug fixes - 1.5.3
+=================
+- Restore discovery of Python 3.6 and 3.7 interpreters: the interrogation script had grown 3.8-only syntax and is now
+  kept to Python 3.6. Candidates below 3.6 log one warning naming the version found instead of two debug-level query
+  attempts, and the verdict is cached so they are queried only once; an absolute-path spec for one raises
+  ``RuntimeError`` with the same message - by :user:`gaborbernat`. (:issue:`116`)
+- Prefer the version-matched system executable when CPython reports an existing generic executable for a copied POSIX
+  virtual environment. (:issue:`124`)
+
+Improved documentation - 1.5.3
+==============================
+- Document the version floors: runs on Python 3.8+, discovers interpreters down to 3.6 - by :user:`gaborbernat`. (:issue:`116`)
+
 ********************
  v1.5.1 (2026-07-31)
 ********************

{python_discovery-1.5.1 → python_discovery-1.5.3}/docs/conf.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -14,6 +15,7 @@ release = __version__
 copyright = f"2026-{datetime.now(tz=timezone.utc).year}, {company}"  # ruff:ignore[builtin-variable-shadowing]
 
 extensions = [
+    "sphinx_llm.txt",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.extlinks",
@@ -58,3 +60,5 @@ html_theme_options = {
     "sidebar_hide_name": True,
 }
 html_css_files = ["custom.css"]
+
+markdown_http_base = os.environ.get("READTHEDOCS_CANONICAL_URL", "")

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

@@ -243,6 +243,18 @@ The timeout applies to each individual interpreter being queried. If you set a v
 legitimate interpreters may be skipped; if too high, the discovery process may take longer to fail
 when encountering problematic interpreters.
 
+Supported Python versions
+-------------------------
+
+Two floors apply: python-discovery itself runs on Python 3.8+ (``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
+found, and the floor; the verdict is cached, so the interpreter is not queried again. Candidates too
+old to run the version check at all (before Python 2.7) fail as a generic query error. An
+absolute-path spec for a below-floor interpreter raises :class:`RuntimeError` with the same message.
+The floor moves only in a major release.
+
 Spec format reference
 -----------------------
 

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

@@ -59,11 +59,13 @@ test = [
   "pytest>=8.3.5",
   "pytest-mock>=3.14",
   "setuptools>=75.1",
+  "vermin>=1.6",
 ]
 docs = [
   "furo>=2025.12.19",
   "sphinx>=9.1",
   "sphinx-autodoc-typehints>=3.6.3",
+  "sphinx-llm>=0.4.1",
   "sphinxcontrib-mermaid>=2",
   "sphinxcontrib-towncrier>=0.4",
   "towncrier>=25.8",
@@ -87,50 +89,57 @@ lint.select = [
   "ALL",
 ]
 lint.ignore = [
-  "COM812", # Conflict with formatter
-  "CPY",    # No copyright statements
-  "D203",   # `one-blank-line-before-class` and `no-blank-line-before-class` are incompatible
-  "D212",   # `multi-line-summary-first-line` and `multi-line-summary-second-line` are incompatible
-  "DOC201", # `return` is not documented in docstring
-  "DOC402", # `yield` is not documented in docstring
-  "DOC501", # `raises` is not documented in docstring
-  "ISC001", # Conflict with formatter
-  "S104",   # Possible binding to all interface
+  "CPY",                                       # No copyright statements
+  "docstring-missing-exception",               # `raises` is not documented in docstring
+  "docstring-missing-returns",                 # `return` is not documented in docstring
+  "docstring-missing-yields",                  # `yield` is not documented in docstring
+  "hardcoded-bind-all-interfaces",             # Possible binding to all interface
+  "incorrect-blank-line-before-class",         # `one-blank-line-before-class` and `no-blank-line-before-class` are incompatible
+  "missing-trailing-comma",                    # Conflict with formatter
+  "multi-line-summary-first-line",             # `multi-line-summary-first-line` and `multi-line-summary-second-line` are incompatible
+  "single-line-implicit-string-concatenation", # Conflict with formatter
 ]
 lint.per-file-ignores."docs/**/*.py" = [
-  "INP001", # no __init__.py in docs directory
+  "implicit-namespace-package", # no __init__.py in docs directory
 ]
 lint.per-file-ignores."src/python_discovery/_discovery.py" = [
   "PTH", # shim resolution uses string-based os.path for consistency with env variables
 ]
 lint.per-file-ignores."src/python_discovery/_py_info.py" = [
-  "PTH", # must use os.path — file runs as subprocess script with only stdlib
+  "PTH", # string-based os.path kept for parity with the interrogation script data
+]
+lint.per-file-ignores."src/python_discovery/_py_info_collect.py" = [
+  "ANN",                              # file must parse on Python 2.7 for the version gate: no annotations
+  "missing-required-import",          # `from __future__ import annotations` is a SyntaxError below 3.7
+  "module-import-not-at-top-of-file", # the version gate must run before importing sysconfig, absent on 3.0/3.1
+  "PTH",                              # must use os.path — file runs as subprocess script with only stdlib
+  "UP",                               # pyupgrade pushes syntax newer than the 2.7 parse floor, e.g. f-strings
 ]
 lint.per-file-ignores."src/python_discovery/_windows/_pep514.py" = [
   "PTH", # os.path.exists is monkeypatched in tests; pathlib.Path.exists bypasses the mock
 ]
 lint.per-file-ignores."tasks/**/*.py" = [
-  "D",      # release helper scripts, not API
-  "INP001", # no __init__.py in tasks directory
-  "S404",   # subprocess import (release tooling)
-  "S603",   # `subprocess` call: argv built from trusted inputs (version, gh CLI)
+  "D",                                    # release helper scripts, not API
+  "implicit-namespace-package",           # no __init__.py in tasks directory
+  "subprocess-without-shell-equals-true", # `subprocess` call: argv built from trusted inputs (version, gh CLI)
+  "suspicious-subprocess-import",         # subprocess import (release tooling)
 ]
 lint.per-file-ignores."tests/**/*.py" = [
-  "D",       # don't care about documentation in tests
-  "FBT",     # don't care about booleans as positional arguments in tests
-  "INP001",  # no implicit namespace
-  "PLC0415", # imports inside test functions (conditional on mocking)
-  "PLC2701", # private imports needed to test internal APIs
-  "PLR0913", # too many arguments (pytest fixtures)
-  "PLR0917", # too many positional arguments (pytest fixtures)
-  "PLR2004", # Magic value used in comparison
-  "S101",    # asserts allowed in tests
-  "S404",    # subprocess import
-  "S603",    # `subprocess` call: check for execution of untrusted input
-  "SLF001",  # private member access needed to test internals
+  "assert",                               # asserts allowed in tests
+  "D",                                    # don't care about documentation in tests
+  "FBT",                                  # don't care about booleans as positional arguments in tests
+  "implicit-namespace-package",           # no implicit namespace
+  "import-outside-top-level",             # imports inside test functions (conditional on mocking)
+  "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
+  "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)
+  "too-many-positional-arguments",        # too many positional arguments (pytest fixtures)
 ]
 lint.per-file-ignores."tests/windows/winreg_mock_values.py" = [
-  "F821", # undefined name (winreg available only on Windows)
+  "undefined-name", # undefined name (winreg available only on Windows)
 ]
 lint.isort = { known-first-party = [
   "python_discovery",
@@ -151,7 +160,11 @@ max_supported_python = "3.15"
 src.exclude = [ "tests/windows/winreg_mock_values.py" ]
 
 [[tool.ty.overrides]]
-include = [ "src/python_discovery/_py_info.py", "src/python_discovery/_py_spec.py" ]
+include = [
+  "src/python_discovery/_py_info.py",
+  "src/python_discovery/_py_info_collect.py",
+  "src/python_discovery/_py_spec.py",
+]
 rules.unused-ignore-comment = "ignore"
 rules.invalid-argument-type = "ignore"
 rules.invalid-return-type = "ignore"
@@ -168,16 +181,16 @@ rules.unresolved-attribute = "ignore"
 ini_options.markers = [ "graalpy" ]
 
 [tool.coverage]
+run.source = [
+  "python_discovery",
+  "tests",
+]
 run.branch = true
 run.dynamic_context = "test_function"
 run.parallel = true
 run.plugins = [
   "covdefaults",
 ]
-run.source = [
-  "python_discovery",
-  "tests",
-]
 paths.source = [
   "src",
   ".tox*/*/lib/python*/site-packages",

{python_discovery-1.5.1 → python_discovery-1.5.3}/src/python_discovery/_cached_py_info.py

@@ -13,6 +13,7 @@ import sys
 import tempfile
 from collections import OrderedDict
 from contextlib import contextmanager
+from functools import lru_cache
 from pathlib import Path
 from shlex import quote
 from subprocess import Popen, TimeoutExpired  # ruff:ignore[suspicious-subprocess-import]
@@ -20,16 +21,30 @@ from typing import TYPE_CHECKING, Final
 
 from ._cache import NoOpCache
 from ._py_info import PythonInfo
+from ._py_info_collect import MIN_INTERROGATE_VERSION, UNSUPPORTED_EXIT_CODE, UNSUPPORTED_MARKER
 
 if TYPE_CHECKING:
     from collections.abc import Generator, Mapping
+    from typing import TypedDict
 
     from ._cache import ContentStore, PyInfoCache
 
+    class CacheEntryMeta(TypedDict):
+        """Identity of a cached interrogation result: the queried binary and the script that produced it."""
+
+        st_mtime: float
+        path: str
+        hash: str | None
+
 
 _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"
+
+
+class _UnsupportedInterpreterError(RuntimeError):
+    """The interpreter is older than the interrogation script supports; retrying cannot help."""
 
 
 def from_exe(  # ruff:ignore[too-many-arguments]
@@ -82,48 +97,54 @@ def _get_via_file_cache(
         path_modified = path.stat().st_mtime
     except OSError:
         path_modified = -1
-    py_info_script = Path(Path(__file__).resolve()).parent / "_py_info.py"
     try:
-        py_info_hash: str | None = hashlib.sha256(py_info_script.read_bytes()).hexdigest()
+        py_info_hash: str | None = _script_hash()
     except OSError:
         py_info_hash = None
 
     resolved_cache = cache if cache is not None else NoOpCache()
-    py_info: PythonInfo | None = None
     py_info_store = resolved_cache.py_info(path)
+    entry_meta: CacheEntryMeta = {"st_mtime": path_modified, "path": path_text, "hash": py_info_hash}
     with py_info_store.locked():
-        if py_info_store.exists() and (data := py_info_store.read()) is not None:
-            of_path, of_st_mtime = data.get("path"), data.get("st_mtime")
-            of_content, of_hash = data.get("content"), data.get("hash")
-            if (
-                of_path == path_text
-                and of_st_mtime == path_modified
-                and of_hash == py_info_hash
-                and isinstance(of_content, dict)
-            ):
-                py_info = _load_cached_py_info(cls, py_info_store, of_content)
-            else:
-                py_info_store.remove()
+        cached = _read_cache_entry(cls, py_info_store, entry_meta)
+        if isinstance(cached, _UnsupportedInterpreterError):
+            return cached
+        py_info = cached
         if py_info is None:
             failure, py_info = _run_subprocess(cls, exe, env)
-            if failure is not None:
+            if failure is not None and not isinstance(failure, _UnsupportedInterpreterError):
                 _LOGGER.debug("first subprocess attempt failed for %s (%s), retrying", exe, failure)
                 failure, py_info = _run_subprocess(cls, exe, env)
+            if isinstance(failure, _UnsupportedInterpreterError):
+                _LOGGER.warning("%s", failure)  # the verdict is permanent, warn once and remember it
+                py_info_store.write({**entry_meta, "unsupported": str(failure)})
+                return failure
             if failure is not None:
                 return failure
             if py_info is not None:
-                py_info_store.write({
-                    "st_mtime": path_modified,
-                    "path": path_text,
-                    "content": py_info.to_dict(),
-                    "hash": py_info_hash,
-                })
+                py_info_store.write({**entry_meta, "content": py_info.to_dict()})
     if py_info is None:
         msg = f"{exe} failed to produce interpreter info"
         return RuntimeError(msg)
     return py_info
 
 
+def _read_cache_entry(
+    cls: type[PythonInfo],
+    py_info_store: ContentStore,
+    entry_meta: CacheEntryMeta,
+) -> 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(unsupported := data.get("unsupported"), str):
+            return _UnsupportedInterpreterError(unsupported)
+        if isinstance(content := data.get("content"), dict):
+            return _load_cached_py_info(cls, py_info_store, content)
+    py_info_store.remove()
+    return None
+
+
 def _load_cached_py_info(
     cls: type[PythonInfo],
     py_info_store: ContentStore,
@@ -140,6 +161,11 @@ def _load_cached_py_info(
     return py_info
 
 
+@lru_cache(maxsize=1)
+def _script_hash() -> str:
+    return hashlib.sha256(_PY_INFO_SCRIPT.read_bytes()).hexdigest()
+
+
 COOKIE_LENGTH: Final[int] = 32
 
 
@@ -149,13 +175,12 @@ def gen_cookie() -> str:
 
 @contextmanager
 def _resolve_py_info_script() -> Generator[Path]:
-    py_info_script = Path(Path(__file__).resolve()).parent / "_py_info.py"
-    if py_info_script.is_file():
-        yield py_info_script
+    if _PY_INFO_SCRIPT.is_file():
+        yield _PY_INFO_SCRIPT
     else:
-        data = pkgutil.get_data(__package__ or __name__, "_py_info.py")
+        data = pkgutil.get_data(__package__ or __name__, _PY_INFO_SCRIPT.name)
         if data is None:
-            msg = "cannot locate _py_info.py for subprocess interrogation"
+            msg = f"cannot locate {_PY_INFO_SCRIPT.name} for subprocess interrogation"
             raise FileNotFoundError(msg)
         fd, tmp = tempfile.mkstemp(suffix=".py")
         try:
@@ -216,8 +241,7 @@ def _run_subprocess(
         except OSError as os_error:
             out, err, code = "", os_error.strerror, os_error.errno
     if code != 0:
-        msg = f"{exe} with code {code}{f' out: {out!r}' if out else ''}{f' err: {err!r}' if err else ''}"
-        return RuntimeError(f"failed to query {msg}"), None
+        return _query_failure(exe, out, err, code), None
     out, raw_out, out_starts, out_ends = _extract_between_cookies(out, start_cookie, end_cookie)
     try:
         result = cls.from_json(out)
@@ -240,6 +264,18 @@ def _run_subprocess(
     return None, result
 
 
+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
+    if code == UNSUPPORTED_EXIT_CODE and err is not None and (at := err.find(UNSUPPORTED_MARKER)) != -1:
+        version = err[at + len(UNSUPPORTED_MARKER) :].split() or ["unknown"]
+        floor = ".".join(str(i) for i in MIN_INTERROGATE_VERSION)
+        msg = f"{exe} is Python {version[0]}, older than the minimum {floor} python-discovery can query"
+        return _UnsupportedInterpreterError(msg)
+    msg = f"{exe} with code {code}{f' out: {out!r}' if out else ''}{f' err: {err!r}' if err else ''}"
+    return RuntimeError(f"failed to query {msg}")
+
+
 class LogCmd:
     def __init__(self, cmd: list[str], env: Mapping[str, str] | None = None) -> None:
         self.cmd = cmd