✨ feat(discovery): add iter_interpreters for enumeration

[gaborbernat]

Closes #65.

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 os.path.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.

flowchart TD
    Call(["iter_interpreters(key)"]) --> Mode{key given?}
    Mode -->|"key=None"| Wide["wide mode<br>cpython, pypy, graalpy<br>filenames on PATH and uv"]
    Mode -->|"key='3.12'"| Narrow["narrow mode<br>only python* on PATH<br>(matches get_interpreter)"]

    Wide --> Walk[walk candidate sources]
    Narrow --> Walk

    Walk --> S1["try_first_with"]
    Walk --> S2["running interpreter"]
    Walk --> S3["Windows registry"]
    Walk --> S4["PATH (left to right)"]
    Walk --> S5["uv installs<br>per-OS layout"]

    S1 --> Pipe[per-candidate filters]
    S2 --> Pipe
    S3 --> Pipe
    S4 --> Pipe
    S5 --> Pipe

    Pipe --> D1[realpath dedup]
    D1 --> D2[satisfies spec]
    D2 --> D3[predicate]
    D3 --> Out([yield PythonInfo])

    style Call fill:#4a90d9,stroke:#2a5f8f,color:#fff
    style Mode fill:#d9904a,stroke:#8f5f2a,color:#fff
    style Wide fill:#9f4ad9,stroke:#5f2a8f,color:#fff
    style Narrow fill:#4a90d9,stroke:#2a5f8f,color:#fff
    style Walk fill:#3a7fc2,stroke:#1f4d7a,color:#fff
    style S1 fill:#3a7fc2,stroke:#1f4d7a,color:#fff
    style S2 fill:#3a7fc2,stroke:#1f4d7a,color:#fff
    style S3 fill:#3a7fc2,stroke:#1f4d7a,color:#fff
    style S4 fill:#3a7fc2,stroke:#1f4d7a,color:#fff
    style S5 fill:#3a7fc2,stroke:#1f4d7a,color:#fff
    style Pipe fill:#c2873a,stroke:#7a4c1f,color:#fff
    style D1 fill:#c2873a,stroke:#7a4c1f,color:#fff
    style D2 fill:#c2873a,stroke:#7a4c1f,color:#fff
    style D3 fill:#c2873a,stroke:#7a4c1f,color:#fff
    style Out fill:#4a9f4a,stroke:#2a6f2a,color:#fff

Loading

iter_interpreters yields every match in discovery order (try_first_with first, then the running interpreter, then the Windows registry, then PATH left-to-right, then UV-managed installs). ✨ Results are deduplicated by the resolved real path of system_executable so symlinked aliases collapse to a single entry, which is the "one yield per distinct install" semantic callers building choosers or version-range pickers usually want. With no spec it broadens the PATH and uv-install regex to every name in the new KNOWN_IMPLEMENTATIONS constant (python, cpython, pypy, graalpy), because an "all interpreters" call that quietly drops PyPy and GraalPy would just shift the gotcha somewhere else.

get_interpreter's narrow regex stays as it was: when no implementation is in the spec, only python* filenames match on PATH. 🛡️ Tools like virtualenv and tox have always read "no implementation in the spec" as "give me CPython" and changing that would be a behaviour shift across every existing caller. The wide-mode regex is opt-in through iter_interpreters only.

While auditing the uv-install glob to extend it for non-CPython, I noticed the existing */bin/python pattern silently finds nothing on Windows, where uv puts python.exe directly under the install root and PyPy at pypy<M>.<N>.exe. 🐛 GraalPy is the lone exception that keeps bin/graalpy.exe on every OS. The new pattern list reflects uv's actual cross-platform layout (sourced from crates/uv-python/src/managed.rs) and is included here as a bugfix changelog entry.

flowchart LR
    Caller(["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 Caller 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

Loading

The Diátaxis documentation gains coverage in all four quadrants — tutorial, how-to, reference, and explanation — describing iteration order, dedup model, when wide-mode kicks in, and the per-OS uv install layout.