python-discovery 1.0.0__tar.gz → 1.1.1__tar.gz

python_discovery-1.1.1/.github/FUNDING.yaml

@@ -0,0 +1 @@
+github: gaborbernat

python_discovery-1.1.1/.github/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest released version is supported with security updates. Older versions will not receive patches.
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities via [GitHub's private vulnerability reporting](../../security/advisories/new).

python_discovery-1.1.1/.github/release.yaml

@@ -0,0 +1,5 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot[bot]
+      - pre-commit-ci[bot]

{python_discovery-1.0.0 → python_discovery-1.1.1}/.github/workflows/check.yaml

@@ -12,6 +12,9 @@ concurrency:
   group: check-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest

{python_discovery-1.0.0 → python_discovery-1.1.1}/.github/workflows/release.yaml

@@ -3,6 +3,9 @@ on:
   push:
     tags: ["*"]
 
+permissions:
+  contents: read
+
 env:
   dists-artifact-name: python-package-distributions
 
@@ -22,7 +25,7 @@ jobs:
       - name: Build package
         run: uv build --python 3.14 --python-preference only-managed --sdist --wheel . --out-dir dist
       - name: Store the distribution packages
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ env.dists-artifact-name }}
           path: dist/*
@@ -38,7 +41,7 @@ jobs:
       id-token: write
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: ${{ env.dists-artifact-name }}
           path: dist/

{python_discovery-1.0.0 → python_discovery-1.1.1}/.pre-commit-config.yaml

@@ -5,7 +5,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.36.1
+    rev: 0.37.0
     hooks:
       - id: check-github-workflows
         args: ["--verbose"]
@@ -15,11 +15,11 @@ repos:
       - id: codespell
         additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.11.1"
+    rev: "v2.16.2"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.14.14"
+    rev: "v0.15.4"
     hooks:
       - id: ruff-format
       - id: ruff

{python_discovery-1.0.0 → python_discovery-1.1.1}/.readthedocs.yaml

@@ -5,4 +5,4 @@ build:
   commands:
     - curl -LsSf https://astral.sh/uv/install.sh | sh
     - ~/.local/bin/uv tool install tox --with tox-uv -p 3.14 --managed-python
-    - ~/.local/bin/tox run -e docs --
+    - ~/.local/bin/tox run -e docs -- "$READTHEDOCS_OUTPUT/html"

{python_discovery-1.0.0 → python_discovery-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-discovery
-Version: 1.0.0
+Version: 1.1.1
 Summary: Python interpreter discovery
 Project-URL: Changelog, https://github.com/tox-dev/python-discovery/releases
 Project-URL: Documentation, https://python-discovery.readthedocs.io
@@ -67,5 +67,5 @@ Description-Content-Type: text/markdown
 [![Supported Python
 versions](https://img.shields.io/pypi/pyversions/python-discovery.svg)](https://pypi.org/project/python-discovery/)
 [![Downloads](https://static.pepy.tech/badge/python-discovery/month)](https://pepy.tech/project/python-discovery)
-[![check](https://github.com/tox-dev/python-discovery/actions/workflows/check.yml/badge.svg)](https://github.com/tox-dev/python-discovery/actions/workflows/check.yml)
+[![check](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml)
 [![Documentation Status](https://readthedocs.org/projects/python-discovery/badge/?version=latest)](https://python-discovery.readthedocs.io/en/latest/?badge=latest)

{python_discovery-1.0.0 → python_discovery-1.1.1}/README.md

@@ -4,5 +4,5 @@
 [![Supported Python
 versions](https://img.shields.io/pypi/pyversions/python-discovery.svg)](https://pypi.org/project/python-discovery/)
 [![Downloads](https://static.pepy.tech/badge/python-discovery/month)](https://pepy.tech/project/python-discovery)
-[![check](https://github.com/tox-dev/python-discovery/actions/workflows/check.yml/badge.svg)](https://github.com/tox-dev/python-discovery/actions/workflows/check.yml)
+[![check](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml/badge.svg)](https://github.com/tox-dev/python-discovery/actions/workflows/check.yaml)
 [![Documentation Status](https://readthedocs.org/projects/python-discovery/badge/?version=latest)](https://python-discovery.readthedocs.io/en/latest/?badge=latest)

{python_discovery-1.0.0 → python_discovery-1.1.1}/docs/explanation.rst

@@ -2,7 +2,7 @@ How it works
 ============
 
 Where does python-discovery look?
--------------------------------
+---------------------------------
 
 When you call :func:`~python_discovery.get_interpreter`, the library checks several locations in
 order. It stops as soon as it finds an interpreter that matches your spec.

{python_discovery-1.0.0 → python_discovery-1.1.1}/docs/index.rst

@@ -1,5 +1,5 @@
 python-discovery
-============
+================
 
 You may have multiple Python versions installed on your machine -- system Python, versions from
 `pyenv <https://github.com/pyenv/pyenv>`_, `mise <https://mise.jdx.dev/>`_,

{python_discovery-1.0.0 → python_discovery-1.1.1}/pyproject.toml

@@ -129,31 +129,20 @@ count = true
 [tool.pyproject-fmt]
 max_supported_python = "3.14"
 
-[tool.pytest.ini_options]
-markers = [ "graalpy" ]
+[tool.pytest]
+ini_options.markers = [ "graalpy" ]
 
 [tool.coverage]
-run.source = [
-  "python_discovery",
-  "tests",
-]
-run.dynamic_context = "test_function"
 run.branch = true
+run.dynamic_context = "test_function"
 run.parallel = true
 run.plugins = [
   "covdefaults",
 ]
-report.fail_under = 100
-report.show_missing = true
-report.partial_branches = [
-  "assert any\\(",
-]
-report.omit = [
-  "src/python_discovery/_windows/*",
-  "tests/windows/*",
+run.source = [
+  "python_discovery",
+  "tests",
 ]
-html.show_contexts = true
-html.skip_covered = false
 paths.source = [
   "src",
   ".tox*/*/lib/python*/site-packages",
@@ -162,6 +151,17 @@ paths.source = [
   "*/src",
   "*\\src",
 ]
+report.fail_under = 100
+report.omit = [
+  "src/python_discovery/_windows/*",
+  "tests/windows/*",
+]
+report.partial_branches = [
+  "assert any\\(",
+]
+report.show_missing = true
+html.show_contexts = true
+html.skip_covered = false
 
 [tool.ty]
 src.exclude = [ "tests/windows/winreg_mock_values.py" ]

{python_discovery-1.0.0 → python_discovery-1.1.1}/src/python_discovery/__init__.py

@@ -8,6 +8,7 @@ from ._cache import ContentStore, DiskCache, PyInfoCache
 from ._discovery import get_interpreter
 from ._py_info import PythonInfo
 from ._py_spec import PythonSpec
+from ._specifier import SimpleSpecifier, SimpleSpecifierSet, SimpleVersion
 
 __version__ = version("python-discovery")
 
@@ -17,6 +18,9 @@ __all__ = [
     "PyInfoCache",
     "PythonInfo",
     "PythonSpec",
+    "SimpleSpecifier",
+    "SimpleSpecifierSet",
+    "SimpleVersion",
     "__version__",
     "get_interpreter",
 ]

{python_discovery-1.0.0 → python_discovery-1.1.1}/src/python_discovery/_cache.py

@@ -19,25 +19,47 @@ _LOGGER: Final[logging.Logger] = logging.getLogger(__name__)
 class ContentStore(Protocol):
     """A store for reading and writing cached content."""
 
-    def exists(self) -> bool: ...
+    def exists(self) -> bool:
+        """Return whether the cached content exists."""
+        ...
 
-    def read(self) -> dict | None: ...
+    def read(self) -> dict | None:
+        """Read the cached content, or ``None`` if unavailable or corrupt."""
+        ...
 
-    def write(self, content: dict) -> None: ...
+    def write(self, content: dict) -> None:
+        """
+        Persist *content* to the store.
 
-    def remove(self) -> None: ...
+        :param content: interpreter metadata to cache.
+        """
+        ...
+
+    def remove(self) -> None:
+        """Delete the cached content."""
+        ...
 
     @contextmanager
-    def locked(self) -> Generator[None]: ...
+    def locked(self) -> Generator[None]:
+        """Context manager that acquires an exclusive lock on this store."""
+        ...
 
 
 @runtime_checkable
 class PyInfoCache(Protocol):
     """Cache interface for Python interpreter information."""
 
-    def py_info(self, path: Path) -> ContentStore: ...
+    def py_info(self, path: Path) -> ContentStore:
+        """
+        Return the content store for the interpreter at *path*.
+
+        :param path: absolute path to a Python executable.
+        """
+        ...
 
-    def py_info_clear(self) -> None: ...
+    def py_info_clear(self) -> None:
+        """Remove all cached interpreter information."""
+        ...
 
 
 class DiskContentStore:
@@ -91,7 +113,11 @@ class DiskContentStore:
 
 
 class DiskCache:
-    """File-system based Python interpreter info cache (``<root>/py_info/4/<sha256>.json``)."""
+    """
+    File-system based Python interpreter info cache (``<root>/py_info/4/<sha256>.json``).
+
+    :param root: root directory for the on-disk cache.
+    """
 
     def __init__(self, root: Path) -> None:
         self._root = root
@@ -101,10 +127,16 @@ class DiskCache:
         return self._root / "py_info" / "4"
 
     def py_info(self, path: Path) -> DiskContentStore:
+        """
+        Return the content store for the interpreter at *path*.
+
+        :param path: absolute path to a Python executable.
+        """
         key = sha256(str(path).encode("utf-8")).hexdigest()
         return DiskContentStore(self._py_info_dir, key)
 
     def py_info_clear(self) -> None:
+        """Remove all cached interpreter information."""
         folder = self._py_info_dir
         if folder.exists():
             for entry in folder.iterdir():

{python_discovery-1.0.0 → python_discovery-1.1.1}/src/python_discovery/_cached_py_info.py

@@ -15,7 +15,7 @@ from collections import OrderedDict
 from contextlib import contextmanager
 from pathlib import Path
 from shlex import quote
-from subprocess import Popen  # noqa: S404
+from subprocess import Popen, TimeoutExpired  # noqa: S404
 from typing import TYPE_CHECKING, Final
 
 from ._cache import NoOpCache
@@ -206,8 +206,11 @@ def _run_subprocess(
                 encoding="utf-8",
                 errors="backslashreplace",
             )
-            out, err = process.communicate()
+            out, err = process.communicate(timeout=5)
             code = process.returncode
+        except TimeoutExpired:
+            process.kill()
+            out, err, code = "", "timed out", -1
         except OSError as os_error:
             out, err, code = "", os_error.strerror, os_error.errno
     if code != 0:

{python_discovery-1.0.0 → python_discovery-1.1.1}/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:

{python_discovery-1.0.0 → python_discovery-1.1.1}/src/python_discovery/_py_info.py

@@ -245,7 +245,11 @@ class PythonInfo:  # noqa: PLR0904
         return None  # in this case we just can't tell easily without poking around FS and calling them, bail
 
     def install_path(self, key: str) -> str:
-        """Return the relative installation path for a given installation scheme *key*."""
+        """
+        Return the relative installation path for a given installation scheme *key*.
+
+        :param key: sysconfig installation scheme key (e.g. ``"scripts"``, ``"purelib"``).
+        """
         result = self.distutils_install.get(key)
         if result is None:  # pragma: >=3.11 cover # distutils is empty when "venv" scheme is available
             # set prefixes to empty => result is relative from cwd
@@ -308,7 +312,13 @@ class PythonInfo:  # noqa: PLR0904
         return self.base_prefix is not None
 
     def sysconfig_path(self, key: str, config_var: dict[str, str] | None = None, sep: str = os.sep) -> str:
-        """Return the sysconfig install path for a scheme *key*, optionally substituting config variables."""
+        """
+        Return the sysconfig install path for a scheme *key*, optionally substituting config variables.
+
+        :param key: sysconfig path key (e.g. ``"purelib"``, ``"include"``).
+        :param config_var: replacement mapping for sysconfig variables; when ``None`` uses the interpreter's own values.
+        :param sep: path separator to use in the result.
+        """
         pattern = self.sysconfig_paths.get(key)
         if pattern is None:
             return ""
@@ -406,14 +416,23 @@ class PythonInfo:  # noqa: PLR0904
 
     @classmethod
     def clear_cache(cls, cache: PyInfoCache) -> None:
-        """Clear all cached interpreter information from *cache*."""
+        """
+        Clear all cached interpreter information from *cache*.
+
+        :param cache: the cache store to clear.
+        """
         from ._cached_py_info import clear  # noqa: PLC0415
 
         clear(cache)
         cls._cache_exe_discovery.clear()
 
     def satisfies(self, spec: PythonSpec, *, impl_must_match: bool) -> bool:  # noqa: PLR0911
-        """Check if a given specification can be satisfied by this python interpreter instance."""
+        """
+        Check if a given specification can be satisfied by this python interpreter instance.
+
+        :param spec: the specification to check against.
+        :param impl_must_match: when ``True``, the implementation name must match exactly.
+        """
         if spec.path and not self._satisfies_path(spec):
             return False
         if impl_must_match and not self._satisfies_implementation(spec):
@@ -462,7 +481,11 @@ class PythonInfo:  # noqa: PLR0904
 
     @classmethod
     def current(cls, cache: PyInfoCache | None = None) -> PythonInfo:
-        """Locate the current host interpreter information."""
+        """
+        Locate the current host interpreter information.
+
+        :param cache: interpreter metadata cache; when ``None`` results are not cached.
+        """
         if cls._current is None:
             result = cls.from_exe(sys.executable, cache, raise_on_error=True, resolve_to_host=False)
             if result is None:
@@ -473,7 +496,11 @@ class PythonInfo:  # noqa: PLR0904
 
     @classmethod
     def current_system(cls, cache: PyInfoCache | None = None) -> PythonInfo:
-        """Locate the current system interpreter information, resolving through any virtualenv layers."""
+        """
+        Locate the current system interpreter information, resolving through any virtualenv layers.
+
+        :param cache: interpreter metadata cache; when ``None`` results are not cached.
+        """
         if cls._current_system is None:
             result = cls.from_exe(sys.executable, cache, raise_on_error=True, resolve_to_host=True)
             if result is None:
@@ -483,9 +510,11 @@ class PythonInfo:  # noqa: PLR0904
         return cls._current_system
 
     def to_json(self) -> str:
+        """Serialize this interpreter information to a JSON string."""
         return json.dumps(self.to_dict(), indent=2)
 
     def to_dict(self) -> dict[str, object]:
+        """Convert this interpreter information to a plain dictionary."""
         data = {var: (getattr(self, var) if var != "_creators" else None) for var in vars(self)}
         version_info = data["version_info"]
         data["version_info"] = version_info._asdict() if hasattr(version_info, "_asdict") else version_info
@@ -502,7 +531,16 @@ class PythonInfo:  # noqa: PLR0904
         resolve_to_host: bool = True,
         env: Mapping[str, str] | None = None,
     ) -> PythonInfo | None:
-        """Get the python information for a given executable path."""
+        """
+        Get the python information for a given executable path.
+
+        :param exe: path to the Python executable.
+        :param cache: interpreter metadata cache; when ``None`` results are not cached.
+        :param raise_on_error: raise on failure instead of returning ``None``.
+        :param ignore_cache: bypass the cache and re-query the interpreter.
+        :param resolve_to_host: resolve through virtualenv layers to the system interpreter.
+        :param env: environment mapping; defaults to :data:`os.environ`.
+        """
         from ._cached_py_info import from_exe  # noqa: PLC0415
 
         env = os.environ if env is None else env
@@ -520,11 +558,21 @@ class PythonInfo:  # noqa: PLR0904
 
     @classmethod
     def from_json(cls, payload: str) -> PythonInfo:
+        """
+        Deserialize interpreter information from a JSON string.
+
+        :param payload: JSON produced by :meth:`to_json`.
+        """
         raw = json.loads(payload)
         return cls.from_dict(raw.copy())
 
     @classmethod
     def from_dict(cls, data: dict[str, object]) -> PythonInfo:
+        """
+        Reconstruct a :class:`PythonInfo` from a plain dictionary.
+
+        :param data: dictionary produced by :meth:`to_dict`.
+        """
         data["version_info"] = VersionInfo(**data["version_info"])  # restore this to a named tuple structure
         result = cls()
         result.__dict__ = data.copy()
@@ -532,6 +580,12 @@ class PythonInfo:  # noqa: PLR0904
 
     @classmethod
     def resolve_to_system(cls, cache: PyInfoCache | None, target: PythonInfo) -> PythonInfo:
+        """
+        Walk virtualenv/venv prefix chains to find the underlying system interpreter.
+
+        :param cache: interpreter metadata cache; when ``None`` results are not cached.
+        :param target: the interpreter to resolve.
+        """
         start_executable = target.executable
         prefixes = OrderedDict()
         while target.system_executable is None:
@@ -565,7 +619,14 @@ class PythonInfo:  # noqa: PLR0904
         exact: bool = True,
         env: Mapping[str, str] | None = None,
     ) -> PythonInfo:
-        """Discover a matching Python executable under a given *prefix* directory."""
+        """
+        Discover a matching Python executable under a given *prefix* directory.
+
+        :param cache: interpreter metadata cache.
+        :param prefix: directory prefix to search under.
+        :param exact: when ``True``, require an exact version match.
+        :param env: environment mapping; defaults to :data:`os.environ`.
+        """
         key = prefix, exact
         if key in self._cache_exe_discovery and prefix:
             _LOGGER.debug("discover exe from cache %s - exact %s: %r", prefix, exact, self._cache_exe_discovery[key])

{python_discovery-1.0.0 → python_discovery-1.1.1}/src/python_discovery/_py_spec.py

@@ -99,7 +99,20 @@ def _parse_specifier(string_spec: str) -> PythonSpec | None:
 
 
 class PythonSpec:
-    """Contains specification about a Python Interpreter."""
+    """
+    Contains specification about a Python Interpreter.
+
+    :param str_spec: the raw specification string as provided by the caller.
+    :param implementation: interpreter implementation name (e.g. ``"cpython"``, ``"pypy"``), or ``None`` for any.
+    :param major: required major version, or ``None`` for any.
+    :param minor: required minor version, or ``None`` for any.
+    :param micro: required micro (patch) version, or ``None`` for any.
+    :param architecture: required pointer-size bitness (``32`` or ``64``), or ``None`` for any.
+    :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``.
+    """
 
     def __init__(  # noqa: PLR0913, PLR0917
         self,
@@ -128,7 +141,12 @@ class PythonSpec:
 
     @classmethod
     def from_string_spec(cls, string_spec: str) -> PythonSpec:
-        """Parse a string specification into a 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.
+        """
         if pathlib.Path(string_spec).is_absolute():
             return cls(string_spec, None, None, None, None, None, string_spec)
         if result := _parse_spec_pattern(string_spec):
@@ -138,7 +156,11 @@ class PythonSpec:
         return cls(string_spec, None, None, None, None, None, string_spec)
 
     def generate_re(self, *, windows: bool) -> re.Pattern:
-        """Generate a regular expression for matching against a filename."""
+        """
+        Generate a regular expression for matching interpreter filenames.
+
+        :param windows: if ``True``, require a ``.exe`` suffix.
+        """
         version = r"{}(\.{}(\.{})?)?".format(
             *(r"\d+" if v is None else v for v in (self.major, self.minor, self.micro)),
         )
@@ -153,6 +175,7 @@ class PythonSpec:
 
     @property
     def is_abs(self) -> bool:
+        """``True`` if the spec refers to an absolute filesystem path."""
         return self.path is not None and pathlib.Path(self.path).is_absolute()
 
     def _check_version_specifier(self, spec: PythonSpec) -> bool:
@@ -188,7 +211,11 @@ class PythonSpec:
         return None
 
     def satisfies(self, spec: PythonSpec) -> bool:  # noqa: PLR0911
-        """Check if this spec is compatible with the given *spec* (e.g. PEP-514 on Windows)."""
+        """
+        Check if this spec is compatible with the given *spec* (e.g. PEP-514 on Windows).
+
+        :param spec: the requirement to check against.
+        """
         if spec.is_abs and self.is_abs and self.path != spec.path:
             return False
         if (

{python_discovery-1.0.0 → python_discovery-1.1.1}/src/python_discovery/_specifier.py

@@ -40,7 +40,17 @@ _PRE_ORDER: Final[dict[str, int]] = {"a": 1, "b": 2, "rc": 3}
 
 @dataclass(**_DC_KW)
 class SimpleVersion:
-    """Simple PEP 440-like version parser using only standard library."""
+    """
+    Simple PEP 440-like version parser using only standard library.
+
+    :param version_str: the original version string.
+    :param major: major version number.
+    :param minor: minor version number.
+    :param micro: micro (patch) version number.
+    :param pre_type: pre-release label (``"a"``, ``"b"``, or ``"rc"``), or ``None``.
+    :param pre_num: pre-release sequence number, or ``None``.
+    :param release: the ``(major, minor, micro)`` tuple.
+    """
 
     version_str: str
     major: int
@@ -52,6 +62,11 @@ class SimpleVersion:
 
     @classmethod
     def from_string(cls, version_str: str) -> SimpleVersion:
+        """
+        Parse a PEP 440 version string (e.g. ``3.12.1``).
+
+        :param version_str: the version string to parse.
+        """
         stripped = version_str.strip()
         if not (match := _VERSION_RE.match(stripped)):
             msg = f"Invalid version: {version_str}"
@@ -112,7 +127,16 @@ class SimpleVersion:
 
 @dataclass(**_DC_KW)
 class SimpleSpecifier:
-    """Simple PEP 440-like version specifier using only standard library."""
+    """
+    Simple PEP 440-like version specifier using only standard library.
+
+    :param spec_str: the original specifier string (e.g. ``>=3.10``).
+    :param operator: the comparison operator (``==``, ``>=``, ``<``, etc.).
+    :param version_str: the version portion of the specifier, without the operator.
+    :param is_wildcard: ``True`` if the specifier uses a wildcard suffix (``.*``).
+    :param wildcard_precision: number of version components before the wildcard, or ``None``.
+    :param version: the parsed version, or ``None`` if parsing failed.
+    """
 
     spec_str: str
     operator: str
@@ -123,6 +147,11 @@ class SimpleSpecifier:
 
     @classmethod
     def from_string(cls, spec_str: str) -> SimpleSpecifier:
+        """
+        Parse a single PEP 440 specifier (e.g. ``>=3.10``).
+
+        :param spec_str: the specifier string to parse.
+        """
         stripped = spec_str.strip()
         if not (match := _SPECIFIER_RE.match(stripped)):
             msg = f"Invalid specifier: {spec_str}"
@@ -148,7 +177,11 @@ class SimpleSpecifier:
         )
 
     def contains(self, version_str: str) -> bool:
-        """Check if a version string satisfies this specifier."""
+        """
+        Check if a version string satisfies this specifier.
+
+        :param version_str: the version string to test.
+        """
         try:
             candidate = SimpleVersion.from_string(version_str) if isinstance(version_str, str) else version_str
         except ValueError:
@@ -216,13 +249,23 @@ class SimpleSpecifier:
 
 @dataclass(**_DC_KW)
 class SimpleSpecifierSet:
-    """Simple PEP 440-like specifier set using only standard library."""
+    """
+    Simple PEP 440-like specifier set using only standard library.
+
+    :param specifiers_str: the original comma-separated specifier string.
+    :param specifiers: the parsed individual specifiers.
+    """
 
     specifiers_str: str
     specifiers: tuple[SimpleSpecifier, ...]
 
     @classmethod
     def from_string(cls, specifiers_str: str = "") -> SimpleSpecifierSet:
+        """
+        Parse a comma-separated PEP 440 specifier string (e.g. ``>=3.10,<4``).
+
+        :param specifiers_str: the specifier string to parse.
+        """
         stripped = specifiers_str.strip()
         specs: list[SimpleSpecifier] = []
         if stripped:
@@ -234,7 +277,11 @@ class SimpleSpecifierSet:
         return cls(specifiers_str=stripped, specifiers=tuple(specs))
 
     def contains(self, version_str: str) -> bool:
-        """Check if a version satisfies all specifiers in the set."""
+        """
+        Check if a version satisfies all specifiers in the set.
+
+        :param version_str: the version string to test.
+        """
         if not self.specifiers:
             return True
         return all(spec.contains(version_str) for spec in self.specifiers)

{python_discovery-1.0.0 → python_discovery-1.1.1}/tests/conftest.py

@@ -26,4 +26,5 @@ def _ensure_py_info_cache_empty(session_cache: DiskCache) -> Generator[None]:
 def _skip_if_test_in_system(session_cache: DiskCache) -> None:
     current = PythonInfo.current(session_cache)
     if current.system_executable is not None:  # pragma: no cover
-        pytest.skip("test not valid if run under system")
+        msg = "test not valid if run under system"
+        raise pytest.skip.Exception(msg)

{python_discovery-1.0.0 → python_discovery-1.1.1}/tests/py_info/test_py_info.py

@@ -338,7 +338,7 @@ def test_py_info_machine_property() -> None:
     assert machine is not None
     assert isinstance(machine, str)
     assert len(machine) > 0
-    known_isas = {"arm64", "x86_64", "x86", "ppc64le", "ppc64", "s390x", "riscv64"}
+    known_isas = {"arm64", "i686", "ppc64", "ppc64le", "riscv64", "s390x", "x86", "x86_64"}
     assert machine in known_isas, f"unexpected machine value: {machine}"
 
 

{python_discovery-1.0.0 → python_discovery-1.1.1}/tests/test_cached_py_info.py

@@ -5,6 +5,7 @@ import logging
 import os
 import sys
 from pathlib import Path
+from subprocess import TimeoutExpired
 from typing import TYPE_CHECKING
 from unittest.mock import MagicMock, patch
 
@@ -110,6 +111,17 @@ def test_run_subprocess_with_cookies(mocker: MockerFixture) -> None:
     assert mock_stdout.write.call_count == 2
 
 
+def test_run_subprocess_timeout(mocker: MockerFixture) -> None:
+    mock_process = MagicMock()
+    mock_process.communicate.side_effect = TimeoutExpired(cmd="python", timeout=30)
+    mocker.patch("python_discovery._cached_py_info.Popen", return_value=mock_process)
+    failure, result = _run_subprocess(PythonInfo, sys.executable, dict(os.environ))
+    assert failure is not None
+    assert "timed out" in str(failure)
+    assert result is None
+    mock_process.kill.assert_called_once()
+
+
 def test_run_subprocess_nonzero_exit(mocker: MockerFixture) -> None:
     mock_process = MagicMock()
     mock_process.communicate.return_value = ("some output", "some error")

{python_discovery-1.0.0 → python_discovery-1.1.1}/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

python_discovery-1.0.0/.github/release.yml

@@ -1,5 +0,0 @@
-changelog:
-  exclude:
-    authors:
-      - dependabot
-      - pre-commit-ci