Cythonize _program.py (#1565)

* Begin Cythonization of _program.py

- Rename _program.py to _program.pyx
- Convert Program to cdef class with _program.pxd declarations
- Extract _MembersNeededForFinalize to module-level _ProgramMNFF
  (nested classes not allowed in cdef class)
- Add __repr__ method to Program
- Keep ProgramOptions as @DataClass (unchanged)
- Keep weakref.finalize pattern for handle cleanup

* Extract Program helpers to module-level cdef functions

- Move _translate_program_options to Program_translate_options (cdef)
- Move _can_load_generated_ptx to Program_can_load_generated_ptx (cdef)
- Remove unused TYPE_CHECKING import block
- Follow _memory/_buffer.pyx helper function patterns

* Complete Cythonization of _program.py

- Reorganize file structure per developer guide (principal class first)
- Add module docstring, __all__, type alias section
- Factor long methods into cdef inline helpers
- Add proper exception specs to cdef functions
- Fix docstrings (use :class: refs, public paths)
- Add type annotations to public methods
- Inline _nvvm_exception_manager (single use)
- Remove Union import, use | syntax
- Add public Program.driver_can_load_nvrtc_ptx_output() API
- Update tests to use new public API

Closes #1082

* Extend test_object_protocols.py with Program and ObjectCode variations

Add fixtures for different Program backends (NVRTC, PTX, NVVM) and
ObjectCode code types (cubin, PTX, LTOIR). Split API_TYPES into more
precise HASH_TYPES, EQ_TYPES, and WEAKREF_TYPES lists. Derive
DICT_KEY_TYPES and WEAK_KEY_TYPES for collection tests.

* Add NVRTC/NVVM resource handles and remove Program MNFF

- Add NvrtcProgramHandle and NvvmProgramHandle to resource handles module
- Add function pointer initialization for nvrtcDestroyProgram and nvvmDestroyProgram
- Forward-declare nvvmProgram to avoid nvvm.h dependency
- Refactor detail::make_py to accept module name parameter
- Remove _ProgramMNFF class from _program.pyx
- Program now uses typed handles directly with RAII cleanup
- Update handle property to return None when handle is null

* Add HANDLE_RETURN_NVRTC and HANDLE_RETURN_NVVM, simplify HANDLE_RETURN

- Add NVVMError exception class
- Add HANDLE_RETURN_NVRTC for nogil NVRTC error handling with program log
- Add HANDLE_RETURN_NVVM for nogil NVVM error handling with program log
- Remove vestigial supported_error_type fused type
- Simplify HANDLE_RETURN to directly take cydriver.CUresult

* Fix build errors, update tests, remove unused imports

- Change cdef function return types from ObjectCode to object (Cython limitation)
- Remove unused imports: intptr_t, NvrtcProgramHandle, NvvmProgramHandle, as_intptr
- Update as_py(NvvmProgramHandle) to return Python int via PyLong_FromSsize_t
- Update test assertions: remove handle checks after close(), test idempotency instead
- Update NVVM error message regex to match new unified format

* Address review feedback: keep _can_load_generated_ptx private, update SPDX dates

- Remove Program.driver_can_load_nvrtc_ptx_output() public static method
- Make _can_load_generated_ptx a cpdef (callable from Python tests)
- Update tests to import _can_load_generated_ptx from cuda.core._program
- Update SPDX copyright years to 2024-2026 for files with 2024-2025
- Update get_kernel docstring: name parameter is str | bytes

Co-authored-by: Cursor <cursoragent@cursor.com>

* Address review feedback: NVVMError inherits from nvvmError, clean up error helpers

- Make NVVMError inherit from cuda.bindings.nvvm.nvvmError for compatibility
  with code catching nvvmError, while also inheriting from CUDAError
- Simplify HANDLE_RETURN_NVRTC and HANDLE_RETURN_NVVM to just check success
  and delegate to helper functions
- Move all error handling logic into _raise_nvrtc_error and _raise_nvvm_error

Co-authored-by: Cursor <cursoragent@cursor.com>

* Add 0.6.x release notes with cuda-bindings build requirement change

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Andy-Jost

cuda_core/cuda/core/_cpp/resource_handles.cpp

@@ -56,6 +56,12 @@ decltype(&cuLibraryLoadData) p_cuLibraryLoadData = nullptr;
 decltype(&cuLibraryUnload) p_cuLibraryUnload = nullptr;
 decltype(&cuLibraryGetKernel) p_cuLibraryGetKernel = nullptr;
 
+// NVRTC function pointers
+decltype(&nvrtcDestroyProgram) p_nvrtcDestroyProgram = nullptr;
+
+// NVVM function pointers (may be null if NVVM is not available)
+NvvmDestroyProgramFn p_nvvmDestroyProgram = nullptr;
+
 // ============================================================================
 // GIL management helpers
 // ============================================================================
@@ -764,4 +770,64 @@ KernelHandle create_kernel_handle_ref(CUkernel kernel, const LibraryHandle& h_li
     return KernelHandle(box, &box->resource);
 }
 
+// ============================================================================
+// NVRTC Program Handles
+// ============================================================================
+
+namespace {
+struct NvrtcProgramBox {
+    nvrtcProgram resource;
+};
+}  // namespace
+
+NvrtcProgramHandle create_nvrtc_program_handle(nvrtcProgram prog) {
+    auto box = std::shared_ptr<NvrtcProgramBox>(
+        new NvrtcProgramBox{prog},
+        [](NvrtcProgramBox* b) {
+            // Note: nvrtcDestroyProgram takes nvrtcProgram* and nulls it,
+            // but we're deleting the box anyway so nulling is harmless.
+            // Errors are ignored (standard destructor practice).
+            p_nvrtcDestroyProgram(&b->resource);
+            delete b;
+        }
+    );
+    return NvrtcProgramHandle(box, &box->resource);
+}
+
+NvrtcProgramHandle create_nvrtc_program_handle_ref(nvrtcProgram prog) {
+    auto box = std::make_shared<NvrtcProgramBox>(NvrtcProgramBox{prog});
+    return NvrtcProgramHandle(box, &box->resource);
+}
+
+// ============================================================================
+// NVVM Program Handles
+// ============================================================================
+
+namespace {
+struct NvvmProgramBox {
+    nvvmProgram resource;
+};
+}  // namespace
+
+NvvmProgramHandle create_nvvm_program_handle(nvvmProgram prog) {
+    auto box = std::shared_ptr<NvvmProgramBox>(
+        new NvvmProgramBox{prog},
+        [](NvvmProgramBox* b) {
+            // Note: nvvmDestroyProgram takes nvvmProgram* and nulls it,
+            // but we're deleting the box anyway so nulling is harmless.
+            // If NVVM is not available, the function pointer is null.
+            if (p_nvvmDestroyProgram) {
+                p_nvvmDestroyProgram(&b->resource);
+            }
+            delete b;
+        }
+    );
+    return NvvmProgramHandle(box, &box->resource);
+}
+
+NvvmProgramHandle create_nvvm_program_handle_ref(nvvmProgram prog) {
+    auto box = std::make_shared<NvvmProgramBox>(NvvmProgramBox{prog});
+    return NvvmProgramHandle(box, &box->resource);
+}
+
 }  // namespace cuda_core

cuda_core/cuda/core/_cpp/resource_handles.hpp

@@ -6,9 +6,14 @@
 
 #include <Python.h>
 #include <cuda.h>
+#include <nvrtc.h>
 #include <cstdint>
 #include <memory>
 
+// Forward declaration for NVVM - avoids nvvm.h dependency
+// Use void* to match cuda.bindings.cynvvm's typedef
+using nvvmProgram = void*;
+
 namespace cuda_core {
 
 // ============================================================================
@@ -67,6 +72,28 @@ extern decltype(&cuLibraryLoadData) p_cuLibraryLoadData;
 extern decltype(&cuLibraryUnload) p_cuLibraryUnload;
 extern decltype(&cuLibraryGetKernel) p_cuLibraryGetKernel;
 
+// ============================================================================
+// NVRTC function pointers
+//
+// These are populated by _resource_handles.pyx at module import time using
+// function pointers extracted from cuda.bindings.cynvrtc.__pyx_capi__.
+// ============================================================================
+
+extern decltype(&nvrtcDestroyProgram) p_nvrtcDestroyProgram;
+
+// ============================================================================
+// NVVM function pointers
+//
+// These are populated by _resource_handles.pyx at module import time using
+// function pointers extracted from cuda.bindings.cynvvm.__pyx_capi__.
+// Note: May be null if NVVM is not available at runtime.
+// ============================================================================
+
+// Function pointer type for nvvmDestroyProgram (avoids nvvm.h dependency)
+// Signature: nvvmResult nvvmDestroyProgram(nvvmProgram *prog)
+using NvvmDestroyProgramFn = int (*)(nvvmProgram*);
+extern NvvmDestroyProgramFn p_nvvmDestroyProgram;
+
 // ============================================================================
 // Handle type aliases - expose only the raw CUDA resource
 // ============================================================================
@@ -77,6 +104,8 @@ using EventHandle = std::shared_ptr<const CUevent>;
 using MemoryPoolHandle = std::shared_ptr<const CUmemoryPool>;
 using LibraryHandle = std::shared_ptr<const CUlibrary>;
 using KernelHandle = std::shared_ptr<const CUkernel>;
+using NvrtcProgramHandle = std::shared_ptr<const nvrtcProgram>;
+using NvvmProgramHandle = std::shared_ptr<const nvvmProgram>;
 
 // ============================================================================
 // Context handle functions
@@ -260,6 +289,33 @@ KernelHandle create_kernel_handle(const LibraryHandle& h_library, const char* na
 // Use for borrowed kernels. The library handle keeps the library alive.
 KernelHandle create_kernel_handle_ref(CUkernel kernel, const LibraryHandle& h_library);
 
+// ============================================================================
+// NVRTC Program handle functions
+// ============================================================================
+
+// Create an owning NVRTC program handle.
+// When the last reference is released, nvrtcDestroyProgram is called.
+// Use this to wrap a program created via nvrtcCreateProgram.
+NvrtcProgramHandle create_nvrtc_program_handle(nvrtcProgram prog);
+
+// Create a non-owning NVRTC program handle (references existing program).
+// The program will NOT be destroyed when the handle is released.
+NvrtcProgramHandle create_nvrtc_program_handle_ref(nvrtcProgram prog);
+
+// ============================================================================
+// NVVM Program handle functions
+// ============================================================================
+
+// Create an owning NVVM program handle.
+// When the last reference is released, nvvmDestroyProgram is called.
+// Use this to wrap a program created via nvvmCreateProgram.
+// Note: If NVVM is not available (p_nvvmDestroyProgram is null), the deleter is a no-op.
+NvvmProgramHandle create_nvvm_program_handle(nvvmProgram prog);
+
+// Create a non-owning NVVM program handle (references existing program).
+// The program will NOT be destroyed when the handle is released.
+NvvmProgramHandle create_nvvm_program_handle_ref(nvvmProgram prog);
+
 // ============================================================================
 // Overloaded helper functions to extract raw resources from handles
 // ============================================================================
@@ -293,6 +349,14 @@ inline CUkernel as_cu(const KernelHandle& h) noexcept {
     return h ? *h : nullptr;
 }
 
+inline nvrtcProgram as_cu(const NvrtcProgramHandle& h) noexcept {
+    return h ? *h : nullptr;
+}
+
+inline nvvmProgram as_cu(const NvvmProgramHandle& h) noexcept {
+    return h ? *h : nullptr;
+}
+
 // as_intptr() - extract handle as intptr_t for Python interop
 // Using signed intptr_t per C standard convention and issue #1342
 inline std::intptr_t as_intptr(const ContextHandle& h) noexcept {
@@ -323,11 +387,19 @@ inline std::intptr_t as_intptr(const KernelHandle& h) noexcept {
     return reinterpret_cast<std::intptr_t>(as_cu(h));
 }
 
-// as_py() - convert handle to Python driver wrapper object (returns new reference)
+inline std::intptr_t as_intptr(const NvrtcProgramHandle& h) noexcept {
+    return reinterpret_cast<std::intptr_t>(as_cu(h));
+}
+
+inline std::intptr_t as_intptr(const NvvmProgramHandle& h) noexcept {
+    return reinterpret_cast<std::intptr_t>(as_cu(h));
+}
+
+// as_py() - convert handle to Python wrapper object (returns new reference)
 namespace detail {
 // n.b. class lookup is not cached to avoid deadlock hazard, see DESIGN.md
-inline PyObject* make_py(const char* class_name, std::intptr_t value) noexcept {
-    PyObject* mod = PyImport_ImportModule("cuda.bindings.driver");
+inline PyObject* make_py(const char* module_name, const char* class_name, std::intptr_t value) noexcept {
+    PyObject* mod = PyImport_ImportModule(module_name);
     if (!mod) return nullptr;
     PyObject* cls = PyObject_GetAttrString(mod, class_name);
     Py_DECREF(mod);
@@ -339,31 +411,40 @@ inline PyObject* make_py(const char* class_name, std::intptr_t value) noexcept {
 }  // namespace detail
 
 inline PyObject* as_py(const ContextHandle& h) noexcept {
-    return detail::make_py("CUcontext", as_intptr(h));
+    return detail::make_py("cuda.bindings.driver", "CUcontext", as_intptr(h));
 }
 
 inline PyObject* as_py(const StreamHandle& h) noexcept {
-    return detail::make_py("CUstream", as_intptr(h));
+    return detail::make_py("cuda.bindings.driver", "CUstream", as_intptr(h));
 }
 
 inline PyObject* as_py(const EventHandle& h) noexcept {
-    return detail::make_py("CUevent", as_intptr(h));
+    return detail::make_py("cuda.bindings.driver", "CUevent", as_intptr(h));
 }
 
 inline PyObject* as_py(const MemoryPoolHandle& h) noexcept {
-    return detail::make_py("CUmemoryPool", as_intptr(h));
+    return detail::make_py("cuda.bindings.driver", "CUmemoryPool", as_intptr(h));
 }
 
 inline PyObject* as_py(const DevicePtrHandle& h) noexcept {
-    return detail::make_py("CUdeviceptr", as_intptr(h));
+    return detail::make_py("cuda.bindings.driver", "CUdeviceptr", as_intptr(h));
 }
 
 inline PyObject* as_py(const LibraryHandle& h) noexcept {
-    return detail::make_py("CUlibrary", as_intptr(h));
+    return detail::make_py("cuda.bindings.driver", "CUlibrary", as_intptr(h));
 }
 
 inline PyObject* as_py(const KernelHandle& h) noexcept {
-    return detail::make_py("CUkernel", as_intptr(h));
+    return detail::make_py("cuda.bindings.driver", "CUkernel", as_intptr(h));
+}
+
+inline PyObject* as_py(const NvrtcProgramHandle& h) noexcept {
+    return detail::make_py("cuda.bindings.nvrtc", "nvrtcProgram", as_intptr(h));
+}
+
+inline PyObject* as_py(const NvvmProgramHandle& h) noexcept {
+    // NVVM bindings use raw integers, not wrapper classes
+    return PyLong_FromSsize_t(as_intptr(h));
 }
 
 }  // namespace cuda_core

cuda_core/cuda/core/_module.pyx

@@ -800,7 +800,7 @@ cdef class ObjectCode:
 
         Parameters
         ----------
-        name : Any
+        name : str | bytes
             Name of the kernel to retrieve.
 
         Returns
@@ -816,7 +816,8 @@ cdef class ObjectCode:
         try:
             name = self._sym_map[name]
         except KeyError:
-            name = name.encode()
+            if isinstance(name, str):
+                name = name.encode()
 
         cdef KernelHandle h_kernel = create_kernel_handle(self._h_library, <const char*>name)
         if not h_kernel:

cuda_core/cuda/core/_program.pxd

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from ._resource_handles cimport NvrtcProgramHandle, NvvmProgramHandle
+
+
+cdef class Program:
+    cdef:
+        NvrtcProgramHandle _h_nvrtc
+        NvvmProgramHandle _h_nvvm
+        str _backend
+        object _linker  # Linker
+        object _options  # ProgramOptions
+        object __weakref__