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

{python_discovery-1.4.4 → 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.4.4 → python_discovery-1.5.3}/.github/workflows/check.yaml

@@ -7,14 +7,11 @@ on:
   pull_request:
   schedule:
     - cron: "0 8 * * *"
-
 concurrency:
   group: check-${{ github.ref }}
   cancel-in-progress: true
-
 permissions:
   contents: read
-
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -22,6 +19,8 @@ jobs:
       fail-fast: false
       matrix:
         env:
+          - "3.15"
+          - "3.15t"
           - "3.14"
           - "3.13"
           - "3.12"
@@ -34,12 +33,12 @@ jobs:
           - dev
           - pkg_meta
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - 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@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
@@ -56,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.4.4 → python_discovery-1.5.3}/.github/workflows/prepare-release.yaml

@@ -12,13 +12,10 @@ on:
           - minor
           - patch
         default: auto
-
 permissions:
   contents: read
-
 env:
   FORCE_COLOR: 1
-
 jobs:
   prepare-release:
     runs-on: ubuntu-24.04
@@ -26,24 +23,21 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           token: ${{ secrets.RELEASE_PAT }}
           persist-credentials: true
-
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"
           github-token: ${{ secrets.GITHUB_TOKEN }}
-
       - name: Configure git
         run: |
           git config user.name "${GITHUB_ACTOR}"
           git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
-
       - name: Calculate next version
         id: version
         env:
@@ -84,16 +78,13 @@ 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
-
       - name: Run release process
         run: tox run -e release -- ${STEPS_VERSION_OUTPUTS_VERSION}
         env:
           GH_TOKEN: ${{ secrets.RELEASE_PAT }}
           STEPS_VERSION_OUTPUTS_VERSION: ${{ steps.version.outputs.version }}
-
       - name: Display completion message
         run: echo "Release ${STEPS_VERSION_OUTPUTS_VERSION} prepared and pushed successfully!"
         env:

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

@@ -2,23 +2,20 @@ name: Release to PyPI
 on:
   push:
     tags: ["*"]
-
 permissions:
   contents: read
-
 env:
   dists-artifact-name: python-package-distributions
-
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - 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@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
@@ -30,7 +27,6 @@ jobs:
         with:
           name: ${{ env.dists-artifact-name }}
           path: dist/*
-
   release:
     needs:
       - build
@@ -47,6 +43,6 @@ jobs:
           name: ${{ env.dists-artifact-name }}
           path: dist/
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
         with:
           attestations: true

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

@@ -5,34 +5,41 @@ 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"]
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.2
+    rev: v2.4.3
     hooks:
       - id: codespell
         additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.25.1"
+    rev: "v2.28.0"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.20"
+    rev: "v0.16.3"
     hooks:
       - id: ruff-format
       - id: ruff
         args: ["--fix", "--unsafe-fixes", "--exit-non-zero-on-fix"]
-  - repo: https://github.com/rbubley/mirrors-prettier
-    rev: "v3.9.4"
+  - repo: https://github.com/google/yamlfmt
+    rev: "v0.21.0"
     hooks:
-      - id: prettier
+      - id: yamlfmt
+  - repo: local
+    hooks:
+      - id: mdformat
+        name: mdformat
+        entry: mdformat --wrap 120
+        language: python
+        types: [markdown]
         additional_dependencies:
-          - prettier@3.8.1
-          - "@prettier/plugin-xml@3.4.2"
+          - mdformat-gfm>=1
+          - mdformat-ruff>=0.1.3
   - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: v1.26.1
+    rev: v1.29.0
     hooks:
       - id: zizmor
   - repo: meta

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-discovery
-Version: 1.4.4
+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
@@ -42,25 +42,12 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+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-Dist: platformdirs<5,>=4.3.6
-Provides-Extra: docs
-Requires-Dist: furo>=2025.12.19; extra == 'docs'
-Requires-Dist: sphinx-autodoc-typehints>=3.6.3; extra == 'docs'
-Requires-Dist: sphinx>=9.1; extra == 'docs'
-Requires-Dist: sphinxcontrib-mermaid>=2; extra == 'docs'
-Requires-Dist: sphinxcontrib-towncrier>=0.4; extra == 'docs'
-Requires-Dist: towncrier>=25.8; extra == 'docs'
-Provides-Extra: testing
-Requires-Dist: covdefaults>=2.3; extra == 'testing'
-Requires-Dist: coverage>=7.5.4; extra == 'testing'
-Requires-Dist: pytest-mock>=3.14; extra == 'testing'
-Requires-Dist: pytest>=8.3.5; extra == 'testing'
-Requires-Dist: setuptools>=75.1; extra == 'testing'
 Description-Content-Type: text/markdown
 
 # [`python-discovery`](https://python-discovery.readthedocs.io/en/latest/)
@@ -81,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.4.4 → 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.4.4 → python_discovery-1.5.3}/docs/changelog.rst

@@ -6,6 +6,49 @@
 
 .. 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)
+********************
+
+Bug fixes - 1.5.1
+=================
+- Locate uv's interpreter store the way uv does, using XDG on macOS (``~/.local/share/uv/python``) and roaming
+  ``%APPDATA%\uv\python`` on Windows, neither of which ``platformdirs`` reported. The uv variables now come from the
+  ``env`` mapping rather than ``os.environ`` - by :user:`gaborbernat`. (:issue:`109`)
+- Pick uv-managed interpreters by install directory name instead of globbing the store. A bare ``3.8`` now means
+  CPython, the way uv resolves it, rather than whichever implementation the filesystem happened to list first, and
+  probing runs newest version first - by :user:`gaborbernat`. (:issue:`110`)
+
+Packaging updates and notes for downstreams - 1.5.1
+===================================================
+- Drop the ``platformdirs`` runtime dependency; locating uv's store was the only thing it did - by
+  :user:`gaborbernat`. (:issue:`109`)
+
+********************
+ v1.5.0 (2026-07-21)
+********************
+
+Packaging updates and notes for downstreams - 1.5.0
+===================================================
+- Declare support for Python 3.15 and run the test suite against it, currently in beta. (:issue:`104`)
+
 ********************
  v1.4.4 (2026-07-08)
 ********************

{python_discovery-1.4.4 → 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
 
@@ -11,9 +12,10 @@ company = "tox-dev"
 name = "python-discovery"
 version = ".".join(__version__.split(".")[:2])
 release = __version__
-copyright = f"2026-{datetime.now(tz=timezone.utc).year}, {company}"  # noqa: A001
+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.4.4 → python_discovery-1.5.3}/docs/explanation.rst

@@ -68,9 +68,33 @@ detects these shims and resolves them to the actual binary.
 How uv-managed Pythons are discovered
 ---------------------------------------
 
-`uv <https://docs.astral.sh/uv/>`_ installs Python interpreters under a single root directory (configurable via
-``UV_PYTHON_INSTALL_DIR``, otherwise defaulting under ``XDG_DATA_HOME`` or the platform user-data path). Each
-install lives in its own subdirectory, but the actual binary location varies by OS and implementation:
+`uv <https://docs.astral.sh/uv/>`_ installs Python interpreters under a single root directory. ``UV_PYTHON_INSTALL_DIR``
+overrides it; otherwise the store is the ``python`` bucket of uv's state directory, which uv derives as follows:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Platform
+     - Legacy state directory
+     - Current state directory
+   * - Windows
+     - ``%APPDATA%\uv\data``
+     - ``%APPDATA%\uv`` (roaming, not local)
+   * - macOS
+     - ``~/Library/Application Support/uv``
+     - ``$XDG_DATA_HOME/uv`` or ``~/.local/share/uv``
+   * - Other
+     - same as current
+     - ``$XDG_DATA_HOME/uv`` or ``~/.local/share/uv``
+
+uv follows the XDG convention on macOS too, and falls back to the legacy directory only when that directory already
+exists. python-discovery searches both, in the same order, so a leftover legacy directory cannot hide the store uv
+installs into. A relative ``XDG_DATA_HOME`` does not count, as the XDG specification requires, and Windows ignores it
+outright. Every one of these variables comes from the ``env`` mapping passed to
+:func:`~python_discovery.get_interpreter`, rather than from the process environment.
+
+Each install lives in its own subdirectory, but the actual binary location varies by OS and implementation:
 
 .. list-table::
    :header-rows: 1
@@ -89,42 +113,51 @@ install lives in its own subdirectory, but the actual binary location varies by
      - ``<root>/<key>/bin/graalpy``
      - ``<root>/<key>/bin/graalpy.exe``
 
+GraalPy keeps its ``bin/`` segment on Windows (an upstream choice in uv); PyPy and CPython do not. python-discovery
+globs all of these patterns regardless of the host OS, because globs that do not match anything are essentially
+free, and the cross-platform list is short. Symlinked aliases inside an install (``bin/python``,
+``bin/python3``, ``bin/python3.14`` all pointing at the same real file) are deduplicated by resolved path before
+the subprocess interrogation, so each install is interrogated once. python-discovery also follows the ``install``
+subdirectory some distributions unpack into, as uv does.
+
+Which uv installs get interrogated
+------------------------------------
+
+Interrogating an interpreter costs a subprocess, and a uv install directory announces what it holds in its own name:
+``<implementation>-<version>[+<variant>]-<os>-<arch>-<libc>``, for example
+``cpython-3.14.6+freethreaded-macos-aarch64-none``. python-discovery reads that name and skips the installs the spec
+already rules out, then probes what is left in uv's preference order:
+
 .. mermaid::
 
     flowchart LR
-        Call(["iter_interpreters(key)"]) --> Mode{"key is None?"}
-        Mode -->|"narrow"| N1["*/bin/python"]
-        Mode -->|"narrow"| N2["*/python.exe"]
-        Mode -->|"wide"| W1["*/bin/pypy*"]
-        Mode -->|"wide"| W2["*/bin/graalpy"]
-        Mode -->|"wide"| W3["*/pypy*.exe"]
-        Mode -->|"wide"| W4["*/bin/graalpy.exe"]
-
-        N1 --> Dedup[/"realpath dedup"/]
-        N2 --> Dedup
-        W1 --> Dedup
-        W2 --> Dedup
-        W3 --> Dedup
-        W4 --> Dedup
-
-        Dedup --> Interrogate(["subprocess interrogation"])
-
-        style Call fill:#4a90d9,stroke:#2a5f8f,color:#fff
-        style Mode fill:#d9904a,stroke:#8f5f2a,color:#fff
-        style N1 fill:#3a7fc2,stroke:#1f4d7a,color:#fff
-        style N2 fill:#3a7fc2,stroke:#1f4d7a,color:#fff
-        style W1 fill:#9f4ad9,stroke:#5f2a8f,color:#fff
-        style W2 fill:#9f4ad9,stroke:#5f2a8f,color:#fff
-        style W3 fill:#9f4ad9,stroke:#5f2a8f,color:#fff
-        style W4 fill:#9f4ad9,stroke:#5f2a8f,color:#fff
-        style Dedup fill:#c2873a,stroke:#7a4c1f,color:#fff
+        Dirs[/"store subdirectories"/] --> Parse{"name is a uv key?"}
+        Parse -->|"no"| Last["probe last"]
+        Parse -->|"yes"| Filter["drop what the spec rules out:<br>implementation, version, free-threaded, debug"]
+        Filter --> Sort["CPython → PyPy → GraalPy,<br>newest version first,<br>default build before variants"]
+        Sort --> Interrogate(["subprocess interrogation"])
+        Last --> Interrogate
+
+        style Dirs fill:#4a90d9,stroke:#2a5f8f,color:#fff
+        style Parse fill:#d9904a,stroke:#8f5f2a,color:#fff
+        style Filter fill:#9f4ad9,stroke:#5f2a8f,color:#fff
+        style Sort fill:#c2873a,stroke:#7a4c1f,color:#fff
         style Interrogate fill:#4a9f4a,stroke:#2a6f2a,color:#fff
 
-GraalPy keeps its ``bin/`` segment on Windows (an upstream choice in uv); PyPy and CPython do not. python-discovery
-globs all of these patterns regardless of the host OS, because globs that do not match anything are essentially
-free, and the cross-platform list is short. Symlinked aliases inside an install (``bin/python``,
-``bin/python3``, ``bin/python3.14`` all pointing at the same real file) are deduplicated by resolved path before
-the subprocess interrogation, so each install is interrogated once.
+python-discovery reads the variant suffix the same way :class:`~python_discovery.PythonSpec` does: ``3.14t`` wants
+``+freethreaded``, ``3.14d`` wants ``+debug``. A spec that says nothing about a variant leaves it unconstrained, so
+``3.14`` still reaches a ``+debug`` install, after the default build rather than instead of it.
+
+A bare version spec such as ``3.8`` matches CPython only, which is what uv resolves it to and what the equivalent
+``python3.8`` probe on ``PATH`` finds in practice. Ask for ``pypy3.8`` or enumerate with
+:func:`~python_discovery.iter_interpreters` to reach the other implementations - PyPy ships a ``bin/python`` symlink,
+so a store-wide glob would otherwise hand back PyPy for ``3.8`` whenever the filesystem listed it first.
+
+Two names carry less information than they appear to. GraalPy keys named after the GraalVM release
+(``graalpy-24.1.1``, from older uv versions) do not constrain the version, and uv's minor version links
+(``cpython-3.15`` pointing at ``cpython-3.15.0b3``) move on the next patch release, so the concrete install ranks
+ahead of the link. Anything that is not a uv key - a hand-made ``UV_PYTHON_INSTALL_DIR`` layout, say - stays in
+the running, at the back of the queue.
 
 Selecting one interpreter vs. enumerating all of them
 -------------------------------------------------------
@@ -210,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
 -----------------------