Use cuda-pathfinder in build-system.requires

[rwgk]

Follow-up to #1801. Closes the build-time integration gap identified in #1803.

The build hooks in cuda_bindings and cuda_core now use cuda.pathfinder.get_cuda_path_or_home() to resolve CUDA_PATH/CUDA_HOME, replacing the previous inline os.environ.get() fallback.

This firmly establishes that cuda-pathfinder is usable as a tool at build time, not just at runtime, although a helper function (_import_get_cuda_path_or_home()) is needed because cuda is a Python namespace package; see #1824 for details.

• Pin cuda-pathfinder>=1.5 in both build-system.requires and project.dependencies for cuda_bindings and cuda_core.
• Namespace fix for PEP 517 isolated builds: In isolated build environments, backend-path=["."] causes the cuda namespace to shadow the installed cuda-pathfinder. The new _import_get_cuda_path_or_home() helper detects this and fixes cuda.__path__ by replacing the _NamespacePath with a plain list that includes the site-packages cuda/ directory.
• Test updates: cuda_core/tests/test_build_hooks.py adds get_cuda_path_or_home.cache_clear() calls so monkeypatched env vars take effect.
• Stale pixi version: Updated cuda_pathfinder/pixi.toml package version from 1.3.4a0 to 1.5.0 (just to avoid confusing someone looking at the version in passing).

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[rwgk]

/ok to test

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-1817/
https://nvidia.github.io/cuda-python/pr-preview/pr-1817/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-1817/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-1817/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[rparolin]

We should avoid duplicating implementations. Could we not hoist this into a separate file and import from both?

[rwgk]

We should avoid duplicating implementations.

Agreed

Could we not hoist this into a separate file and import from both?

No 😭

---

In the words of Cursor Opus 4.6 1M Thinking:

There's no reasonable way to share code between the two build_hooks.py files:

• Each is a PEP 517 build backend loaded via backend-path=["."] from its own package directory (cuda_bindings/ or cuda_core/). They can't import from the monorepo root or from each other.
• The function exists because cuda.pathfinder can't be imported normally in this context — so it can't live inside cuda-pathfinder either.
• A shared helper package in build-system.requires would be massive overkill for ~15 lines of stable code.

The only alternatives are worse: a new PyPI package just for this, importlib file-path hacks, or copying a shared file into both directories at CI time.

The "please keep in sync" comments are the pragmatic solution here.

[rwgk]

We have other existing cases of "please keep in sync" that are impractical to avoid.

It just crossed my mind: a pre-commit check to enforce that they stay in sync is probably pretty easy to implement.

[rparolin]

Should we include some message explaining that we iterated through sys.path looking for pathfinder and couldn't find it? That seems to be important information that would be missing from just throwing we couldn't import pathfinder module.

[rparolin]

          for p in sys.path:
              sp_cuda = os.path.join(p, "cuda")                                                                                
              if os.path.isdir(os.path.join(sp_cuda, "pathfinder")):
                  cuda.__path__ = list(cuda.__path__) + [sp_cuda]                                                              
                  break                 
          else:                                                                                                                
              raise ModuleNotFoundError(
                  "cuda-pathfinder is not installed in the build environment. "                                                
                  "Ensure 'cuda-pathfinder>=1.5' is in build-system.requires."                                                 
              )
          import cuda.pathfinder ```

[rwgk]

Done: commit 3d422de

[cpcloud]

The path hacking needs some more justification and explicit examples of in what common scenarios a plain import isn't going to work.

[cpcloud]

Path hacking of any sort like this is a code smell. At the very least the docstring is missing a concrete example of why this is needed.

isolated build environments

is doing a ton of work there. Isolated how? What is backend-path and where does that come from? Where are all these nouns like backend-path and build-env coming from?

In what real-world scenarios does this actually happen where there's not a viable alternative?

I'm really skeptical that path hacking like this is necessary.

[rwgk]

It's fully documented now here: #1824 (that in turn is pointing to #1803, where you can see the original development history for the workaround)

The comment here was updated:

commit 6892ae0

[cpcloud]

Main concern: this workaround solves one specific PEP 517 shadowing scenario by mutating global namespace-package state (cuda.__path__). That is risky in a build backend because the rest of the process now sees a different import model depending on whether this helper has already run.

The two concrete issues I see are:

1. except ModuleNotFoundError is broad enough to catch real import failures inside cuda.pathfinder, so a broken dependency/import in that package can be misdiagnosed as namespace shadowing.
2. Replacing importlib's _NamespacePath with a plain list and appending the first cuda/pathfinder hit from sys.path makes the selected package "sticky" for the rest of the process and depends on path ordering heuristics.

I'm commenting on the cuda_bindings copy only to avoid duplication, but the same concerns apply to the mirrored helper in cuda_core.

[cpcloud]

This except ModuleNotFoundError is too broad: it will also catch ModuleNotFoundErrors raised from inside cuda.pathfinder itself. If cuda.pathfinder is installed but one of its own imports is broken, we silently reinterpret that as the namespace-shadowing case and take the workaround path.

I'd narrow the fallback to the exact failure we expect here:

try:
    from cuda.pathfinder import get_cuda_path_or_home
    return get_cuda_path_or_home
except ModuleNotFoundError as exc:
    if exc.name != "cuda.pathfinder":
        raise

That preserves the real traceback for genuine cuda.pathfinder import bugs and keeps the workaround limited to the cuda.pathfinder-not-found case.

[cpcloud]

Mutating cuda.__path__ here permanently changes namespace resolution for the rest of the backend process, and it selects whichever cuda/pathfinder directory happens to appear first on sys.path. That's pretty fragile.

If we keep this overall approach, I think the safer version is to resolve the installed cuda-pathfinder distribution explicitly and append only that exact cuda/ directory, instead of scanning sys.path:

from importlib import metadata
from pathlib import Path

# after narrowing the ModuleNotFoundError as above
import cuda

dist = metadata.distribution("cuda-pathfinder")
site_cuda = str(dist.locate_file(Path("cuda")))
cuda_paths = list(cuda.__path__)
if site_cuda not in cuda_paths:
    cuda.__path__ = cuda_paths + [site_cuda]

from cuda.pathfinder import get_cuda_path_or_home
return get_cuda_path_or_home

That still uses the namespace workaround, but it removes the sys.path guesswork.

If you'd rather avoid cuda.__path__ mutation entirely, another option is to load cuda/pathfinder/_utils/env_vars.py directly from the installed distribution under a private module name and call get_cuda_path_or_home() from there. That file is stdlib-only today, so it avoids rewriting namespace-package state.