♻️ refactor: remove Discover ABC and Builtin class

The Discover ABC existed for virtualenv's plugin system, which is
not relevant to py-discovery as a standalone library. Builtin was the
only concrete subclass and added no value over get_interpreter().

Folded multi-spec support into get_interpreter() (accepts str or
list[str]) and removed both classes. Renamed _builtin.py to
_discovery.py to reflect the new function-only module.

Author: gaborbernat

docs/explanation.rst

@@ -4,13 +4,13 @@ How it works
 Where does py-discovery look?
 -------------------------------
 
-When you call :class:`~py_discovery.Builtin` ``.run()``, the library checks several locations in
+When you call :func:`~py_discovery.get_interpreter`, the library checks several locations in
 order. It stops as soon as it finds an interpreter that matches your spec.
 
 .. mermaid::
 
     flowchart TD
-        Start["Builtin.run()"] --> AbsPath{"Is spec an<br>absolute path?"}
+        Start["get_interpreter()"] --> AbsPath{"Is spec an<br>absolute path?"}
         AbsPath -->|Yes| TryAbs["Use path directly"]
         AbsPath -->|No| TryFirst["try_first_with paths"]
         TryFirst --> RelPath{"Is spec a<br>relative path?"}

docs/how-to/standalone-usage.rst

@@ -25,22 +25,22 @@ shell. You can override these to control exactly where the library looks.
 .. mermaid::
 
     flowchart TD
-        Env["Custom env dict"] --> Builtin["Builtin(spec, env=env)"]
-        Builtin --> PATH["PATH"]
-        Builtin --> Pyenv["PYENV_ROOT"]
-        Builtin --> UV["UV_PYTHON_INSTALL_DIR"]
-        Builtin --> Mise["MISE_DATA_DIR"]
+        Env["Custom env dict"] --> Call["get_interpreter(spec, env=env)"]
+        Call --> PATH["PATH"]
+        Call --> Pyenv["PYENV_ROOT"]
+        Call --> UV["UV_PYTHON_INSTALL_DIR"]
+        Call --> Mise["MISE_DATA_DIR"]
 
         style Env fill:#4a90d9,stroke:#2a5f8f,color:#fff
 
 .. code-block:: python
 
    import os
 
-   from py_discovery import Builtin
+   from py_discovery import get_interpreter
 
    env = {**os.environ, "PATH": "/usr/local/bin:/usr/bin"}
-   discover = Builtin(python_spec=["python3.12"], env=env)
+   result = get_interpreter("python3.12", env=env)
 
 Read interpreter metadata
 ---------------------------
@@ -67,10 +67,10 @@ Once you have a :class:`~py_discovery.PythonInfo`, you can inspect everything ab
 
    from pathlib import Path
 
-   from py_discovery import Builtin, DiskCache
+   from py_discovery import DiskCache, get_interpreter
 
    cache = DiskCache(root=Path("~/.cache/py-discovery").expanduser())
-   info = Builtin(python_spec=["python3.12"], cache=cache).run()
+   info = get_interpreter("python3.12", cache=cache)
 
    info.executable           # Resolved path to the binary.
    info.system_executable    # The underlying system interpreter (outside any venv).

docs/index.rst

@@ -12,11 +12,12 @@ repeated lookups are fast.
 
 .. code-block:: python
 
-   from py_discovery import Builtin, DiskCache
    from pathlib import Path
 
+   from py_discovery import DiskCache, get_interpreter
+
    cache = DiskCache(root=Path("~/.cache/py-discovery").expanduser())
-   result = Builtin(python_spec=["python3.12"], cache=cache).run()
+   result = get_interpreter("python3.12", cache=cache)
    if result is not None:
        print(result.executable)       # /usr/bin/python3.12
        print(result.implementation)   # CPython

docs/tutorial/getting-started.rst

@@ -56,14 +56,13 @@ Finding a different interpreter
 --------------------------------
 
 Usually you need a *specific* Python version, not the one currently running. Pass a **spec** string
-to :class:`~py_discovery.Builtin` and call ``.run()`` to search your system.
+to :func:`~py_discovery.get_interpreter` to search your system.
 
 .. mermaid::
 
     flowchart TD
-        Spec["Spec: python3.12"] --> Builtin["Builtin(python_spec, cache)"]
-        Builtin --> Run[".run()"]
-        Run --> Found{"Match found?"}
+        Spec["Spec: python3.12"] --> Call["get_interpreter(spec, cache)"]
+        Call --> Found{"Match found?"}
         Found -->|Yes| Info["PythonInfo with full metadata"]
         Found -->|No| Nil["None"]
 
@@ -75,15 +74,18 @@ to :class:`~py_discovery.Builtin` and call ``.run()`` to search your system.
 
    from pathlib import Path
 
-   from py_discovery import Builtin, DiskCache
+   from py_discovery import DiskCache, get_interpreter
 
    cache = DiskCache(root=Path("~/.cache/py-discovery").expanduser())
-   discover = Builtin(python_spec=["python3.12"], cache=cache)
-   result = discover.run()
+   result = get_interpreter("python3.12", cache=cache)
    if result is not None:
        print(result.executable)
 
-You can pass multiple specs -- the library tries each one in order and returns the first match.
+You can pass multiple specs as a list -- the library tries each one in order and returns the first match.
+
+.. code-block:: python
+
+   result = get_interpreter(["python3.12", "python3.11"], cache=cache)
 
 Writing specs
 -------------
@@ -173,6 +175,6 @@ Every call will run a subprocess to query the interpreter, so this is slower for
 
 .. code-block:: python
 
-   from py_discovery import Builtin
+   from py_discovery import get_interpreter
 
-   result = Builtin(python_spec=["python3.12"], cache=None).run()
+   result = get_interpreter("python3.12")

pyproject.toml

@@ -63,7 +63,6 @@ urls.Source = "https://github.com/tox-dev/py-discovery"
 urls.Tracker = "https://github.com/tox-dev/py-discovery/issues"
 
 [tool.hatch]
-build.hooks.vcs.version-file = "src/py_discovery/_version.py"
 version.source = "vcs"
 
 [tool.ruff]

src/py_discovery/__init__.py

@@ -2,17 +2,16 @@
 
 from __future__ import annotations
 
-from ._builtin import Builtin, get_interpreter
+from importlib.metadata import version
 from ._cache import ContentStore, DiskCache, PyInfoCache
-from ._discover import Discover
+from ._discovery import get_interpreter
 from ._py_info import PythonInfo
 from ._py_spec import PythonSpec
-from ._version import __version__
 
+
+__version__ = version("py-discovery")
 __all__ = [
-    "Builtin",
     "ContentStore",
-    "Discover",
     "DiskCache",
     "PyInfoCache",
     "PythonInfo",

src/py_discovery/_compat.py

@@ -9,7 +9,6 @@
 import tempfile
 
 IS_WIN = sys.platform == "win32"
-
 LOGGER = logging.getLogger(__name__)
 
 

src/py_discovery/_discover.py

@@ -10,7 +10,6 @@
 from platformdirs import user_data_path
 
 from ._compat import IS_WIN, fs_path_id
-from ._discover import Discover
 from ._py_info import PythonInfo
 from ._py_spec import PythonSpec
 
@@ -22,53 +21,40 @@
 LOGGER = logging.getLogger(__name__)
 
 
-class Builtin(Discover):
-    python_spec: Sequence[str]
-    cache: PyInfoCache | None
-    try_first_with: Sequence[str]
-
-    def __init__(
-        self,
-        python_spec: Sequence[str] | None = None,
-        cache: PyInfoCache | None = None,
-        try_first_with: Sequence[str] | None = None,
-        env: Mapping[str, str] | None = None,
-    ) -> None:
-        super().__init__(env=env)
-        self.python_spec = python_spec or [sys.executable]
-        self.cache = cache
-        self.try_first_with = try_first_with or []
-
-    def run(self) -> PythonInfo | None:
-        for python_spec in self.python_spec:
-            result = get_interpreter(python_spec, self.try_first_with, self.cache, self._env)
-            if result is not None:
-                return result
-        return None
-
-    def __repr__(self) -> str:
-        spec = self.python_spec[0] if len(self.python_spec) == 1 else self.python_spec
-        return f"{self.__class__.__name__} discover of python_spec={spec!r}"
+def get_interpreter(
+    key: str | Sequence[str],
+    try_first_with: Iterable[str] | None = None,
+    cache: PyInfoCache | None = None,
+    env: Mapping[str, str] | None = None,
+) -> PythonInfo | None:
+    specs = [key] if isinstance(key, str) else key
+    for spec_str in specs:
+        if result := _find_interpreter(spec_str, try_first_with or (), cache, env):
+            return result
+    return None
 
 
-def get_interpreter(
-    key, try_first_with: Iterable[str], cache: PyInfoCache | None = None, env: Mapping[str, str] | None = None
+def _find_interpreter(
+    key: str,
+    try_first_with: Iterable[str],
+    cache: PyInfoCache | None = None,
+    env: Mapping[str, str] | None = None,
 ) -> PythonInfo | None:
     spec = PythonSpec.from_string_spec(key)
     LOGGER.info("find interpreter for spec %r", spec)
-    proposed_paths = set()
+    proposed_paths: set[tuple[str, bool]] = set()
     env = os.environ if env is None else env
     for interpreter, impl_must_match in propose_interpreters(spec, try_first_with, cache, env):
         if interpreter is None:  # pragma: no cover
             continue
-        key = interpreter.system_executable, impl_must_match
-        if key in proposed_paths:
+        proposed_key = interpreter.system_executable, impl_must_match
+        if proposed_key in proposed_paths:
             continue
         LOGGER.info("proposed %s", interpreter)
         if interpreter.satisfies(spec, impl_must_match):
             LOGGER.debug("accepted %s", interpreter)
             return interpreter
-        proposed_paths.add(key)
+        proposed_paths.add(proposed_key)
     return None
 
 
@@ -292,7 +278,6 @@ class PathPythonInfo(PythonInfo):
 
 
 __all__ = [
-    "Builtin",
     "LazyPathDump",
     "PathPythonInfo",
     "get_interpreter",