✨ feat(discovery): add iter_interpreters for enumeration

Callers wanting every interpreter on the system, rather than the first match,
had to abuse get_interpreter's predicate as a side-channel: return False for
every candidate so the search never stops, accumulate into a dict keyed by
realpath. The workaround missed any interpreter whose binary on PATH is named
pypy or graalpy, and surfaced /bin/python and /usr/bin/python as separate
entries even though they resolve to the same file.

iter_interpreters yields every match in discovery order, deduplicated by the
resolved real path of system_executable so symlinked aliases and venvs that
symlink to a base interpreter collapse to a single entry. With no spec it
broadens the PATH and uv-install regex to every name in KNOWN_IMPLEMENTATIONS,
because an "all interpreters" call that quietly drops PyPy and GraalPy would
just shift the gotcha. get_interpreter's narrow regex stays as it was so tools
that have always read "no implementation in the spec" as "give me CPython"
keep that behaviour.

Closes #65.

Author: gaborbernat

docs/changelog/65.feature.rst

@@ -0,0 +1,3 @@
+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`
+- by :user:`gaborbernat`.

docs/explanation.rst

@@ -65,6 +65,45 @@ 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.
 
+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 behaviour 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
 -------------------
 

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
 ---------------------------
 

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
 -------------
 

src/python_discovery/__init__.py

@@ -5,15 +5,16 @@
 from importlib.metadata import version
 
 from ._cache import ContentStore, DiskCache, PyInfoCache
-from ._discovery import get_interpreter
+from ._discovery import get_interpreter, iter_interpreters
 from ._py_info import KNOWN_ARCHITECTURES, PythonInfo, normalize_isa
-from ._py_spec import PythonSpec
+from ._py_spec import KNOWN_IMPLEMENTATIONS, PythonSpec
 from ._specifier import SimpleSpecifier, SimpleSpecifierSet, SimpleVersion
 
 __version__ = version("python-discovery")
 
 __all__ = [
     "KNOWN_ARCHITECTURES",
+    "KNOWN_IMPLEMENTATIONS",
     "ContentStore",
     "DiskCache",
     "PyInfoCache",
@@ -24,5 +25,6 @@
     "SimpleVersion",
     "__version__",
     "get_interpreter",
+    "iter_interpreters",
     "normalize_isa",
 ]

src/python_discovery/_discovery.py

@@ -11,10 +11,10 @@
 
 from ._compat import fs_path_id
 from ._py_info import PythonInfo
-from ._py_spec import PythonSpec
+from ._py_spec import KNOWN_IMPLEMENTATIONS, PythonSpec
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Generator, Iterable, Mapping, Sequence
+    from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence
 
     from ._cache import PyInfoCache
 
@@ -51,6 +51,64 @@ def get_interpreter(
     return None
 
 
+def iter_interpreters(
+    key: str | Sequence[str] | None = None,
+    try_first_with: Iterable[str] | None = None,
+    cache: PyInfoCache | None = None,
+    env: Mapping[str, str] | None = None,
+    predicate: Callable[[PythonInfo], bool] | None = None,
+) -> Iterator[PythonInfo]:
+    """
+    Yield every interpreter on the system that satisfies *key*.
+
+    Iteration order is discovery order: ``try_first_with`` paths first, then the running interpreter, then ``PATH``
+    (left to right), then UV-managed installs. Results are deduplicated by the resolved real path of the underlying
+    system interpreter, so symlinked aliases (``/bin`` vs ``/usr/bin``) and venvs that symlink to a base interpreter
+    collapse to a single entry. Callers that want a different ordering should sort the result.
+
+    :param key: interpreter specification — same syntax as :func:`get_interpreter`. ``None`` enumerates every Python
+        implementation python-discovery knows about (see :data:`KNOWN_IMPLEMENTATIONS`).
+    :param try_first_with: executables to probe before the normal discovery search.
+    :param cache: interpreter metadata cache; when ``None`` results are not cached. Strongly recommended for
+        enumeration, which interrogates every candidate as a subprocess on a cold cache.
+    :param env: environment mapping for ``PATH`` lookup; defaults to :data:`os.environ`.
+    :param predicate: optional filter applied after the spec match; return ``True`` to include the interpreter.
+    """
+    env_map = os.environ if env is None else env
+    try_first_tuple = tuple(try_first_with or ())
+    if key is None:
+        keys: tuple[str | None, ...] = (None,)
+    elif isinstance(key, str):
+        keys = (key,)
+    else:
+        keys = tuple(key)
+    seen_real_paths: set[str] = set()
+    for spec_str in keys:
+        if spec_str is None:
+            spec = PythonSpec("", None, None, None, None, None, None)
+            wide = True
+        else:
+            spec = PythonSpec.from_string_spec(spec_str)
+            wide = False
+        for interpreter, impl_must_match in propose_interpreters(
+            spec, try_first_tuple, cache, env_map, all_implementations=wide
+        ):
+            if interpreter is None:
+                continue
+            anchor = interpreter.system_executable or interpreter.executable
+            if anchor is None:
+                continue
+            real_path = os.path.realpath(anchor)
+            if real_path in seen_real_paths:
+                continue
+            if not interpreter.satisfies(spec, impl_must_match=impl_must_match):
+                continue
+            if predicate is not None and not predicate(interpreter):
+                continue
+            seen_real_paths.add(real_path)
+            yield interpreter
+
+
 def _find_interpreter(
     key: str,
     try_first_with: Iterable[str],
@@ -106,6 +164,8 @@ def propose_interpreters(
     try_first_with: Iterable[str],
     cache: PyInfoCache | None = None,
     env: Mapping[str, str] | None = None,
+    *,
+    all_implementations: bool = False,
 ) -> Generator[tuple[PythonInfo | None, bool], None, None]:
     """
     Yield ``(interpreter, impl_must_match)`` candidates for *spec*.
@@ -114,6 +174,8 @@ def propose_interpreters(
     :param try_first_with: executable paths to probe before the standard search.
     :param cache: interpreter metadata cache; when ``None`` results are not cached.
     :param env: environment mapping for ``PATH`` lookup; defaults to :data:`os.environ`.
+    :param all_implementations: when ``True`` and *spec* does not constrain the implementation, also surface
+        non-CPython binaries on ``PATH`` and under UV's install directory. Used by enumeration APIs.
     """
     env = os.environ if env is None else env
     tested_exes: set[str] = set()
@@ -125,8 +187,8 @@ def propose_interpreters(
     yield from _propose_explicit(spec, try_first_with, cache, env, tested_exes)
     if spec.path is not None and spec.is_abs:  # pragma: no cover # relative spec.path is never abs
         return
-    yield from _propose_from_path(spec, cache, env, tested_exes)
-    yield from _propose_from_uv(cache, env)
+    yield from _propose_from_path(spec, cache, env, tested_exes, all_implementations=all_implementations)
+    yield from _propose_from_uv(cache, env, all_implementations=all_implementations)
 
 
 def _propose_explicit(
@@ -170,8 +232,10 @@ def _propose_from_path(
     cache: PyInfoCache | None,
     env: Mapping[str, str],
     tested_exes: set[str],
+    *,
+    all_implementations: bool = False,
 ) -> Generator[tuple[PythonInfo | None, bool], None, None]:
-    find_candidates = path_exe_finder(spec)
+    find_candidates = path_exe_finder(spec, all_implementations=all_implementations)
     for pos, path in enumerate(get_paths(env)):
         _LOGGER.debug(LazyPathDump(pos, path, env))
         for exe, impl_must_match in find_candidates(path):
@@ -189,6 +253,8 @@ def _propose_from_path(
 def _propose_from_uv(
     cache: PyInfoCache | None,
     env: Mapping[str, str],
+    *,
+    all_implementations: bool = False,
 ) -> Generator[tuple[PythonInfo | None, bool], None, None]:
     if uv_python_dir := os.getenv("UV_PYTHON_INSTALL_DIR"):
         uv_python_path = Path(uv_python_dir).expanduser()
@@ -197,10 +263,19 @@ def _propose_from_uv(
     else:
         uv_python_path = user_data_path("uv") / "python"
 
-    for exe_path in uv_python_path.glob("*/bin/python"):  # pragma: no branch
-        interpreter = PathPythonInfo.from_exe(str(exe_path), cache, raise_on_error=False, env=env)
-        if interpreter is not None:  # pragma: no branch
-            yield interpreter, True
+    patterns: list[str] = ["*/bin/python"]
+    if all_implementations:
+        patterns.extend(f"*/bin/{impl}" for impl in KNOWN_IMPLEMENTATIONS if impl != "python")
+    seen_uv_paths: set[str] = set()
+    for pattern in patterns:
+        for exe_path in uv_python_path.glob(pattern):
+            resolved = str(Path(exe_path).resolve())
+            if resolved in seen_uv_paths:
+                continue
+            seen_uv_paths.add(resolved)
+            interpreter = PathPythonInfo.from_exe(str(exe_path), cache, raise_on_error=False, env=env)
+            if interpreter is not None:  # pragma: no branch
+                yield interpreter, True
 
 
 def get_paths(env: Mapping[str, str]) -> Generator[Path, None, None]:
@@ -244,9 +319,11 @@ def __repr__(self) -> str:
         return content
 
 
-def path_exe_finder(spec: PythonSpec) -> Callable[[Path], Generator[tuple[Path, bool], None, None]]:
+def path_exe_finder(
+    spec: PythonSpec, *, all_implementations: bool = False
+) -> Callable[[Path], Generator[tuple[Path, bool], None, None]]:
     """Given a spec, return a function that can be called on a path to find all matching files in it."""
-    pat = spec.generate_re(windows=sys.platform == "win32")
+    pat = spec.generate_re(windows=sys.platform == "win32", all_implementations=all_implementations)
     direct = spec.str_spec
     if sys.platform == "win32":  # pragma: win32 cover
         direct = f"{direct}.exe"
@@ -331,5 +408,6 @@ class PathPythonInfo(PythonInfo):
     "PathPythonInfo",
     "get_interpreter",
     "get_paths",
+    "iter_interpreters",
     "propose_interpreters",
 ]