python-discovery 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

python_discovery/__init__.py

@@ -5,15 +5,16 @@ from __future__ import annotations
 from importlib.metadata import version
 
 from ._cache import ContentStore, DiskCache, PyInfoCache
-from ._discovery import get_interpreter
-from ._py_info import KNOWN_ARCHITECTURES, PythonInfo
-from ._py_spec import PythonSpec
+from ._discovery import get_interpreter, iter_interpreters
+from ._py_info import KNOWN_ARCHITECTURES, PythonInfo, normalize_isa
+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,4 +25,6 @@ __all__ = [
     "SimpleVersion",
     "__version__",
     "get_interpreter",
+    "iter_interpreters",
+    "normalize_isa",
 ]

python_discovery/_discovery.py

@@ -14,7 +14,7 @@ from ._py_info import PythonInfo
 from ._py_spec import 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
 
@@ -36,7 +36,9 @@ def get_interpreter(
     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.
+        (``cpython3.12``), or a
+        `version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_
+        (``>=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`.
@@ -51,6 +53,73 @@ 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.
+    """
+    if key is None:
+        keys: tuple[str | None, ...] = (None,)
+    elif isinstance(key, str):
+        keys = (key,)
+    else:
+        keys = tuple(key)
+    first_with = tuple(try_first_with or ())
+    env_map = os.environ if env is None else env
+    seen: set[str] = set()
+    for spec_str in keys:
+        yield from _iter_for_spec(spec_str, first_with, cache, env_map, predicate, seen)
+
+
+def _iter_for_spec(  # noqa: PLR0913, PLR0917
+    spec_str: str | None,
+    try_first_with: tuple[str, ...],
+    cache: PyInfoCache | None,
+    env: Mapping[str, str],
+    predicate: Callable[[PythonInfo], bool] | None,
+    seen: set[str],
+) -> Iterator[PythonInfo]:
+    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_with, cache, env, all_implementations=wide
+    ):
+        if interpreter is None:
+            continue
+        if (anchor := interpreter.system_executable or interpreter.executable) is None:
+            continue
+        if (real_path := os.path.realpath(anchor)) in seen:
+            continue
+        if not interpreter.satisfies(spec, impl_must_match=impl_must_match):
+            continue
+        if predicate is not None and not predicate(interpreter):
+            continue
+        seen.add(real_path)
+        yield interpreter
+
+
 def _find_interpreter(
     key: str,
     try_first_with: Iterable[str],
@@ -106,6 +175,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 +185,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 +198,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 +243,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 +264,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 +274,18 @@ 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", "*/python.exe"]
+    if all_implementations:
+        patterns.extend(("*/bin/pypy*", "*/bin/graalpy", "*/pypy*.exe", "*/bin/graalpy.exe"))
+    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)
+            if interpreter := PathPythonInfo.from_exe(str(exe_path), cache, raise_on_error=False, env=env):
+                yield interpreter, True
 
 
 def get_paths(env: Mapping[str, str]) -> Generator[Path, None, None]:
@@ -244,9 +329,11 @@ class LazyPathDump:
         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 +418,6 @@ __all__ = [
     "PathPythonInfo",
     "get_interpreter",
     "get_paths",
+    "iter_interpreters",
     "propose_interpreters",
 ]

python_discovery/_py_info.py

@@ -770,21 +770,43 @@ class PythonInfo:  # noqa: PLR0904
 
 KNOWN_ARCHITECTURES: frozenset[str] = frozenset({
     "arm64",
-    "i686",
     "loongarch64",
+    "ppc",
     "ppc64",
     "ppc64le",
     "riscv64",
     "s390x",
+    "sparc64",
     "x86",
     "x86_64",
 })
-"""Known CPU architecture (ISA) values after normalization."""
+"""Known CPU architecture (ISA) values after normalization.
+
+.. deprecated::
+    Use :func:`normalize_isa` instead, which handles both known and unknown architectures.
+"""
 
 
 def normalize_isa(isa: str) -> str:
+    """
+    Normalize an ISA (instruction set architecture) string to a canonical form.
+
+    Known aliases are mapped (e.g. ``amd64`` → ``x86_64``, ``aarch64`` → ``arm64``).
+    Unrecognized values are lowercased and returned as-is.
+    """
     low = isa.lower()
-    return {"amd64": "x86_64", "aarch64": "arm64", "i386": "x86", "i586": "x86"}.get(low, low)
+    return {
+        "amd64": "x86_64",
+        "aarch64": "arm64",
+        "i386": "x86",
+        "i486": "x86",
+        "i586": "x86",
+        "i686": "x86",
+        "powerpc": "ppc",
+        "powerpc64": "ppc64",
+        "powerpc64le": "ppc64le",
+        "sparcv9": "sparc64",
+    }.get(low, low)
 
 
 def _main() -> None:  # pragma: no cover

python_discovery/_py_spec.py

@@ -35,6 +35,8 @@ SPECIFIER_PATTERN = re.compile(
 _MAX_VERSION_PARTS: Final[int] = 3
 _SINGLE_DIGIT_MAX: Final[int] = 9
 
+KNOWN_IMPLEMENTATIONS: Final[tuple[str, ...]] = ("python", "cpython", "pypy", "graalpy")
+
 SpecifierSet = SimpleSpecifierSet
 Version = SimpleVersion
 InvalidSpecifier = ValueError
@@ -111,7 +113,9 @@ class PythonSpec:
     :param path: filesystem path to a specific interpreter, or ``None``.
     :param free_threaded: whether a free-threaded build is required, or ``None`` for any.
     :param machine: required ISA (e.g. ``"arm64"``), or ``None`` for any.
-    :param version_specifier: PEP 440 version constraints, or ``None``.
+    :param version_specifier:
+        `version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_
+        constraints, or ``None``.
     """
 
     def __init__(  # noqa: PLR0913, PLR0917
@@ -145,7 +149,7 @@ class PythonSpec:
         Parse a string specification into a :class:`PythonSpec`.
 
         :param string_spec: an interpreter spec — an absolute path, a version string, an implementation prefix,
-            or a PEP 440 specifier.
+            or a `version specifier <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_.
         """
         if pathlib.Path(string_spec).is_absolute():
             return cls(string_spec, None, None, None, None, None, string_spec)
@@ -155,16 +159,23 @@ class PythonSpec:
             return result
         return cls(string_spec, None, None, None, None, None, string_spec)
 
-    def generate_re(self, *, windows: bool) -> re.Pattern:
+    def generate_re(self, *, windows: bool, all_implementations: bool = False) -> re.Pattern:
         """
         Generate a regular expression for matching interpreter filenames.
 
         :param windows: if ``True``, require a ``.exe`` suffix.
+        :param all_implementations: when ``True`` and the spec does not constrain the implementation, match every
+            filename in :data:`KNOWN_IMPLEMENTATIONS` instead of only ``python``. Used by enumeration APIs.
         """
         version = r"{}(\.{}(\.{})?)?".format(
             *(r"\d+" if v is None else v for v in (self.major, self.minor, self.micro)),
         )
-        impl = "python" if self.implementation is None else f"python|{re.escape(self.implementation)}"
+        if self.implementation is not None:
+            impl = f"python|{re.escape(self.implementation)}"
+        elif all_implementations:
+            impl = "|".join(re.escape(i) for i in KNOWN_IMPLEMENTATIONS)
+        else:
+            impl = "python"
         mod = "t?" if self.free_threaded else ""
         suffix = r"\.exe" if windows else ""
         version_conditional = "?" if windows or self.major is None else ""
@@ -254,6 +265,7 @@ class PythonSpec:
 
 
 __all__ = [
+    "KNOWN_IMPLEMENTATIONS",
     "InvalidSpecifier",
     "InvalidVersion",
     "PythonSpec",

{python_discovery-1.2.1.dist-info → python_discovery-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-discovery
-Version: 1.2.1
+Version: 1.3.0
 Summary: Python interpreter discovery
 Project-URL: Changelog, https://github.com/tox-dev/python-discovery/releases
 Project-URL: Documentation, https://python-discovery.readthedocs.io
@@ -99,7 +99,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.1.dist-info → python_discovery-1.3.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
-python_discovery/__init__.py,sha256=_-cpcN1ZKP1uRuQDpxsSbiqd036yyMOAJXe13PzVyqc,676
+python_discovery/__init__.py,sha256=Hi4j3pMvC8Fo8KoNL-wOHsPSCUHwY4c0qvv5sjnFzME,808
 python_discovery/_cache.py,sha256=bG4fD-h2pdPmb4v9BldbXmJ5Tlt1boiH1Qrz8kp9Dds,5063
 python_discovery/_cached_py_info.py,sha256=1AFEoc_-OaCi1PXmaFz9Iy_bEuqOhJdFSDFHljzD-EE,8540
 python_discovery/_compat.py,sha256=iqxGuhK9rPaiui80G1H1KrweoMJ16gyLYEmUrSXrp5c,709
-python_discovery/_discovery.py,sha256=yccO7GNtNuxHtmDHsyqtaASmNHFgKIeEX6Me3jX-GFs,12822
-python_discovery/_py_info.py,sha256=-b47WzGdzVlBr7xQxavrKKjmUpIJ2RSV7wfwxkXKi5I,33873
-python_discovery/_py_spec.py,sha256=rhm9uahWSQL3JLyyMmM2HQVhrTMVnHnZEAhArkjeNtM,9601
+python_discovery/_discovery.py,sha256=tlcmGDsOL8zitSSQSws9cXYt6MKT6ENiVtfAjQBzBtw,16820
+python_discovery/_py_info.py,sha256=MLDQJbqamOdVev9_OH1b-DcQqTJR0h3RA3dHyB-bAgM,34446
+python_discovery/_py_spec.py,sha256=rmABAbCh0oZ48uLT-2TfOj8GDQu5rmNBIa5dq5vaNCc,10305
 python_discovery/_specifier.py,sha256=PTh6suNTC0hMnFSxFYF_vggdciFLnwxoh1YflSbgCXA,10368
 python_discovery/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 python_discovery/_windows/__init__.py,sha256=qthcyGh36b3WkeSbZ4ECRRYLbCOCaQu5X_DRZ98tXfk,315
 python_discovery/_windows/_pep514.py,sha256=JYSQ5tOYbSMOKtVVfOEkyYskBhEoTsImNr3DJcv7XNE,7658
 python_discovery/_windows/_propose.py,sha256=iMJf6l0TU4SvuV8UsCHHINAe9L5dUT949xyeyMVdong,1565
-python_discovery-1.2.1.dist-info/METADATA,sha256=IakgM5Ss1sLajW-_p4TQRscNlvVmB2oP_X0mdUvDD-M,5404
-python_discovery-1.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-python_discovery-1.2.1.dist-info/licenses/LICENSE,sha256=kOJeH68qSq6o2V7o5_VziwUqGswMnFgGgQH5Mahr1Yg,1023
-python_discovery-1.2.1.dist-info/RECORD,,
+python_discovery-1.3.0.dist-info/METADATA,sha256=0an9XeuI3H011i75sO0571tS0rmyOG28Q66WajKbIJQ,5483
+python_discovery-1.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_discovery-1.3.0.dist-info/licenses/LICENSE,sha256=kOJeH68qSq6o2V7o5_VziwUqGswMnFgGgQH5Mahr1Yg,1023
+python_discovery-1.3.0.dist-info/RECORD,,