Migrate _binaries and _utils path handling to pathlib

Part 3 of the series proposed in #2410.

_binaries/find_nvidia_binary_utility.py now works in Path internally:
_is_executable_candidate, _ctk_bin_subdirs and _resolve_in_trusted_dirs take
and return Path. str() is applied once, on the public return of
find_nvidia_binary_utility(), which is unchanged.

SITE_PACKAGES_BINDIRS holds path components instead of joined strings. The
caller immediately did sub_dir.split(os.sep) to undo the join, and
find_sub_dirs_all_sitepackages wants components anyway.

find_sub_dirs_no_cache walks in Path. Its return type stays list[str]:
_binaries, _dynamic_libs, _headers and _static_libs all consume it, so
flipping it is better done on its own once those have moved.

Its directory test goes through a small _is_dir() helper rather than calling
Path.is_dir() directly. The two are not interchangeable here: os.path.isdir()
returns False for any stat error, while Path.is_dir() only swallows the errnos
in pathlib's ignore list and propagates the rest. This function walks
site-packages trees that nobody here controls, so a single unreadable
directory would have turned a clean "not found" into a PermissionError.

_utils/env_vars.py uses Path.exists/Path.samefile. Both calls are already
inside the existing try/except OSError, so the same error-handling difference
does not apply. os.path.normcase and os.path.normpath stay in _paths_differ:
PurePath does not collapse "..", which test_paths_differ_text_only depends on,
and Path.resolve() would also follow symlinks. os.path.abspath likewise stays
in _resolve_in_trusted_dirs, since Path.absolute() does not normalize.

test_find_nvidia_binaries.py moves with the module: it asserts on the exact
values passed to and returned by these private helpers, so it cannot be
separated from the signature change.

Verified by differential fuzzing of find_sub_dirs_no_cache against the
previous implementation: 3000 calls over randomized trees comparing result
order, plus 720 calls over trees containing unreadable directories. Identical,
except that a parent dir spelled with redundant separators now yields the
normalized form.

Signed-off-by: LeSingh1 <sshaurya914@gmail.com>

Author: LeSingh1

cuda_pathfinder/cuda/pathfinder/_binaries/find_nvidia_binary_utility.py

@@ -4,6 +4,7 @@
 import functools
 import os
 from collections.abc import Iterable
+from pathlib import Path
 
 from cuda.pathfinder._binaries import supported_nvidia_binaries, windows_nsight
 from cuda.pathfinder._utils.ctk_root_canary import CTK_ROOT_CANARY_ANCHOR_LIBNAMES
@@ -29,22 +30,23 @@ def _normalize_utility_name(utility_name: str) -> str:
     return utility_name
 
 
-def _is_executable_candidate(path: str) -> bool:
-    if not os.path.isfile(path):
+def _is_executable_candidate(path: Path) -> bool:
+    if not path.is_file():
         return False
     if IS_WINDOWS:
         return True
+    # pathlib has no access() equivalent.
     return os.access(path, os.X_OK)
 
 
-def _ctk_bin_subdirs(root: str) -> list[str]:
+def _ctk_bin_subdirs(root: Path) -> list[Path]:
     if IS_WINDOWS:
         return [
-            os.path.join(root, "bin", "x64"),
-            os.path.join(root, "bin", "x86_64"),
-            os.path.join(root, "bin"),
+            root / "bin" / "x64",
+            root / "bin" / "x86_64",
+            root / "bin",
         ]
-    return [os.path.join(root, "bin")]
+    return [root / "bin"]
 
 
 def _resolve_candidate_paths(candidates: Iterable[str]) -> str | None:
@@ -54,7 +56,7 @@ def _resolve_candidate_paths(candidates: Iterable[str]) -> str | None:
         if candidate in seen:
             continue
         seen.add(candidate)
-        if _is_executable_candidate(candidate):
+        if _is_executable_candidate(Path(candidate)):
             return os.path.abspath(candidate)
     return None
 
@@ -75,31 +77,34 @@ def _resolve_ctk_root_via_canary() -> str | None:
     return ctk_root
 
 
-def _resolve_in_trusted_dirs(normalized_name: str, dirs: list[str]) -> str | None:
+def _resolve_in_trusted_dirs(normalized_name: str, dirs: list[Path]) -> str | None:
     """Resolve ``normalized_name`` against ``dirs`` in order."""
-    seen: set[str] = set()
+    seen: set[Path] = set()
     for directory in dirs:
         if directory in seen:
             continue
-        assert directory
+        # Path("") is Path("."), which would silently search the CWD (#2119).
+        assert directory != Path()
         seen.add(directory)
-        candidate = os.path.join(directory, normalized_name)
+        candidate = directory / normalized_name
         if _is_executable_candidate(candidate):
             # Return an absolute path, as the docstring promises (a relative
-            # search dir would otherwise leak a relative result).
+            # search dir would otherwise leak a relative result). os.path.abspath
+            # has no pathlib equivalent: Path.absolute() does not normalize and
+            # Path.resolve() would also follow symlinks.
             return os.path.abspath(candidate)
     return None
 
 
-def _resolve_names_in_trusted_dirs(candidate_names: tuple[str, ...], dirs: list[str]) -> str | None:
+def _resolve_names_in_trusted_dirs(candidate_names: tuple[str, ...], dirs: list[Path]) -> str | None:
     """Resolve ordered candidate names within each trusted directory."""
-    seen: set[str] = set()
+    seen: set[Path] = set()
     for directory in dirs:
         if directory in seen:
             continue
-        assert directory
+        assert directory != Path()
         seen.add(directory)
-        found = _resolve_candidate_paths(os.path.join(directory, name) for name in candidate_names)
+        found = _resolve_candidate_paths(str(directory / name) for name in candidate_names)
         if found is not None:
             return found
     return None
@@ -193,17 +198,15 @@ def find_nvidia_binary_utility(utility_name: str) -> str | None:
 
     # 1. Search in site-packages (NVIDIA wheels)
     candidate_dirs = supported_nvidia_binaries.SITE_PACKAGES_BINDIRS.get(utility_name, ())
-    dirs = []
+    dirs: list[Path] = []
 
     for sub_dir in candidate_dirs:
-        dirs.extend(find_sub_dirs_all_sitepackages(sub_dir.split(os.sep)))
+        dirs.extend(Path(abs_dir) for abs_dir in find_sub_dirs_all_sitepackages(sub_dir))
 
     # 2. Search in Conda environment
     if (conda_prefix := os.environ.get("CONDA_PREFIX")) is not None:
-        if IS_WINDOWS:
-            dirs.append(os.path.join(conda_prefix, "Library", "bin"))
-        else:
-            dirs.append(os.path.join(conda_prefix, "bin"))
+        conda_root = Path(conda_prefix)
+        dirs.append(conda_root / "Library" / "bin" if IS_WINDOWS else conda_root / "bin")
 
     normalized_name = _normalize_utility_name(utility_name)
     if IS_WINDOWS and utility_name in ("compute-sanitizer", "ncu"):
@@ -235,5 +238,5 @@ def find_nvidia_binary_utility(utility_name: str) -> str | None:
     if ctk_root is not None:
         if IS_WINDOWS and utility_name == "compute-sanitizer":
             return _find_windows_compute_sanitizer(ctk_root)
-        return _resolve_in_trusted_dirs(normalized_name, _ctk_bin_subdirs(ctk_root))
+        return _resolve_in_trusted_dirs(normalized_name, _ctk_bin_subdirs(Path(ctk_root)))
     return None

cuda_pathfinder/cuda/pathfinder/_binaries/supported_nvidia_binaries.py

@@ -1,13 +1,13 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
-import os
 
 # Site-packages bin directories where binaries might be found
-# Based on NVIDIA wheel layouts (same for Linux and Windows)
-_CUDA_NVCC_BIN = os.path.join("nvidia", "cuda_nvcc", "bin")
-_CUDA13_BIN = os.path.join("nvidia", "cu13", "bin")
-_NSIGHT_SYSTEMS_BIN = os.path.join("nvidia", "nsight_systems", "bin")
-_NSIGHT_COMPUTE_BIN = os.path.join("nvidia", "nsight_compute", "bin")
+# Based on NVIDIA wheel layouts (same for Linux and Windows).
+# Path components, because that is what find_sub_dirs_all_sitepackages takes.
+_CUDA_NVCC_BIN = ("nvidia", "cuda_nvcc", "bin")
+_CUDA13_BIN = ("nvidia", "cu13", "bin")
+_NSIGHT_SYSTEMS_BIN = ("nvidia", "nsight_systems", "bin")
+_NSIGHT_COMPUTE_BIN = ("nvidia", "nsight_compute", "bin")
 
 # Common CUDA binary utilities available on both Linux and Windows
 SITE_PACKAGES_BINDIRS = {

cuda_pathfinder/cuda/pathfinder/_utils/env_vars.py

@@ -22,6 +22,7 @@
 import functools
 import os
 import warnings
+from pathlib import Path
 
 _CUDA_PATH_ENV_VARS_ORDERED = ("CUDA_PATH", "CUDA_HOME")
 
@@ -36,15 +37,19 @@ def _paths_differ(a: str, b: str) -> bool:
     2) If still different AND both exist, use os.path.samefile to resolve symlinks/junctions.
     3) Otherwise (nonexistent paths or samefile unavailable), treat as different.
     """
+    # normcase/normpath have no pathlib equivalent: PurePath does not collapse
+    # "..", Path.resolve() would also follow symlinks, and comparing PurePath
+    # objects would only case-fold on Windows.
     norm_a = os.path.normcase(os.path.normpath(a))
     norm_b = os.path.normcase(os.path.normpath(b))
     if norm_a == norm_b:
         return False
 
+    path_a, path_b = Path(a), Path(b)
     try:
-        if os.path.exists(a) and os.path.exists(b):
+        if path_a.exists() and path_b.exists():
             # samefile raises on non-existent paths; only call when both exist.
-            return not os.path.samefile(a, b)
+            return not path_a.samefile(path_b)
     except OSError:
         # Fall through to "different" if samefile isn't applicable/available.
         pass

cuda_pathfinder/cuda/pathfinder/_utils/find_sub_dirs.py

@@ -2,36 +2,51 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import functools
-import os
 import site
 import sys
 from collections.abc import Sequence
+from pathlib import Path
+
+
+def _is_dir(path: Path) -> bool:
+    """``path.is_dir()``, but False instead of raising on an inaccessible path.
+
+    This walks directories nobody here controls, so it has to tolerate whatever
+    it runs into. Path.is_dir() only swallows the errnos in pathlib's ignore
+    list, and raises for the rest (EACCES, ENAMETOOLONG); os.path.isdir, which
+    this replaces, returned False for all of them.
+    """
+    try:
+        return path.is_dir()
+    except OSError:
+        return False
 
 
 def find_sub_dirs_no_cache(parent_dirs: Sequence[str], sub_dirs: Sequence[str]) -> list[str]:
+    # Results stay str: they are consumed by _binaries, _dynamic_libs, _headers
+    # and _static_libs, so the type flip belongs in its own change.
     results = []
     for base in parent_dirs:
-        stack = [(base, 0)]  # (current_path, index into sub_dirs)
+        stack = [(Path(base), 0)]  # (current_path, index into sub_dirs)
         while stack:
             current_path, idx = stack.pop()
             if idx == len(sub_dirs):
-                if os.path.isdir(current_path):
-                    results.append(current_path)
+                if _is_dir(current_path):
+                    results.append(str(current_path))
                 continue
 
             sub = sub_dirs[idx]
             if sub == "*":
                 try:
-                    entries = sorted(os.listdir(current_path))
+                    entries = sorted(current_path.iterdir(), key=lambda entry: entry.name)
                 except OSError:
                     continue
-                for entry in entries:
-                    entry_path = os.path.join(current_path, entry)
-                    if os.path.isdir(entry_path):
+                for entry_path in entries:
+                    if _is_dir(entry_path):
                         stack.append((entry_path, idx + 1))
             else:
-                next_path = os.path.join(current_path, sub)
-                if os.path.isdir(next_path):
+                next_path = current_path / sub
+                if _is_dir(next_path):
                     stack.append((next_path, idx + 1))
     return results