✨ feat(discovery): add predicate param to get_interpreter

Hatch monkeypatches `propose_interpreters` to filter out incompatible
interpreters, which broke when virtualenv moved discovery to this
package. Adding a `predicate` callback gives downstream tools a public
API to filter interpreters without monkeypatching internals.

Named `predicate` instead of `filter` to avoid shadowing the Python
builtin (ruff A002).

Closes #30

Author: gaborbernat

src/python_discovery/_discovery.py

@@ -27,10 +27,26 @@ def get_interpreter(
     try_first_with: Iterable[str] | None = None,
     cache: PyInfoCache | None = None,
     env: Mapping[str, str] | None = None,
+    predicate: Callable[[PythonInfo], bool] | None = None,
 ) -> PythonInfo | None:
+    """
+    Find a Python interpreter matching *key*.
+
+    Iterates over one or more specification strings and returns the first interpreter that satisfies the spec and passes
+    the optional *predicate*.
+
+    :param key: interpreter specification string(s) — an absolute path, a version (``3.12``), an implementation prefix
+        (``cpython3.12``), or a PEP 440 specifier (``>=3.10``). When a sequence is given each entry is tried in order.
+    :param try_first_with: executables to probe before the normal discovery 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 predicate: optional callback applied after an interpreter matches the spec. Return ``True`` to accept the
+        interpreter, ``False`` to skip it and continue searching.
+    :return: the first matching interpreter, or ``None`` if no match is found.
+    """
     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):
+        if result := _find_interpreter(spec_str, try_first_with or (), cache, env, predicate):
             return result
     return None
 
@@ -40,6 +56,7 @@ def _find_interpreter(
     try_first_with: Iterable[str],
     cache: PyInfoCache | None = None,
     env: Mapping[str, str] | None = None,
+    predicate: Callable[[PythonInfo], bool] | None = None,
 ) -> PythonInfo | None:
     spec = PythonSpec.from_string_spec(key)
     _LOGGER.info("find interpreter for spec %r", spec)
@@ -52,7 +69,9 @@ def _find_interpreter(
         if proposed_key in proposed_paths:
             continue
         _LOGGER.info("proposed %s", interpreter)
-        if interpreter.satisfies(spec, impl_must_match=impl_must_match):
+        if interpreter.satisfies(spec, impl_must_match=impl_must_match) and (
+            predicate is None or predicate(interpreter)
+        ):
             _LOGGER.debug("accepted %s", interpreter)
             return interpreter
         proposed_paths.add(proposed_key)
@@ -88,6 +107,14 @@ def propose_interpreters(
     cache: PyInfoCache | None = None,
     env: Mapping[str, str] | None = None,
 ) -> Generator[tuple[PythonInfo | None, bool], None, None]:
+    """
+    Yield ``(interpreter, impl_must_match)`` candidates for *spec*.
+
+    :param spec: the parsed interpreter specification to match against.
+    :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`.
+    """
     env = os.environ if env is None else env
     tested_exes: set[str] = set()
     if spec.is_abs and spec.path is not None:

tests/test_discovery.py

@@ -409,3 +409,38 @@ def test_shim_colon_separated_pyenv_version_picks_first_match(
         mock_from_exe.return_value = None
         get_interpreter("python2.7", [])
         assert mock_from_exe.call_args_list[0][0][0] == str(second_binary)
+
+
+def test_predicate_filters_interpreters(session_cache: DiskCache) -> None:
+    result = get_interpreter(sys.executable, [], session_cache, predicate=lambda _: False)
+    assert result is None
+
+
+def test_predicate_accepts_interpreter(session_cache: DiskCache) -> None:
+    result = get_interpreter(sys.executable, [], session_cache, predicate=lambda _: True)
+    assert result is not None
+    assert result.executable == sys.executable
+
+
+def test_predicate_none_is_noop(session_cache: DiskCache) -> None:
+    result = get_interpreter(sys.executable, [], session_cache, predicate=None)
+    assert result is not None
+    assert result.executable == sys.executable
+
+
+def test_predicate_with_fallback_specs(session_cache: DiskCache) -> None:
+    current = PythonInfo.current_system(session_cache)
+    major, minor = current.version_info.major, current.version_info.minor
+    accepted_exe: str | None = None
+
+    def reject_first(info: PythonInfo) -> bool:
+        nonlocal accepted_exe
+        if accepted_exe is None:
+            accepted_exe = str(info.executable)
+            return False
+        return True
+
+    result = get_interpreter([f"{major}.{minor}", sys.executable], [], session_cache, predicate=reject_first)
+    assert accepted_exe is not None
+    assert result is not None
+    assert str(result.executable) != accepted_exe