fix(pathfinder): address binary finder review

Author: aryanputta

cuda_pathfinder/cuda/pathfinder/_binaries/find_nvidia_binary_utility.py

@@ -5,15 +5,11 @@
 import os
 
 from cuda.pathfinder._binaries import supported_nvidia_binaries
+from cuda.pathfinder._utils.ctk_root_canary import CTK_ROOT_CANARY_ANCHOR_LIBNAMES
 from cuda.pathfinder._utils.env_vars import get_cuda_path_or_home
 from cuda.pathfinder._utils.find_sub_dirs import find_sub_dirs_all_sitepackages
 from cuda.pathfinder._utils.platform_aware import IS_WINDOWS
 
-# CUDA Toolkit canary library used to derive the toolkit root when it is only
-# visible through the dynamic loader. ``cudart`` always ships with the CTK and
-# matches the anchor used by the dynamic-library CTK-root canary flow.
-_CTK_ROOT_CANARY_ANCHOR_LIBNAME = "cudart"
-
 
 class UnsupportedBinaryError(Exception):
     def __init__(self, utility: str) -> None:
@@ -37,7 +33,7 @@ def _is_executable_file(path: str) -> bool:
 
     On Windows executability is determined by the file extension (the
     candidate name already carries one), so existence is sufficient. On POSIX
-    the execute permission bit must be set, matching ``shutil.which``.
+    the execute permission bit must be set.
     """
     if not os.path.isfile(path):
         return False
@@ -47,11 +43,6 @@ def _is_executable_file(path: str) -> bool:
 
 
 def _ctk_bin_subdirs(root: str) -> list[str]:
-    """Return the bin directories to search under a CUDA Toolkit ``root``.
-
-    On Windows the CTK ships binaries under ``bin/x64`` (CTK 13), ``bin/x86_64``,
-    and ``bin`` (CTK 12); on Linux they live in ``bin``.
-    """
     if IS_WINDOWS:
         return [
             os.path.join(root, "bin", "x64"),
@@ -62,34 +53,19 @@ def _ctk_bin_subdirs(root: str) -> list[str]:
 
 
 def _resolve_ctk_root_via_canary() -> str | None:
-    """Derive the CUDA Toolkit root from the ``cudart`` canary library.
-
-    ``cudart`` is resolved by the OS dynamic loader, which honors
-    ``LD_LIBRARY_PATH`` on Linux and the native DLL search on Windows, and the
-    toolkit root is derived from its absolute path. The ambient ``PATH`` is
-    never consulted. The loader module is imported lazily to avoid pulling the
-    dynamic-library machinery in at import time.
-    """
     from cuda.pathfinder._dynamic_libs.load_nvidia_dynamic_lib import resolve_ctk_root_via_canary
 
-    ctk_root: str | None = resolve_ctk_root_via_canary(_CTK_ROOT_CANARY_ANCHOR_LIBNAME)
+    ctk_root: str | None = resolve_ctk_root_via_canary(CTK_ROOT_CANARY_ANCHOR_LIBNAMES[0])
     return ctk_root
 
 
 def _resolve_in_trusted_dirs(normalized_name: str, dirs: list[str]) -> str | None:
-    """Resolve ``normalized_name`` against ``dirs`` only, in order.
-
-    Unlike ``shutil.which``, this never consults the current working directory
-    or the ambient ``PATH``. On Windows ``shutil.which`` prepends the process
-    CWD to the search even when an explicit ``path=`` is supplied, which lets a
-    binary sitting in an arbitrary CWD shadow the trusted CUDA / Conda / wheel
-    binary that pathfinder is contracted to discover. Searching the trusted
-    directories explicitly keeps the lookup deterministic and bounded.
-    """
+    """Resolve ``normalized_name`` against ``dirs`` in order."""
     seen: set[str] = set()
     for directory in dirs:
-        if not directory or directory in seen:
+        if directory in seen:
             continue
+        assert directory
         seen.add(directory)
         candidate = os.path.join(directory, normalized_name)
         if _is_executable_file(candidate):
@@ -137,11 +113,8 @@ def find_nvidia_binary_utility(utility_name: str) -> str | None:
         4. **CTK-root canary fallback**
 
            - Only when steps 1-3 miss: resolve the ``cudart`` library through the
-             OS dynamic loader (which honors ``LD_LIBRARY_PATH`` on Linux and the
-             native DLL search on Windows), derive the CUDA Toolkit root from it,
-             and search that root's bin layout. This finds the utility for users
-             who follow the CUDA install guide and set ``LD_LIBRARY_PATH`` for
-             libraries without also setting ``CUDA_HOME`` / ``CUDA_PATH``.
+             OS dynamic loader, derive the CUDA Toolkit root from it, and search
+             that root's bin layout.
 
     Note:
         Results are cached using ``@functools.cache`` for performance. The cache
@@ -152,8 +125,7 @@ def find_nvidia_binary_utility(utility_name: str) -> str | None:
         are identified by the ``X_OK`` (execute) permission bit.
 
         Lookup is restricted to the trusted directories and the canary-derived
-        CTK root listed above; the process working directory and the ambient
-        ``PATH`` are never consulted.
+        CTK root listed above.
 
     Example:
         >>> from cuda.pathfinder import find_nvidia_binary_utility
@@ -187,9 +159,7 @@ def find_nvidia_binary_utility(utility_name: str) -> str | None:
     if found is not None:
         return found
 
-    # 4. CTK-root canary fallback: only when the explicit trusted dirs above
-    #    miss. Resolve cudart via the dynamic loader (honors LD_LIBRARY_PATH),
-    #    derive the toolkit root, and search its bin layout. PATH is never used.
+    # 4. CTK-root canary fallback.
     ctk_root = _resolve_ctk_root_via_canary()
     if ctk_root is not None:
         return _resolve_in_trusted_dirs(normalized_name, _ctk_bin_subdirs(ctk_root))

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/descriptor_catalog.py

@@ -8,6 +8,8 @@
 from dataclasses import dataclass
 from typing import Literal
 
+from cuda.pathfinder._utils.ctk_root_canary import CTK_ROOT_CANARY_ANCHOR_LIBNAMES
+
 PackagedWith = Literal["ctk", "other", "driver"]
 
 
@@ -73,7 +75,7 @@ class DescriptorSpec:
         site_packages_windows=("nvidia/cu13/bin/x86_64", "nvidia/cuda_nvcc/nvvm/bin"),
         anchor_rel_dirs_linux=("nvvm/lib64",),
         anchor_rel_dirs_windows=("nvvm/bin/*", "nvvm/bin"),
-        ctk_root_canary_anchor_libnames=("cudart",),
+        ctk_root_canary_anchor_libnames=CTK_ROOT_CANARY_ANCHOR_LIBNAMES,
     ),
     DescriptorSpec(
         name="cublas",
@@ -291,7 +293,7 @@ class DescriptorSpec:
         site_packages_windows=("nvidia/cu13/bin/x86_64", "nvidia/cuda_cupti/bin"),
         anchor_rel_dirs_linux=("extras/CUPTI/lib64", "lib"),
         anchor_rel_dirs_windows=("extras/CUPTI/lib64", "bin"),
-        ctk_root_canary_anchor_libnames=("cudart",),
+        ctk_root_canary_anchor_libnames=CTK_ROOT_CANARY_ANCHOR_LIBNAMES,
     ),
     DescriptorSpec(
         name="cudla",

cuda_pathfinder/cuda/pathfinder/_headers/find_nvidia_headers.py

@@ -19,6 +19,7 @@
     platform_include_subdirs,
     resolve_conda_anchor,
 )
+from cuda.pathfinder._utils.ctk_root_canary import CTK_ROOT_CANARY_ANCHOR_LIBNAMES
 from cuda.pathfinder._utils.env_vars import get_cuda_path_or_home
 from cuda.pathfinder._utils.find_sub_dirs import find_sub_dirs_all_sitepackages
 
@@ -121,7 +122,7 @@ def find_via_ctk_root_canary(desc: HeaderDescriptor) -> LocatedHeaderDir | None:
     """
     if not desc.use_ctk_root_canary:
         return None
-    canary_abs_path = _resolve_system_loaded_abs_path_in_subprocess("cudart")
+    canary_abs_path = _resolve_system_loaded_abs_path_in_subprocess(CTK_ROOT_CANARY_ANCHOR_LIBNAMES[0])
     if canary_abs_path is None:
         return None
     ctk_root = derive_ctk_root(canary_abs_path)

cuda_pathfinder/cuda/pathfinder/_utils/ctk_root_canary.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+CTK_ROOT_CANARY_ANCHOR_LIBNAMES = ("cudart",)

cuda_pathfinder/docs/source/release/1.6.0-notes.rst

@@ -10,18 +10,9 @@ Highlights
 ----------
 
 * :func:`find_nvidia_binary_utility` now resolves binaries through a bounded,
-  deterministic search of trusted directories instead of ``shutil.which``. The
-  process working directory and the ambient ``PATH`` are never consulted, which
-  closes a lookup ambiguity on Windows where ``shutil.which`` prepends the CWD
-  even when an explicit search path is supplied.
-  (`PR #2196 <https://github.com/NVIDIA/cuda-python/pull/2196>`_)
-
-* :func:`find_nvidia_binary_utility` gains a CTK-root canary fallback. When the
-  NVIDIA wheel, ``CONDA_PREFIX``, and ``CUDA_HOME`` / ``CUDA_PATH`` directories
-  all miss, ``cudart`` is resolved through the OS dynamic loader, which honors
-  ``LD_LIBRARY_PATH`` on Linux and the native DLL search on Windows. The CUDA
-  Toolkit root is derived from that path and its ``bin`` layout is searched.
-  This locates the utility for users who follow the CUDA installation guide and
-  set ``LD_LIBRARY_PATH`` for libraries without also setting ``CUDA_HOME`` /
-  ``CUDA_PATH``, while still never falling back to ``PATH``.
+  deterministic search of trusted directories instead of ``shutil.which`` and
+  gains a CTK-root canary fallback. When the NVIDIA wheel, ``CONDA_PREFIX``, and
+  ``CUDA_HOME`` / ``CUDA_PATH`` directories all miss, ``cudart`` is resolved
+  through the OS dynamic loader, the CUDA Toolkit root is derived from that
+  path, and its ``bin`` layout is searched.
   (`PR #2196 <https://github.com/NVIDIA/cuda-python/pull/2196>`_)

cuda_pathfinder/tests/test_find_nvidia_binaries.py

@@ -304,7 +304,7 @@ def _make_executable(directory, name):
 
     def test_cwd_is_not_searched(self, tmp_path, monkeypatch):
         # Regression for #2119: a binary in the process CWD must never shadow
-        # the trusted directories the way shutil.which does on Windows.
+        # the trusted directories.
         trusted = tmp_path / "trusted"
         trusted.mkdir()
         evil_cwd = tmp_path / "cwd"
@@ -315,7 +315,7 @@ def test_cwd_is_not_searched(self, tmp_path, monkeypatch):
         self._make_executable(evil_cwd, "nvcc")  # the decoy that must be ignored
         monkeypatch.chdir(evil_cwd)
 
-        # The only trusted dir given has no binary -> None, never the CWD copy.
+        # A trusted dir with no binary returns None, never the CWD copy.
         assert binary_finder_module._resolve_in_trusted_dirs("nvcc", [str(empty)]) is None
         # When a trusted dir holds it, that path wins regardless of CWD.
         assert binary_finder_module._resolve_in_trusted_dirs("nvcc", [str(empty), str(trusted)]) == trusted_nvcc
@@ -329,13 +329,17 @@ def test_first_trusted_dir_wins(self, tmp_path):
         self._make_executable(second, "nvcc")
         assert binary_finder_module._resolve_in_trusted_dirs("nvcc", [str(first), str(second)]) == first_nvcc
 
-    def test_empty_and_duplicate_dirs_skipped(self, tmp_path):
+    def test_duplicate_dirs_skipped(self, tmp_path):
         present = tmp_path / "p"
         present.mkdir()
         nvcc = self._make_executable(present, "nvcc")
-        assert binary_finder_module._resolve_in_trusted_dirs("nvcc", ["", str(present), str(present)]) == nvcc
+        assert binary_finder_module._resolve_in_trusted_dirs("nvcc", [str(present), str(present)]) == nvcc
         assert binary_finder_module._resolve_in_trusted_dirs("nvcc", []) is None
 
+    def test_empty_dir_asserts(self):
+        with pytest.raises(AssertionError):
+            binary_finder_module._resolve_in_trusted_dirs("nvcc", [""])
+
     @pytest.mark.skipif(binary_finder_module.IS_WINDOWS, reason="POSIX execute-bit semantics")
     def test_non_executable_file_rejected_on_posix(self, tmp_path):
         directory = tmp_path / "d"