Improve optional CUDA module import handling for NVVM and nvJitLink (#1733)

* fix(core,pathfinder): harden optional NVVM and nvJitLink imports

Add a shared `optional_cuda_import` API in cuda.pathfinder so optional module checks only suppress genuinely unavailable modules or dynamic libs while still surfacing nested import bugs. Wire cuda.core NVVM/nvJitLink detection to this helper and declare cuda-pathfinder as a direct cuda-core dependency.

Made-with: Cursor

* chore(pathfinder): address pre-commit follow-ups

Apply ruff-preferred import ordering in pathfinder exports and rename an unused test lambda argument so repository-wide pre-commit checks pass cleanly.

Made-with: Cursor

* address review feedback for issue 980 PR

Raise the cuda-core dependency floor to cuda-pathfinder>=1.4.2, move the new optional import note to 1.4.2 release notes, and simplify nvJitLink warning text by inlining the fixed version detail.

Made-with: Cursor

Author: cpcloud

cuda_core/cuda/core/_linker.pyx

@@ -29,6 +29,7 @@ from dataclasses import dataclass
 from typing import Union
 from warnings import warn
 
+from cuda.pathfinder import optional_cuda_import
 from cuda.core._device import Device
 from cuda.core._module import ObjectCode
 from cuda.core._utils.clear_error_support import assert_type
@@ -649,23 +650,20 @@ def _decide_nvjitlink_or_driver() -> bool:
         " For best results, consider upgrading to a recent version of"
     )
 
-    try:
-        __import__("cuda.bindings.nvjitlink")  # availability check
-    except ModuleNotFoundError:
+    nvjitlink_module = optional_cuda_import(
+        "cuda.bindings.nvjitlink",
+        probe_function=lambda module: module.version(),  # probe triggers nvJitLink runtime load
+    )
+    if nvjitlink_module is None:
         warn_txt = f"cuda.bindings.nvjitlink is not available, therefore {warn_txt_common} cuda-bindings."
     else:
         from cuda.bindings._internal import nvjitlink
 
-        try:
-            if _nvjitlink_has_version_symbol(nvjitlink):
-                _use_nvjitlink_backend = True
-                return False  # Use nvjitlink
-        except RuntimeError:
-            warn_detail = "not available"
-        else:
-            warn_detail = "too old (<12.3)"
+        if _nvjitlink_has_version_symbol(nvjitlink):
+            _use_nvjitlink_backend = True
+            return False  # Use nvjitlink
         warn_txt = (
-            f"{'nvJitLink*.dll' if sys.platform == 'win32' else 'libnvJitLink.so*'} is {warn_detail}."
+            f"{'nvJitLink*.dll' if sys.platform == 'win32' else 'libnvJitLink.so*'} is too old (<12.3)."
             f" Therefore cuda.bindings.nvjitlink is not usable and {warn_txt_common} nvJitLink."
         )
 

cuda_core/cuda/core/_program.pyx

@@ -14,6 +14,7 @@ import threading
 from warnings import warn
 
 from cuda.bindings import driver, nvrtc
+from cuda.pathfinder import optional_cuda_import
 
 from libcpp.vector cimport vector
 
@@ -461,8 +462,8 @@ class ProgramOptions:
 # =============================================================================
 
 # Module-level state for NVVM lazy loading
-cdef object_nvvm_module = None
-cdef bint _nvvm_import_attempted = False
+_nvvm_module = None
+_nvvm_import_attempted = False
 
 
 def _get_nvvm_module():
@@ -484,18 +485,21 @@ def _get_nvvm_module():
                 "Please update cuda-bindings to use NVVM features."
             )
 
-        from cuda.bindings import nvvm
-        from cuda.bindings._internal.nvvm import _inspect_function_pointer
-
-        if _inspect_function_pointer("__nvvmCreateProgram") == 0:
-            raise RuntimeError("NVVM library (libnvvm) is not available in this Python environment. ")
+        nvvm = optional_cuda_import(
+            "cuda.bindings.nvvm",
+            probe_function=lambda module: module.version(),  # probe triggers libnvvm load
+        )
+        if nvvm is None:
+            raise RuntimeError(
+                "NVVM support is unavailable: cuda.bindings.nvvm is missing or libnvvm cannot be loaded."
+            )
 
         _nvvm_module = nvvm
         return _nvvm_module
 
-    except RuntimeError as e:
+    except RuntimeError:
         _nvvm_module = None
-        raise e
+        raise
 
 def _find_libdevice_path():
     """Find libdevice*.bc for NVVM compilation using cuda.pathfinder."""

cuda_core/docs/source/release/0.7.x-notes.rst

@@ -40,3 +40,6 @@ Fixes and enhancements
   linking operations to the C level and releasing the GIL during backend calls. This benefits
   workloads that create many programs or linkers, and enables concurrent compilation in
   multithreaded applications.
+- Improved optional dependency handling for NVVM and nvJitLink imports so that only genuinely
+  missing optional modules are treated as unavailable; unrelated import failures now surface
+  normally, and ``cuda.core`` now depends directly on ``cuda-pathfinder``.

cuda_core/pixi.lock

@@ -148,6 +148,7 @@ numpy = "*"
 # Using path dependency now that we've added .pth support for Cython .pxd files
 # See build_hooks.py:_add_cython_include_paths_to_pth()
 cuda-bindings = { path = "../cuda_bindings" }
+cuda-pathfinder = { path = "../cuda_pathfinder" }
 
 [target.linux.tasks.build-cython-tests]
 cmd = ["$PIXI_PROJECT_ROOT/tests/cython/build_tests.sh"]

cuda_core/pixi.toml

@@ -47,6 +47,7 @@ classifiers = [
     "Environment :: GPU :: NVIDIA CUDA :: 13",
 ]
 dependencies = [
+    "cuda-pathfinder >=1.4.2",
     "numpy",
 ]