python-discovery 1.2.2__tar.gz → 1.3.1__tar.gz

{python_discovery-1.2.2 → python_discovery-1.3.1}/.github/workflows/check.yaml

@@ -39,7 +39,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"

python_discovery-1.3.1/.github/workflows/prepare-release.yaml

@@ -0,0 +1,100 @@
+name: Prepare Release
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        type: choice
+        options:
+          - auto
+          - major
+          - minor
+          - patch
+        default: auto
+
+permissions:
+  contents: read
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  prepare-release:
+    runs-on: ubuntu-24.04
+    environment: release-auth
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_PAT }}
+          persist-credentials: true
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        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:
+          BUMP: ${{ inputs.bump }}
+        run: |
+          current=$(git describe --tags --abbrev=0 2>/dev/null || echo "0.0.0")
+          echo "Current version: $current"
+
+          IFS='.' read -r major minor patch <<< "$current"
+
+          bump_type="$BUMP"
+          if [ "$bump_type" = "auto" ]; then
+            feature_count=$(find docs/changelog -name "*.feature.rst" 2>/dev/null | wc -l)
+            breaking_count=$(find docs/changelog -name "*.breaking.rst" 2>/dev/null | wc -l)
+            if [ "$breaking_count" -gt 0 ]; then
+              bump_type="major"
+              echo "Auto-detected: major bump (found $breaking_count breaking changelog(s))"
+            elif [ "$feature_count" -gt 0 ]; then
+              bump_type="minor"
+              echo "Auto-detected: minor bump (found $feature_count feature changelog(s))"
+            else
+              bump_type="patch"
+              echo "Auto-detected: patch bump (no feature changelogs)"
+            fi
+          fi
+
+          case "$bump_type" in
+            major)
+              next="$((major + 1)).0.0"
+              ;;
+            minor)
+              next="$major.$((minor + 1)).0"
+              ;;
+            patch)
+              next="$major.$minor.$((patch + 1))"
+              ;;
+          esac
+
+          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:
+          STEPS_VERSION_OUTPUTS_VERSION: ${{ steps.version.outputs.version }}

{python_discovery-1.2.2 → python_discovery-1.3.1}/.github/workflows/release.yaml

@@ -18,7 +18,7 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
@@ -26,7 +26,7 @@ jobs:
       - name: Build package
         run: uv build --python 3.14 --python-preference only-managed --sdist --wheel . --out-dir dist
       - name: Store the distribution packages
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: ${{ env.dists-artifact-name }}
           path: dist/*
@@ -47,6 +47,6 @@ jobs:
           name: ${{ env.dists-artifact-name }}
           path: dist/
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
         with:
           attestations: true

{python_discovery-1.2.2 → python_discovery-1.3.1}/.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.1
+    rev: 0.37.2
     hooks:
       - id: check-github-workflows
         args: ["--verbose"]
@@ -15,24 +15,24 @@ repos:
       - id: codespell
         additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.21.0"
+    rev: "v2.21.2"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.9"
+    rev: "v0.15.12"
     hooks:
       - id: ruff-format
       - id: ruff
         args: ["--fix", "--unsafe-fixes", "--exit-non-zero-on-fix"]
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: "v3.8.1"
+    rev: "v3.8.3"
     hooks:
       - id: prettier
         additional_dependencies:
           - prettier@3.8.1
           - "@prettier/plugin-xml@3.4.2"
   - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: v1.23.1
+    rev: v1.24.1
     hooks:
       - id: zizmor
   - repo: meta

{python_discovery-1.2.2 → python_discovery-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-discovery
-Version: 1.2.2
+Version: 1.3.1
 Summary: Python interpreter discovery
 Project-URL: Changelog, https://github.com/tox-dev/python-discovery/releases
 Project-URL: Documentation, https://python-discovery.readthedocs.io
@@ -53,6 +53,8 @@ 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'
@@ -99,7 +101,8 @@ The `get_interpreter()` function accepts various specification formats:
 - Absolute path: `/usr/bin/python3.12`
 - Version: `3.12`
 - Implementation prefix: `cpython3.12`
-- PEP 440 specifier: `>=3.10`, `>=3.11,<3.13`
+- [Version specifier](https://packaging.python.org/en/latest/specifications/version-specifiers/): `>=3.10`,
+  `>=3.11,<3.13`
 
 ## Documentation
 

{python_discovery-1.2.2 → python_discovery-1.3.1}/README.md

@@ -36,7 +36,8 @@ The `get_interpreter()` function accepts various specification formats:
 - Absolute path: `/usr/bin/python3.12`
 - Version: `3.12`
 - Implementation prefix: `cpython3.12`
-- PEP 440 specifier: `>=3.10`, `>=3.11,<3.13`
+- [Version specifier](https://packaging.python.org/en/latest/specifications/version-specifiers/): `>=3.10`,
+  `>=3.11,<3.13`
 
 ## Documentation
 

python_discovery-1.3.1/docs/changelog/template.jinja2

@@ -0,0 +1,38 @@
+{% set top_underline = "*" %}
+{% set underline = "=" %}
+{% if versiondata.name %}
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 5)}}
+ v{{ versiondata.version }} ({{ versiondata.date }})
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 5)}}
+{% else %}
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 4)}}
+ {{ versiondata.version }} ({{ versiondata.date }})
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 4)}}
+{% endif %}
+
+{% for section, _ in sections.items() %}
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section]%}
+{{ definitions[category]['name'] }} - {{ versiondata.version }}
+{{ underline * ((definitions[category]['name']  + versiondata.version)|length + 3)}}
+{% if definitions[category]['showcontent'] %}
+{% for text, values in sections[section][category].items() %}
+- {{ text }} ({{ values|join(', ') }})
+{% endfor %}
+
+{% else %}
+- {{ sections[section][category]['']|join(', ') }}
+
+{% endif %}
+{% if sections[section][category]|length == 0 %}
+No significant changes.
+
+{% else %}
+{% endif %}
+{% endfor %}
+{% else %}
+No significant changes.
+
+
+{% endif %}
+{% endfor %}

python_discovery-1.3.1/docs/changelog.rst

@@ -0,0 +1,125 @@
+#################
+ Release History
+#################
+
+.. towncrier-draft-entries::
+
+.. towncrier release notes start
+
+********************
+ v1.3.1 (2026-05-12)
+********************
+
+Bug fixes - 1.3.1
+=================
+- export normalize_isa and deprecate KNOWN_ARCHITECTURES - by :user:`rahuldevikar`. (:issue:`59`)
+- discover uv-managed Pythons on Windows. Previously the glob assumed Unix layout (``<root>/<key>/bin/python``) and
+  silently found nothing on Windows, where uv places ``python.exe`` directly under the install root - by
+  :user:`gaborbernat`. (:issue:`65`)
+- Canonicalize GraalVM to match GraalPy Python interpreter in PythonSpec and PythonInfo. - by :user:`timfel`. (:issue:`73`)
+
+********************
+ v1.3.0 (2026-05-05)
+********************
+
+Features - 1.3.0
+================
+
+- Add :func:`~python_discovery.iter_interpreters` for enumerating every discovered interpreter, with PATH and
+  UV-install support for non-CPython implementations listed in :data:`~python_discovery.KNOWN_IMPLEMENTATIONS`
+  (:pull:`71`)
+
+********************
+ v1.2.2 (2026-04-06)
+********************
+
+Features - 1.2.2
+================
+
+- Export ``normalize_isa`` and deprecate ``KNOWN_ARCHITECTURES`` (:pull:`62`)
+
+********************
+ v1.2.1 (2026-03-26)
+********************
+
+Features - 1.2.1
+================
+
+- Expose ``KNOWN_ARCHITECTURES`` as public API (:pull:`56`)
+
+Contributor-facing changes - 1.2.1
+==================================
+
+- Add zizmor security auditing for workflows (:pull:`55`)
+
+********************
+ v1.2.0 (2026-03-18)
+********************
+
+Features - 1.2.0
+================
+
+- Increase interpreter query timeout to 15s, with an override (:pull:`53`)
+
+********************
+ v1.1.3 (2026-03-10)
+********************
+
+Bug fixes - 1.1.3
+=================
+
+- Add ``loongarch64`` to known ISAs (:pull:`50`)
+
+********************
+ v1.1.2 (2026-03-09)
+********************
+
+Bug fixes - 1.1.2
+=================
+
+- Match prerelease versions against ``major.minor`` specs (:pull:`48`)
+- Drain pipes after killing a timed-out interpreter probe (:pull:`49`)
+
+Improved documentation - 1.1.2
+==============================
+
+- Add package description and usage to the README (:pull:`46`)
+
+********************
+ v1.1.1 (2026-03-06)
+********************
+
+Bug fixes - 1.1.1
+=================
+
+- Add a timeout to interpreter probing (:pull:`42`)
+- Add ``i686`` to known ISAs (:pull:`43`)
+
+Contributor-facing changes - 1.1.1
+==================================
+
+- Add a security policy and workflow permissions hardening (:pull:`33`)
+
+********************
+ v1.1.0 (2026-02-26)
+********************
+
+Features - 1.1.0
+================
+
+- Add a ``predicate`` parameter to :func:`~python_discovery.get_interpreter` (:pull:`31`)
+
+Improved documentation - 1.1.0
+==============================
+
+- Fix the ReadTheDocs build (:pull:`29`)
+- Add ``:param:`` descriptions to all public APIs (:pull:`32`)
+
+********************
+ v1.0.0 (2026-02-25)
+********************
+
+Features - 1.0.0
+================
+
+- Initial release as a standalone package, extracted from ``virtualenv`` (:pull:`28`)

{python_discovery-1.2.2 → python_discovery-1.3.1}/docs/conf.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from datetime import datetime, timezone
+from pathlib import Path
 
 from python_discovery import __version__
 
@@ -19,8 +20,13 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
     "sphinxcontrib.mermaid",
+    "sphinxcontrib.towncrier.ext",
 ]
 
+towncrier_draft_autoversion_mode = "draft"
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = Path(__file__).parent.parent
+
 extlinks = {
     "issue": ("https://github.com/tox-dev/python-discovery/issues/%s", "#%s"),
     "pull": ("https://github.com/tox-dev/python-discovery/pull/%s", "PR #%s"),
@@ -33,7 +39,7 @@ intersphinx_mapping = {
 
 templates_path = []
 source_suffix = ".rst"
-exclude_patterns = ["_build", "changelog/*.rst"]
+exclude_patterns = ["_build", "changelog/*"]
 
 main_doc = "index"
 pygments_style = "default"

{python_discovery-1.2.2 → python_discovery-1.3.1}/docs/explanation.rst

@@ -65,6 +65,106 @@ detects these shims and resolves them to the actual binary.
 `mise <https://mise.jdx.dev/>`_ and `asdf <https://asdf-vm.com/>`_ work similarly, using the
 ``MISE_DATA_DIR`` and ``ASDF_DATA_DIR`` environment variables to locate their installations.
 
+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:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 35 40
+
+   * - Implementation
+     - Unix layout
+     - Windows layout
+   * - CPython
+     - ``<root>/<key>/bin/python``
+     - ``<root>/<key>/python.exe``
+   * - PyPy
+     - ``<root>/<key>/bin/pypy*``
+     - ``<root>/<key>/pypy*.exe``
+   * - GraalPy
+     - ``<root>/<key>/bin/graalpy``
+     - ``<root>/<key>/bin/graalpy.exe``
+
+.. 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
+        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.
+
+Selecting one interpreter vs. enumerating all of them
+-------------------------------------------------------
+
+:func:`~python_discovery.get_interpreter` and :func:`~python_discovery.iter_interpreters` walk the same candidate
+sources, but they answer different questions and behave differently in three ways.
+
+.. mermaid::
+
+    flowchart LR
+        Sources["candidate sources<br>(try_first_with → current →<br>PEP 514 → PATH → uv)"]
+        Sources --> Get["get_interpreter()<br>first match wins, returns one"]
+        Sources --> Iter["iter_interpreters()<br>yields every match"]
+
+        style Get fill:#4a9f4a,stroke:#2a6f2a,color:#fff
+        style Iter fill:#4a90d9,stroke:#2a5f8f,color:#fff
+
+**Implementation coverage on PATH.** :func:`~python_discovery.get_interpreter` matches only ``python*`` filenames on
+PATH unless the spec names another implementation explicitly (``pypy3.12``, ``graalpy3.11``). This keeps backwards
+compatibility with tools that have always read "no implementation in the spec" as "give me CPython."
+:func:`~python_discovery.iter_interpreters` with no spec broadens the search to every name in
+:data:`~python_discovery.KNOWN_IMPLEMENTATIONS` -- otherwise an "all interpreters" call would silently miss every
+PyPy and GraalPy on the system. When you pass a spec to :func:`~python_discovery.iter_interpreters`, it falls back
+to the same narrow regex as :func:`~python_discovery.get_interpreter`, so behavior is consistent across the two
+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``).
+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.
+
+**Iteration order.** Yields come back in *priority order*: ``try_first_with`` first, then the running interpreter,
+then :pep:`514` entries on Windows, then PATH left-to-right, then UV-managed installs. This matches what
+:func:`~python_discovery.get_interpreter` would have returned at each step. If your ordering differs (newest
+version first, smallest install root, etc.), wrap the call in :func:`sorted` -- the API deliberately does not
+include a ``sort_by`` parameter because keeping discovery order preserves the priority signal for callers who
+want it.
+
 How caching works
 -------------------
 
@@ -165,9 +265,12 @@ A spec string follows the pattern ``[impl][version][t][-arch][-machine]``. Every
    * - ``/usr/bin/python3``
      - Absolute path, used directly (no search)
    * - ``>=3.11,<3.13``
-     - :pep:`440` version specifier (any Python in range)
+     - `Version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_
+       (any Python in range)
    * - ``cpython>=3.11``
-     - :pep:`440` specifier restricted to CPython
+     - `Version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_
+       restricted to CPython
 
-:pep:`440` specifiers (``>=``, ``<=``, ``~=``, ``!=``, ``==``, ``===``) are supported. Multiple
-specifiers can be comma-separated, for example ``>=3.11,<3.13``.
+`Version specifiers <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_
+(``>=``, ``<=``, ``~=``, ``!=``, ``==``, ``===``) are supported. Multiple specifiers can be comma-separated,
+for example ``>=3.11,<3.13``.

{python_discovery-1.2.2 → python_discovery-1.3.1}/docs/how-to/standalone-usage.rst

@@ -62,6 +62,60 @@ the ``PY_DISCOVERY_TIMEOUT`` environment variable.
 The timeout value should be a number in seconds. Each interpreter candidate is given this much time
 to respond. If a timeout occurs, the candidate is skipped and the search continues with the next one.
 
+List every interpreter on the system
+--------------------------------------
+
+Use :func:`~python_discovery.iter_interpreters` to enumerate every Python python-discovery can find. With no spec
+it yields all known implementations (CPython, PyPy, GraalPy -- see
+:data:`~python_discovery.KNOWN_IMPLEMENTATIONS`). Pass a spec to filter, exactly like
+:func:`~python_discovery.get_interpreter`.
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   from python_discovery import DiskCache, iter_interpreters
+
+   cache = DiskCache(root=Path("~/.cache/python-discovery").expanduser())
+
+   # Every interpreter, no filter
+   for info in iter_interpreters(cache=cache):
+       print(info.executable, info.version_str, info.implementation)
+
+   # Every CPython 3.10 or newer, newest first
+   newest_first = sorted(
+       iter_interpreters("cpython>=3.10", cache=cache),
+       key=lambda info: info.version_info,
+       reverse=True,
+   )
+
+Enumeration interrogates every candidate as a subprocess on a cold cache. Always pass a
+:class:`~python_discovery.DiskCache` if you call this more than once.
+
+Pick an interpreter from a range, preferring newer
+----------------------------------------------------
+
+A common need: search a version range and prefer newer interpreters when more than one matches. Sort the result of
+:func:`~python_discovery.iter_interpreters` and take the first.
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   from python_discovery import DiskCache, iter_interpreters
+
+   cache = DiskCache(root=Path("~/.cache/python-discovery").expanduser())
+
+   matches = sorted(
+       iter_interpreters("cpython>=3.10,<3.15", cache=cache),
+       key=lambda info: info.version_info,
+       reverse=True,
+   )
+   info = matches[0] if matches else None
+
+Use :func:`get_interpreter` instead when you only need the first PATH-priority hit; use the sort-and-take pattern
+when *your* ordering differs from PATH order (newest version, smallest install size, preferred install root, etc.).
+
 Read interpreter metadata
 ---------------------------
 

{python_discovery-1.2.2 → python_discovery-1.3.1}/docs/index.rst

@@ -47,3 +47,9 @@ repeated lookups are fast.
    :hidden:
 
    explanation
+
+.. toctree::
+   :caption: Project
+   :hidden:
+
+   changelog

{python_discovery-1.2.2 → python_discovery-1.3.1}/docs/tutorial/getting-started.rst

@@ -87,6 +87,49 @@ You can pass multiple specs as a list -- the library tries each one in order and
 
    result = get_interpreter(["python3.12", "python3.11"], cache=cache)
 
+Listing every interpreter
+---------------------------
+
+When you need *every* interpreter rather than just the first match -- for example, to show the user a chooser, or
+to apply your own ranking -- use :func:`~python_discovery.iter_interpreters`. Pass no arguments to enumerate every
+implementation python-discovery knows about, or pass a spec to filter.
+
+.. mermaid::
+
+    flowchart TD
+        Call["iter_interpreters(spec, cache)"] --> Yield["yields PythonInfo"]
+        Yield --> A["1. try_first_with paths"]
+        Yield --> B["2. running interpreter"]
+        Yield --> C["3. PATH (left to right)"]
+        Yield --> D["4. uv-managed installs"]
+
+        style Call fill:#4a90d9,stroke:#2a5f8f,color:#fff
+        style Yield fill:#4a9f4a,stroke:#2a6f2a,color:#fff
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   from python_discovery import DiskCache, iter_interpreters
+
+   cache = DiskCache(root=Path("~/.cache/python-discovery").expanduser())
+   for info in iter_interpreters(cache=cache):
+       print(info.executable, info.version_str, info.implementation)
+
+The result is an iterator, so :func:`list`, :func:`sorted`, generator expressions and early ``break`` all work as you
+would expect. Symlinked aliases (``/bin/python3`` and ``/usr/bin/python3``, or a virtualenv and the base it points at)
+collapse to a single entry, so you do not see the same install twice.
+
+To prefer newer interpreters in a range, sort the result by ``version_info`` after filtering:
+
+.. code-block:: python
+
+   newest_first = sorted(
+       iter_interpreters(">=3.10,<3.15", cache=cache),
+       key=lambda info: info.version_info,
+       reverse=True,
+   )
+
 Writing specs
 -------------
 
@@ -131,7 +174,8 @@ Common examples:
    * - ``/usr/bin/python3``
      - An absolute path, used directly without searching
    * - ``>=3.11,<3.13``
-     - Any Python in the 3.11--3.12 range (:pep:`440` syntax)
+     - Any Python in the 3.11--3.12 range
+       (`version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_ syntax)
 
 See the :doc:`full spec reference </explanation>` for all options.