Skip to content

Commit a0a152b

Browse files
authored
fix(pathfinder): return resolved paths for discovered CUDA components (#3418)
* fix(pathfinder): resolve discovered component paths * ci: require manual copy-pr-bot approval * docs(pathfinder): prepare 1.9.0 release notes
1 parent fe9bb74 commit a0a152b

15 files changed

Lines changed: 443 additions & 42 deletions

‎cuda_pathfinder/cuda/pathfinder/_binaries/find_nvidia_binary_utility.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
from cuda.pathfinder._utils.find_sub_dirs import find_sub_dirs_all_sitepackages
1212
from cuda.pathfinder._utils.platform_aware import IS_WINDOWS
1313

14+
from .._utils.resolve_path import resolve_path
15+
1416

1517
class UnsupportedBinaryError(Exception):
1618
def __init__(self, utility: str) -> None:
@@ -55,7 +57,7 @@ def _resolve_candidate_paths(candidates: Iterable[str]) -> str | None:
5557
continue
5658
seen.add(candidate)
5759
if _is_executable_candidate(candidate):
58-
return os.path.abspath(candidate)
60+
return str(resolve_path(candidate))
5961
return None
6062

6163

@@ -85,9 +87,7 @@ def _resolve_in_trusted_dirs(normalized_name: str, dirs: list[str]) -> str | Non
8587
seen.add(directory)
8688
candidate = os.path.join(directory, normalized_name)
8789
if _is_executable_candidate(candidate):
88-
# Return an absolute path, as the docstring promises (a relative
89-
# search dir would otherwise leak a relative result).
90-
return os.path.abspath(candidate)
90+
return str(resolve_path(candidate))
9191
return None
9292

9393

@@ -116,9 +116,9 @@ def find_nvidia_binary_utility(utility_name: str) -> str | None:
116116
also recognizes ``.bat`` and ``.cmd`` files on Windows.
117117
118118
Returns:
119-
str or None: Absolute path to the discovered executable, or ``None``
120-
if the utility cannot be found. The returned path is normalized
121-
(absolute and with resolved separators).
119+
str or None: Resolved absolute path to the discovered executable, or
120+
``None`` if the utility cannot be found. Symlinks and parent-directory
121+
components are resolved to identify the selected executable.
122122
123123
Raises:
124124
UnsupportedBinaryError: If ``utility_name`` is not in the supported set

‎cuda_pathfinder/cuda/pathfinder/_dynamic_libs/search_steps.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@
3131
from cuda.pathfinder._utils.env_vars import get_cuda_path_or_home
3232
from cuda.pathfinder._utils.path_sort import numeric_aware_path_sort_key
3333

34+
from .._utils.resolve_path import resolve_path
35+
3436
# ---------------------------------------------------------------------------
3537
# Data types
3638
# ---------------------------------------------------------------------------
@@ -76,7 +78,7 @@ def _iter_lib_dirs(root: str, rel_dirs: tuple[str, ...]) -> Iterator[str]:
7678
for rel_path in rel_dirs:
7779
for dirname in sorted(glob.glob(os.path.join(root, rel_path))):
7880
if os.path.isdir(dirname):
79-
yield os.path.normpath(dirname)
81+
yield str(resolve_path(dirname))
8082

8183

8284
def _iter_lib_dirs_using_anchor(
@@ -247,7 +249,7 @@ def find_in_program_files_roots(ctx: SearchContext) -> FindResult | None:
247249
for root in sorted(glob.glob(root_glob), key=numeric_aware_path_sort_key, reverse=True):
248250
if not os.path.isdir(root):
249251
continue
250-
result = _find_under_anchor_root(ctx, os.path.normpath(root), "ProgramFiles")
252+
result = _find_under_anchor_root(ctx, str(resolve_path(root)), "ProgramFiles")
251253
if result is not None:
252254
return result
253255
return None

‎cuda_pathfinder/cuda/pathfinder/_headers/find_nvidia_headers.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@
2525
from cuda.pathfinder._utils.find_sub_dirs import find_sub_dirs_all_sitepackages
2626
from cuda.pathfinder._utils.path_sort import numeric_aware_path_sort_key
2727

28+
from .._utils.resolve_path import resolve_path
29+
2830
if TYPE_CHECKING:
2931
from cuda.pathfinder._headers.header_descriptor import HeaderDescriptor
3032

@@ -52,7 +54,7 @@ def __post_init__(self) -> None:
5254

5355
def _abs_norm(path: str | None) -> str | None:
5456
if path:
55-
return os.path.normpath(os.path.abspath(path))
57+
return str(resolve_path(path))
5658
return None
5759

5860

@@ -195,7 +197,7 @@ def locate_nvidia_header_directory(libname: str) -> LocatedHeaderDir | None:
195197
(e.g., ``"nvrtc"``, ``"cusolver"``, ``"nvshmem"``).
196198
197199
Returns:
198-
LocatedHeaderDir or None: A LocatedHeaderDir object containing the absolute path
200+
LocatedHeaderDir or None: A LocatedHeaderDir object containing the resolved absolute path
199201
to the discovered header directory and information about where it was found,
200202
or ``None`` if the headers cannot be found.
201203
@@ -225,7 +227,7 @@ def find_nvidia_header_directory(libname: str) -> str | None:
225227
(e.g., ``"nvrtc"``, ``"cusolver"``, ``"nvshmem"``).
226228
227229
Returns:
228-
str or None: Absolute path to the discovered header directory, or ``None``
230+
str or None: Resolved absolute path to the discovered header directory, or ``None``
229231
if the headers cannot be found.
230232
231233
Raises:

‎cuda_pathfinder/cuda/pathfinder/_static_libs/find_bitcode_lib.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@
1111
from cuda.pathfinder._utils.find_sub_dirs import find_sub_dirs_all_sitepackages
1212
from cuda.pathfinder._utils.platform_aware import IS_WINDOWS
1313

14+
from .._utils.resolve_path import resolve_path
15+
1416

1517
class BitcodeLibNotFoundError(RuntimeError):
1618
"""Raised when a bitcode library cannot be found."""
@@ -95,7 +97,7 @@ def try_site_packages(self) -> Path | None:
9597
for abs_dir in find_sub_dirs_all_sitepackages(sub_dir):
9698
file_path = Path(abs_dir, self.filename)
9799
if file_path.is_file():
98-
return file_path
100+
return resolve_path(file_path)
99101
return None
100102

101103
def try_with_conda_prefix(self) -> Path | None:
@@ -106,7 +108,7 @@ def try_with_conda_prefix(self) -> Path | None:
106108
anchor = Path(conda_prefix, "Library") if IS_WINDOWS else Path(conda_prefix)
107109
file_path = anchor / self.rel_path / self.filename
108110
if file_path.is_file():
109-
return file_path
111+
return resolve_path(file_path)
110112
return None
111113

112114
def try_with_cuda_home(self) -> Path | None:
@@ -118,7 +120,7 @@ def try_with_cuda_home(self) -> Path | None:
118120
anchor = Path(cuda_home)
119121
file_path = anchor / self.rel_path / self.filename
120122
if file_path.is_file():
121-
return file_path
123+
return resolve_path(file_path)
122124

123125
_no_such_file_in_dir(
124126
anchor / self.rel_path,
@@ -135,7 +137,7 @@ def raise_not_found_error(self) -> NoReturn:
135137

136138

137139
def locate_bitcode_lib(name: str) -> LocatedBitcodeLib:
138-
"""Locate a bitcode library by name.
140+
"""Locate a bitcode library by name, returning its resolved absolute path.
139141
140142
Raises:
141143
ValueError: If ``name`` is not a supported bitcode library.
@@ -175,7 +177,7 @@ def locate_bitcode_lib(name: str) -> LocatedBitcodeLib:
175177

176178
@functools.cache
177179
def find_bitcode_lib(name: str) -> str:
178-
"""Find the absolute path to a bitcode library.
180+
"""Find the resolved absolute path to a bitcode library.
179181
180182
Raises:
181183
ValueError: If ``name`` is not a supported bitcode library.

‎cuda_pathfinder/cuda/pathfinder/_static_libs/find_static_lib.py‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
from cuda.pathfinder._utils.platform_aware import IS_WINDOWS
1313
from cuda.pathfinder._utils.windows_arch import windows_python_arch
1414

15+
from .._utils.resolve_path import resolve_path
16+
1517

1618
class StaticLibNotFoundError(RuntimeError):
1719
"""Raised when a static library cannot be found."""
@@ -92,7 +94,7 @@ def try_site_packages(self) -> Path | None:
9294
for abs_dir in find_sub_dirs_all_sitepackages(sub_dir):
9395
file_path = Path(abs_dir, self.filename)
9496
if file_path.is_file():
95-
return file_path
97+
return resolve_path(file_path)
9698
return None
9799

98100
def try_with_conda_prefix(self) -> Path | None:
@@ -104,7 +106,7 @@ def try_with_conda_prefix(self) -> Path | None:
104106
for rel_path in self.conda_rel_paths:
105107
file_path = anchor / rel_path / self.filename
106108
if file_path.is_file():
107-
return file_path
109+
return resolve_path(file_path)
108110
return None
109111

110112
def try_with_cuda_home(self) -> Path | None:
@@ -117,7 +119,7 @@ def try_with_cuda_home(self) -> Path | None:
117119
for rel_path in self.ctk_rel_paths:
118120
file_path = anchor / rel_path / self.filename
119121
if file_path.is_file():
120-
return file_path
122+
return resolve_path(file_path)
121123

122124
_no_such_file_in_dir(
123125
anchor / self.ctk_rel_paths[0],
@@ -134,7 +136,7 @@ def raise_not_found_error(self) -> NoReturn:
134136

135137

136138
def locate_static_lib(name: str) -> LocatedStaticLib:
137-
"""Locate a static library by name.
139+
"""Locate a static library by name, returning its resolved absolute path.
138140
139141
Raises:
140142
ValueError: If ``name`` is not a supported static library.
@@ -174,7 +176,7 @@ def locate_static_lib(name: str) -> LocatedStaticLib:
174176

175177
@functools.cache
176178
def find_static_lib(name: str) -> str:
177-
"""Find the absolute path to a static library.
179+
"""Find the resolved absolute path to a static library.
178180
179181
Raises:
180182
ValueError: If ``name`` is not a supported static library.
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
import os
5+
from pathlib import Path
6+
7+
8+
def resolve_path(*parts: str | os.PathLike[str]) -> Path:
9+
"""Build a canonical absolute path, resolving symlinks and parent components."""
10+
return Path(*parts).resolve()

‎cuda_pathfinder/docs/nv-versions.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
"version": "latest",
44
"url": "https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/"
55
},
6+
{
7+
"version": "1.9.0",
8+
"url": "https://nvidia.github.io/cuda-python/cuda-pathfinder/1.9.0/"
9+
},
610
{
711
"version": "1.8.6",
812
"url": "https://nvidia.github.io/cuda-python/cuda-pathfinder/1.8.6/"

‎cuda_pathfinder/docs/source/api.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,13 @@ The ``cuda.pathfinder`` module provides utilities for loading NVIDIA dynamic lib
1010
locating NVIDIA C/C++ header directories, finding CUDA binary utilities, and locating
1111
CUDA bitcode and static libraries.
1212

13+
Header, binary-utility, bitcode-library, and static-library lookups return
14+
resolved absolute paths. Symlinks and parent-directory components (``..``)
15+
are resolved using the filesystem, so the returned path identifies the
16+
selected component even when a configured root contains a symlink followed
17+
by ``..``. Cached results retain the resolved path selected by the first
18+
lookup. Public path values remain strings.
19+
1320
.. NOTE: The source of truth for public APIs is cuda_pathfinder/cuda/pathfinder/__init__.py.
1421
.. Keep this documentation in sync when adding or removing exports.
1522
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
.. SPDX-License-Identifier: Apache-2.0
3+
4+
.. py:currentmodule:: cuda.pathfinder
5+
6+
``cuda-pathfinder`` 1.9.0 Release notes
7+
=======================================
8+
9+
Compatibility note
10+
------------------
11+
12+
Header, binary utility, static library, and bitcode library lookups now return
13+
resolved absolute paths. Symlinks are followed, so returned paths can differ
14+
from the configured alias, including the basename of a symlinked file.
15+
The ``filename`` fields of :class:`LocatedStaticLib` and
16+
:class:`LocatedBitcodeLib` continue to report the filename searched for.
17+
Public return types, search order, and cache lifetimes are unchanged.
18+
This minor release reflects the intentional change in returned path spelling.
19+
20+
Bugfixes
21+
--------
22+
23+
* Return absolute static-library and bitcode-library paths for relative wheel,
24+
Conda, and CUDA Toolkit roots, keeping cached results valid after a change
25+
of working directory. Resolve Windows drive-relative roots such as
26+
``D:toolkit`` correctly, including on Python 3.11.
27+
(`Issue #3363 <https://github.com/NVIDIA/cuda-python/issues/3363>`_,
28+
`PR #3418 <https://github.com/NVIDIA/cuda-python/pull/3418>`_)
29+
30+
* Preserve the filesystem meaning of roots containing a symlink followed by
31+
``..``. Header and binary utility lookups return the selected component's
32+
resolved path, and dynamic-library directory discovery no longer collapses
33+
these roots lexically into a different location.
34+
(`Issue #3413 <https://github.com/NVIDIA/cuda-python/issues/3413>`_,
35+
`PR #3418 <https://github.com/NVIDIA/cuda-python/pull/3418>`_)

‎cuda_pathfinder/tests/test_find_bitcode_lib.py‎

Lines changed: 85 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,8 +85,7 @@ def test_locate_bitcode_lib(info_summary_append, libname):
8585
_located_bitcode_lib_asserts(located_lib)
8686
assert Path(lib_path).is_file()
8787
assert lib_path == located_lib.abs_path
88-
expected_filename = located_lib.filename
89-
assert Path(lib_path).name == expected_filename
88+
assert located_lib.filename == _bitcode_lib_filename(libname)
9089

9190

9291
@pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
@@ -135,6 +134,90 @@ def find_expected_sub_dir(sub_dir):
135134
assert located_lib.found_via == "CUDA_PATH"
136135

137136

137+
@pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
138+
@pytest.mark.parametrize("source", ("site-packages", "conda", "CUDA_PATH"))
139+
@pytest.mark.agent_authored(model="gpt-6")
140+
def test_locate_bitcode_lib_returns_resolved_path_for_relative_root(monkeypatch, tmp_path, source):
141+
monkeypatch.chdir(tmp_path)
142+
monkeypatch.delenv("CONDA_PREFIX", raising=False)
143+
monkeypatch.delenv("CUDA_HOME", raising=False)
144+
monkeypatch.delenv("CUDA_PATH", raising=False)
145+
146+
info = _bitcode_lib_info("device")
147+
root = Path("relative-root")
148+
if source == "site-packages":
149+
lib_dir = root / Path(info["site_packages_dirs"][0])
150+
monkeypatch.setattr(find_bitcode_lib_module, "find_sub_dirs_all_sitepackages", lambda _sub_dir: [str(lib_dir)])
151+
else:
152+
monkeypatch.setattr(find_bitcode_lib_module, "find_sub_dirs_all_sitepackages", lambda _sub_dir: [])
153+
if source == "conda":
154+
monkeypatch.setenv("CONDA_PREFIX", str(root))
155+
lib_dir = _conda_anchor(root) / Path(info["rel_path"])
156+
else:
157+
monkeypatch.setenv("CUDA_HOME", str(root))
158+
lib_dir = root / Path(info["rel_path"])
159+
160+
expected = (tmp_path / lib_dir / info["filename"]).resolve()
161+
expected.parent.mkdir(parents=True)
162+
expected.touch()
163+
located = locate_bitcode_lib("device")
164+
assert located.found_via == source
165+
assert located.abs_path == str(expected)
166+
assert find_bitcode_lib("device") == str(expected)
167+
168+
monkeypatch.chdir(tmp_path.parent)
169+
assert Path(located.abs_path).is_file()
170+
assert Path(find_bitcode_lib("device")).is_file()
171+
172+
173+
@pytest.mark.skipif(os.name == "nt", reason="POSIX symlink parent traversal")
174+
@pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
175+
@pytest.mark.agent_authored(model="gpt-6")
176+
def test_locate_bitcode_lib_preserves_symlink_parent(monkeypatch, tmp_path):
177+
monkeypatch.chdir(tmp_path)
178+
monkeypatch.delenv("CONDA_PREFIX", raising=False)
179+
monkeypatch.delenv("CUDA_PATH", raising=False)
180+
monkeypatch.setenv("CUDA_HOME", "alias/..")
181+
monkeypatch.setattr(find_bitcode_lib_module, "find_sub_dirs_all_sitepackages", lambda _sub_dir: [])
182+
183+
real_root = tmp_path / "real"
184+
(real_root / "child").mkdir(parents=True)
185+
(tmp_path / "alias").symlink_to(real_root / "child", target_is_directory=True)
186+
info = _bitcode_lib_info("device")
187+
expected = real_root / info["rel_path"] / info["filename"]
188+
expected.parent.mkdir(parents=True)
189+
expected.touch()
190+
191+
located = locate_bitcode_lib("device")
192+
assert located.abs_path == str(expected.resolve())
193+
cached = find_bitcode_lib("device")
194+
monkeypatch.chdir(tmp_path.parent)
195+
assert cached == str(expected.resolve())
196+
assert find_bitcode_lib("device") == cached
197+
198+
199+
@pytest.mark.skipif(os.name == "nt", reason="Symlink creation requires privileges on Windows")
200+
@pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
201+
@pytest.mark.agent_authored(model="gpt-6")
202+
def test_locate_bitcode_lib_resolves_symlinked_file(monkeypatch, tmp_path):
203+
monkeypatch.delenv("CONDA_PREFIX", raising=False)
204+
monkeypatch.delenv("CUDA_PATH", raising=False)
205+
monkeypatch.setattr(find_bitcode_lib_module, "find_sub_dirs_all_sitepackages", lambda _sub_dir: [])
206+
root = tmp_path / "toolkit"
207+
monkeypatch.setenv("CUDA_HOME", str(root))
208+
info = _bitcode_lib_info("device")
209+
target = tmp_path / "actual-library"
210+
target.touch()
211+
candidate = root / info["rel_path"] / info["filename"]
212+
candidate.parent.mkdir(parents=True)
213+
candidate.symlink_to(target)
214+
215+
located = locate_bitcode_lib("device")
216+
assert located.abs_path == str(target.resolve())
217+
assert located.filename == info["filename"]
218+
assert find_bitcode_lib("device") == located.abs_path
219+
220+
138221
@pytest.mark.usefixtures("clear_find_bitcode_lib_cache")
139222
def test_find_bitcode_lib_not_found_error_includes_cuda_home_directory_listing(monkeypatch, tmp_path):
140223
cuda_home = tmp_path / "cuda-home"

0 commit comments

Comments
 (0)