python-discovery 1.5.0__tar.gz → 1.5.1__tar.gz

{python_discovery-1.5.0 → python_discovery-1.5.1}/.github/workflows/check.yaml

@@ -33,12 +33,12 @@ jobs:
           - dev
           - pkg_meta
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"

{python_discovery-1.5.0 → python_discovery-1.5.1}/.github/workflows/prepare-release.yaml

@@ -23,13 +23,13 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           token: ${{ secrets.RELEASE_PAT }}
           persist-credentials: true
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           enable-cache: true
           cache-dependency-glob: "pyproject.toml"

{python_discovery-1.5.0 → python_discovery-1.5.1}/.github/workflows/release.yaml

@@ -10,12 +10,12 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           enable-cache: false
           cache-dependency-glob: "pyproject.toml"
@@ -43,6 +43,6 @@ jobs:
           name: ${{ env.dists-artifact-name }}
           path: dist/
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
         with:
           attestations: true

{python_discovery-1.5.0 → python_discovery-1.5.1}/.pre-commit-config.yaml

@@ -15,11 +15,11 @@ repos:
       - id: codespell
         additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.25.3"
+    rev: "v2.26.0"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.22"
+    rev: "v0.16.0"
     hooks:
       - id: ruff-format
       - id: ruff
@@ -39,7 +39,7 @@ repos:
           - mdformat-gfm>=1
           - mdformat-ruff>=0.1.3
   - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: v1.27.0
+    rev: v1.28.0
     hooks:
       - id: zizmor
   - repo: meta

{python_discovery-1.5.0 → python_discovery-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-discovery
-Version: 1.5.0
+Version: 1.5.1
 Summary: Python interpreter discovery
 Project-URL: Changelog, https://github.com/tox-dev/python-discovery/releases
 Project-URL: Documentation, https://python-discovery.readthedocs.io
@@ -48,7 +48,6 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
 Requires-Python: >=3.8
 Requires-Dist: filelock>=3.15.4
-Requires-Dist: platformdirs<5,>=4.3.6
 Description-Content-Type: text/markdown
 
 # [`python-discovery`](https://python-discovery.readthedocs.io/en/latest/)

{python_discovery-1.5.0 → python_discovery-1.5.1}/docs/changelog.rst

@@ -6,6 +6,24 @@
 
 .. towncrier release notes start
 
+********************
+ v1.5.1 (2026-07-31)
+********************
+
+Bug fixes - 1.5.1
+=================
+- Locate uv's interpreter store the way uv does, using XDG on macOS (``~/.local/share/uv/python``) and roaming
+  ``%APPDATA%\uv\python`` on Windows, neither of which ``platformdirs`` reported. The uv variables now come from the
+  ``env`` mapping rather than ``os.environ`` - by :user:`gaborbernat`. (:issue:`109`)
+- Pick uv-managed interpreters by install directory name instead of globbing the store. A bare ``3.8`` now means
+  CPython, the way uv resolves it, rather than whichever implementation the filesystem happened to list first, and
+  probing runs newest version first - by :user:`gaborbernat`. (:issue:`110`)
+
+Packaging updates and notes for downstreams - 1.5.1
+===================================================
+- Drop the ``platformdirs`` runtime dependency; locating uv's store was the only thing it did - by
+  :user:`gaborbernat`. (:issue:`109`)
+
 ********************
  v1.5.0 (2026-07-21)
 ********************

{python_discovery-1.5.0 → python_discovery-1.5.1}/docs/explanation.rst

@@ -68,9 +68,33 @@ detects these shims and resolves them to the actual binary.
 How uv-managed Pythons are discovered
 ---------------------------------------
 
-`uv <https://docs.astral.sh/uv/>`_ installs Python interpreters under a single root directory (configurable via
-``UV_PYTHON_INSTALL_DIR``, otherwise defaulting under ``XDG_DATA_HOME`` or the platform user-data path). Each
-install lives in its own subdirectory, but the actual binary location varies by OS and implementation:
+`uv <https://docs.astral.sh/uv/>`_ installs Python interpreters under a single root directory. ``UV_PYTHON_INSTALL_DIR``
+overrides it; otherwise the store is the ``python`` bucket of uv's state directory, which uv derives as follows:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+
+   * - Platform
+     - Legacy state directory
+     - Current state directory
+   * - Windows
+     - ``%APPDATA%\uv\data``
+     - ``%APPDATA%\uv`` (roaming, not local)
+   * - macOS
+     - ``~/Library/Application Support/uv``
+     - ``$XDG_DATA_HOME/uv`` or ``~/.local/share/uv``
+   * - Other
+     - same as current
+     - ``$XDG_DATA_HOME/uv`` or ``~/.local/share/uv``
+
+uv follows the XDG convention on macOS too, and falls back to the legacy directory only when that directory already
+exists. python-discovery searches both, in the same order, so a leftover legacy directory cannot hide the store uv
+installs into. A relative ``XDG_DATA_HOME`` does not count, as the XDG specification requires, and Windows ignores it
+outright. Every one of these variables comes from the ``env`` mapping passed to
+:func:`~python_discovery.get_interpreter`, rather than from the process environment.
+
+Each install lives in its own subdirectory, but the actual binary location varies by OS and implementation:
 
 .. list-table::
    :header-rows: 1
@@ -89,42 +113,51 @@ install lives in its own subdirectory, but the actual binary location varies by
      - ``<root>/<key>/bin/graalpy``
      - ``<root>/<key>/bin/graalpy.exe``
 
+GraalPy keeps its ``bin/`` segment on Windows (an upstream choice in uv); PyPy and CPython do not. python-discovery
+globs all of these patterns regardless of the host OS, because globs that do not match anything are essentially
+free, and the cross-platform list is short. Symlinked aliases inside an install (``bin/python``,
+``bin/python3``, ``bin/python3.14`` all pointing at the same real file) are deduplicated by resolved path before
+the subprocess interrogation, so each install is interrogated once. python-discovery also follows the ``install``
+subdirectory some distributions unpack into, as uv does.
+
+Which uv installs get interrogated
+------------------------------------
+
+Interrogating an interpreter costs a subprocess, and a uv install directory announces what it holds in its own name:
+``<implementation>-<version>[+<variant>]-<os>-<arch>-<libc>``, for example
+``cpython-3.14.6+freethreaded-macos-aarch64-none``. python-discovery reads that name and skips the installs the spec
+already rules out, then probes what is left in uv's preference order:
+
 .. mermaid::
 
     flowchart LR
-        Call(["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 Call 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
+        Dirs[/"store subdirectories"/] --> Parse{"name is a uv key?"}
+        Parse -->|"no"| Last["probe last"]
+        Parse -->|"yes"| Filter["drop what the spec rules out:<br>implementation, version, free-threaded, debug"]
+        Filter --> Sort["CPython → PyPy → GraalPy,<br>newest version first,<br>default build before variants"]
+        Sort --> Interrogate(["subprocess interrogation"])
+        Last --> Interrogate
+
+        style Dirs fill:#4a90d9,stroke:#2a5f8f,color:#fff
+        style Parse fill:#d9904a,stroke:#8f5f2a,color:#fff
+        style Filter fill:#9f4ad9,stroke:#5f2a8f,color:#fff
+        style Sort fill:#c2873a,stroke:#7a4c1f,color:#fff
         style Interrogate fill:#4a9f4a,stroke:#2a6f2a,color:#fff
 
-GraalPy keeps its ``bin/`` segment on Windows (an upstream choice in uv); PyPy and CPython do not. python-discovery
-globs all of these patterns regardless of the host OS, because globs that do not match anything are essentially
-free, and the cross-platform list is short. Symlinked aliases inside an install (``bin/python``,
-``bin/python3``, ``bin/python3.14`` all pointing at the same real file) are deduplicated by resolved path before
-the subprocess interrogation, so each install is interrogated once.
+python-discovery reads the variant suffix the same way :class:`~python_discovery.PythonSpec` does: ``3.14t`` wants
+``+freethreaded``, ``3.14d`` wants ``+debug``. A spec that says nothing about a variant leaves it unconstrained, so
+``3.14`` still reaches a ``+debug`` install, after the default build rather than instead of it.
+
+A bare version spec such as ``3.8`` matches CPython only, which is what uv resolves it to and what the equivalent
+``python3.8`` probe on ``PATH`` finds in practice. Ask for ``pypy3.8`` or enumerate with
+:func:`~python_discovery.iter_interpreters` to reach the other implementations - PyPy ships a ``bin/python`` symlink,
+so a store-wide glob would otherwise hand back PyPy for ``3.8`` whenever the filesystem listed it first.
+
+Two names carry less information than they appear to. GraalPy keys named after the GraalVM release
+(``graalpy-24.1.1``, from older uv versions) do not constrain the version, and uv's minor version links
+(``cpython-3.15`` pointing at ``cpython-3.15.0b3``) move on the next patch release, so the concrete install ranks
+ahead of the link. Anything that is not a uv key - a hand-made ``UV_PYTHON_INSTALL_DIR`` layout, say - stays in
+the running, at the back of the queue.
 
 Selecting one interpreter vs. enumerating all of them
 -------------------------------------------------------

{python_discovery-1.5.0 → python_discovery-1.5.1}/pyproject.toml

@@ -45,7 +45,6 @@ dynamic = [
 ]
 dependencies = [
   "filelock>=3.15.4",
-  "platformdirs<5,>=4.3.6",
 ]
 urls.Changelog = "https://github.com/tox-dev/python-discovery/releases"
 urls.Documentation = "https://python-discovery.readthedocs.io"

{python_discovery-1.5.0 → python_discovery-1.5.1}/src/python_discovery/_discovery.py

@@ -4,14 +4,14 @@ import logging
 import os
 import sys
 from contextlib import suppress
+from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Final
 
-from platformdirs import user_data_path
-
 from ._compat import fs_path_id
 from ._py_info import PythonInfo
 from ._py_spec import PythonSpec
+from ._specifier import DC_KW, SimpleVersion
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence
@@ -199,7 +199,7 @@ def propose_interpreters(
     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, all_implementations=all_implementations)
-    yield from _propose_from_uv(cache, env, all_implementations=all_implementations)
+    yield from _propose_from_uv(spec, cache, env, all_implementations=all_implementations)
 
 
 def _propose_explicit(
@@ -262,30 +262,157 @@ def _propose_from_path(
 
 
 def _propose_from_uv(
+    spec: PythonSpec,
     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()
-    elif xdg_data_home := os.getenv("XDG_DATA_HOME"):
-        uv_python_path = Path(xdg_data_home).expanduser() / "uv" / "python"
+    seen_uv_paths: set[str] = set()
+    for root in _uv_python_roots(env):
+        for install in _uv_installs(root, spec, all_implementations=all_implementations):
+            for exe_path in _uv_executables(install):
+                if (resolved := str(exe_path.resolve())) 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
+                    break  # one install directory holds one interpreter
+
+
+def _uv_python_roots(env: Mapping[str, str]) -> Generator[Path, None, None]:
+    """Yield uv's store roots, legacy first; searching both keeps a stale legacy directory from hiding the live one."""
+    if install_dir := env.get("UV_PYTHON_INSTALL_DIR"):
+        yield Path(install_dir).expanduser()
+        return
+    for state_dir in _uv_state_dirs(env):
+        yield state_dir / "python"
+
+
+def _uv_state_dirs(env: Mapping[str, str]) -> Generator[Path, None, None]:
+    """Yield uv's legacy state directory then its current one, the order uv prefers them in."""
+    windows = sys.platform == "win32"
+    home = Path(env.get("USERPROFILE" if windows else "HOME") or "~").expanduser()
+    if windows:
+        app_data = Path(env["APPDATA"]) if "APPDATA" in env else home / "AppData" / "Roaming"
+        yield app_data / "uv" / "data"
+        yield app_data / "uv"
+        return
+    if sys.platform == "darwin":
+        yield home / "Library" / "Application Support" / "uv"
+    # uv ignores a relative XDG_DATA_HOME, as the XDG specification requires
+    if (xdg_data_home := env.get("XDG_DATA_HOME")) and (xdg := Path(xdg_data_home)).is_absolute():
+        yield xdg / "uv"
     else:
-        uv_python_path = user_data_path("uv") / "python"
+        yield home / ".local" / "share" / "uv"
 
-    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 _uv_installs(root: Path, spec: PythonSpec, *, all_implementations: bool) -> list[_UvInstall]:
+    try:
+        matching = [
+            install
+            for entry in sorted(root.iterdir())
+            if not entry.name.startswith(".")
+            and entry.is_dir()
+            and _uv_install_matches(install := _parse_uv_install(entry), spec, all_implementations=all_implementations)
+        ]
+    except OSError:
+        return []
+    matching.sort(key=_uv_sort_key)  # stable, so equally ranked installs stay in directory name order
+    return matching
+
+
+def _parse_uv_install(path: Path) -> _UvInstall:
+    implementation, _, remainder = path.name.partition("-")
+    version_str, _, variant = remainder.partition("-")[0].partition("+")
+    try:
+        version = SimpleVersion.from_string(version_str)
+    except ValueError:  # not a uv key, but the directory may still hold an interpreter worth probing
+        return _UvInstall(path=path, key=None)
+    variants = variant.split("+")
+    key = _UvKey(
+        implementation=implementation.lower(),
+        version=version,
+        free_threaded="freethreaded" in variants,
+        debug="debug" in variants,
+    )
+    return _UvInstall(path=path, key=key)
+
+
+@dataclass(**DC_KW)
+class _UvKey:
+    """The ``<implementation>-<version>[+<variant>]-<os>-<arch>-<libc>`` name uv gives an install directory."""
+
+    implementation: str
+    version: SimpleVersion
+    free_threaded: bool
+    debug: bool
+
+
+@dataclass(**DC_KW)
+class _UvInstall:
+    path: Path
+    key: _UvKey | None
+
+
+def _uv_install_matches(install: _UvInstall, spec: PythonSpec, *, all_implementations: bool) -> bool:
+    if (key := install.key) is None:
+        return True
+    if spec.implementation is not None:
+        if spec.implementation.lower() != key.implementation:
+            return False
+    elif not all_implementations and key.implementation != "cpython":
+        # uv resolves a bare `3.8` to `cpython-3.8`; on PATH the equivalent probe finds CPython too
+        return False
+    if spec.free_threaded is not None and spec.free_threaded != key.free_threaded:
+        return False
+    if spec.debug is not None and spec.debug != key.debug:
+        return False
+    return _uv_version_matches(key, spec)
+
+
+def _uv_version_matches(key: _UvKey, spec: PythonSpec) -> bool:
+    # GraalPy keys carry the GraalVM version in older uv releases, so only CPython and PyPy state a Python version
+    if key.implementation not in {"cpython", "pypy"}:
+        return True
+    if spec.version_specifier is not None and not spec.version_specifier.contains(str(key.version)):
+        return False
+    return all(req is None or our == req for our, req in zip(key.version.release, (spec.major, spec.minor, spec.micro)))
+
+
+def _uv_sort_key(install: _UvInstall) -> tuple[int, ...]:
+    """Rank like uv does: CPython first, newest version first, default build ahead of free-threaded and debug."""
+    impl_order: Final[tuple[str, ...]] = ("cpython", "pypy", "graalpy", "pyodide")
+    if (key := install.key) is None:
+        return (len(impl_order) + 1,)
+    version = key.version
+    return (
+        impl_order.index(key.implementation) if key.implementation in impl_order else len(impl_order),
+        # uv's minor version links point at a concrete install that moves on upgrade, so report the target instead
+        int(install.path.is_symlink()),
+        -version.major,
+        -version.minor,
+        -version.micro,
+        -{"a": 0, "b": 1, "rc": 2, None: 3}[version.pre_type],
+        -(version.pre_num or 0),
+        int(key.free_threaded),
+        int(key.debug),
+    )
+
+
+def _uv_executables(install: _UvInstall) -> Generator[Path, None, None]:
+    # some distributions unpack into an `install` subdirectory, which uv resolves the same way
+    base = nested if (nested := install.path / "install").is_dir() else install.path
+    for pattern in (
+        "bin/python",
+        "python.exe",
+        "bin/pypy*",
+        "pypy*.exe",
+        "bin/graalpy",
+        "bin/graalpy.exe",
+        "python*t.exe",  # free-threaded Windows builds that ship no python.exe (astral-sh/uv#8298)
+    ):
+        yield from sorted(base.glob(pattern))
 
 
 def get_paths(env: Mapping[str, str]) -> Generator[Path, None, None]:

{python_discovery-1.5.0 → python_discovery-1.5.1}/src/python_discovery/_specifier.py

@@ -9,7 +9,9 @@ import sys
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Final
 
-_DC_KW = {"frozen": True, "kw_only": True, "slots": True} if sys.version_info >= (3, 10) else {"frozen": True}
+DC_KW: Final[dict[str, bool]] = (
+    {"frozen": True, "kw_only": True, "slots": True} if sys.version_info >= (3, 10) else {"frozen": True}
+)
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
@@ -38,7 +40,7 @@ _SPECIFIER_RE: Final[re.Pattern[str]] = re.compile(
 _PRE_ORDER: Final[dict[str, int]] = {"a": 1, "b": 2, "rc": 3}
 
 
-@dataclass(**_DC_KW)
+@dataclass(**DC_KW)
 class SimpleVersion:
     """
     Simple PEP 440-like version parser using only standard library.
@@ -125,7 +127,7 @@ class SimpleVersion:
         return f"SimpleVersion('{self.version_str}')"
 
 
-@dataclass(**_DC_KW)
+@dataclass(**DC_KW)
 class SimpleSpecifier:
     """
     Simple PEP 440-like version specifier using only standard library.
@@ -247,7 +249,7 @@ class SimpleSpecifier:
         return f"SimpleSpecifier('{self.spec_str}')"
 
 
-@dataclass(**_DC_KW)
+@dataclass(**DC_KW)
 class SimpleSpecifierSet:
     """
     Simple PEP 440-like specifier set using only standard library.
@@ -305,6 +307,7 @@ class SimpleSpecifierSet:
 
 
 __all__ = [
+    "DC_KW",
     "SimpleSpecifier",
     "SimpleSpecifierSet",
     "SimpleVersion",