Add _CTK_MAJOR_MINOR_PATCH version guards and DRY up explanation tests (#1712)

Rename explanation dicts to _EXPLANATIONS / _FALLBACK_EXPLANATIONS,
add _CTK_MAJOR_MINOR_PATCH to each module, and enforce that the
cuda_core fallback copy is as new as (and in-sync with) cuda_bindings.
Parametrize the smoke and version-check tests to cover both driver and
runtime without duplication.

Made-with: Cursor

Author: rwgk

cuda_bindings/cuda/bindings/_utils/driver_cu_result_explanations.py

@@ -6,8 +6,9 @@
 # Replace the dictionary below with the output.
 # Also update the CUDA Toolkit version number below.
 
-# CUDA Toolkit v13.2.0
-DRIVER_CU_RESULT_EXPLANATIONS = {
+_CTK_MAJOR_MINOR_PATCH = (13, 2, 0)
+
+_EXPLANATIONS = {
     0: (
         "The API call returned with no errors. In the case of query calls, this"
         " also means that the operation being queried is complete (see"

cuda_bindings/cuda/bindings/_utils/runtime_cuda_error_explanations.py

@@ -6,8 +6,9 @@
 # Replace the dictionary below with the output.
 # Also update the CUDA Toolkit version number below.
 
-# CUDA Toolkit v13.2.0
-RUNTIME_CUDA_ERROR_EXPLANATIONS = {
+_CTK_MAJOR_MINOR_PATCH = (13, 2, 0)
+
+_EXPLANATIONS = {
     0: (
         "The API call returned with no errors. In the case of query calls, this"
         " also means that the operation being queried is complete (see"

cuda_bindings/tests/test_enum_explanations.py

@@ -4,8 +4,7 @@
 import importlib.metadata
 
 from cuda.bindings import driver, runtime
-from cuda.bindings._utils.driver_cu_result_explanations import DRIVER_CU_RESULT_EXPLANATIONS
-from cuda.bindings._utils.runtime_cuda_error_explanations import RUNTIME_CUDA_ERROR_EXPLANATIONS
+from cuda.bindings._utils import driver_cu_result_explanations, runtime_cuda_error_explanations
 
 
 def _get_binding_version():
@@ -17,7 +16,7 @@ def _get_binding_version():
 
 
 def test_driver_cu_result_explanations_health():
-    expl_dict = DRIVER_CU_RESULT_EXPLANATIONS
+    expl_dict = driver_cu_result_explanations._EXPLANATIONS
 
     known_codes = set()
     for error in driver.CUresult:
@@ -31,7 +30,7 @@ def test_driver_cu_result_explanations_health():
 
 
 def test_runtime_cuda_error_explanations_health():
-    expl_dict = RUNTIME_CUDA_ERROR_EXPLANATIONS
+    expl_dict = runtime_cuda_error_explanations._EXPLANATIONS
 
     known_codes = set()
     for error in runtime.cudaError_t:

cuda_core/cuda/core/_utils/driver_cu_result_explanations.py

@@ -2,8 +2,9 @@
 # SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 # Fallback copy -- overridden from cuda.bindings below when available.
-# CUDA Toolkit v13.2.0
-DRIVER_CU_RESULT_EXPLANATIONS = {
+_CTK_MAJOR_MINOR_PATCH = (13, 2, 0)
+
+_FALLBACK_EXPLANATIONS = {
     0: (
         "The API call returned with no errors. In the case of query calls, this"
         " also means that the operation being queried is complete (see"
@@ -353,10 +354,12 @@
     999: "This indicates that an unknown internal error has occurred.",
 }
 
+DRIVER_CU_RESULT_EXPLANATIONS = _FALLBACK_EXPLANATIONS
+
 # Prefer the authoritative copy from cuda.bindings when available.
 try:
     import cuda.bindings._utils.driver_cu_result_explanations as _authoritative
 except ModuleNotFoundError:
     pass
 else:
-    DRIVER_CU_RESULT_EXPLANATIONS = _authoritative.DRIVER_CU_RESULT_EXPLANATIONS
+    DRIVER_CU_RESULT_EXPLANATIONS = _authoritative._EXPLANATIONS

cuda_core/cuda/core/_utils/runtime_cuda_error_explanations.py

@@ -2,8 +2,9 @@
 # SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 # Fallback copy -- overridden from cuda.bindings below when available.
-# CUDA Toolkit v13.2.0
-RUNTIME_CUDA_ERROR_EXPLANATIONS = {
+_CTK_MAJOR_MINOR_PATCH = (13, 2, 0)
+
+_FALLBACK_EXPLANATIONS = {
     0: (
         "The API call returned with no errors. In the case of query calls, this"
         " also means that the operation being queried is complete (see"
@@ -546,10 +547,12 @@
     ),
 }
 
+RUNTIME_CUDA_ERROR_EXPLANATIONS = _FALLBACK_EXPLANATIONS
+
 # Prefer the authoritative copy from cuda.bindings when available.
 try:
     import cuda.bindings._utils.runtime_cuda_error_explanations as _authoritative
 except ModuleNotFoundError:
     pass
 else:
-    RUNTIME_CUDA_ERROR_EXPLANATIONS = _authoritative.RUNTIME_CUDA_ERROR_EXPLANATIONS
+    RUNTIME_CUDA_ERROR_EXPLANATIONS = _authoritative._EXPLANATIONS

cuda_core/tests/test_cuda_utils.py

@@ -3,26 +3,53 @@
 # SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 import dataclasses
+import importlib
 
 import pytest
 
 from cuda.bindings import driver, runtime
 from cuda.core._utils import cuda_utils
 from cuda.core._utils.clear_error_support import assert_type_str_or_bytes_like, raise_code_path_meant_to_be_unreachable
 
+_EXPLANATION_MODULES = [
+    ("driver_cu_result_explanations", "DRIVER_CU_RESULT_EXPLANATIONS"),
+    ("runtime_cuda_error_explanations", "RUNTIME_CUDA_ERROR_EXPLANATIONS"),
+]
 
-def test_driver_cu_result_explanations_smoke():
-    expl = cuda_utils.DRIVER_CU_RESULT_EXPLANATIONS
+
+@pytest.mark.parametrize("module_name,public_name", _EXPLANATION_MODULES)
+def test_explanations_smoke(module_name, public_name):
+    expl = getattr(cuda_utils, public_name)
     for code in (0, 1, 2):
         assert code in expl
         assert isinstance(expl[code], str)
 
 
-def test_runtime_cuda_error_explanations_smoke():
-    expl = cuda_utils.RUNTIME_CUDA_ERROR_EXPLANATIONS
-    for code in (0, 1, 2):
-        assert code in expl
-        assert isinstance(expl[code], str)
+@pytest.mark.parametrize("module_name,public_name", _EXPLANATION_MODULES)
+def test_explanations_ctk_version(module_name, public_name):
+    del public_name  # unused
+    core_mod = importlib.import_module(f"cuda.core._utils.{module_name}")
+    try:
+        bindings_mod = importlib.import_module(f"cuda.bindings._utils.{module_name}")
+    except ModuleNotFoundError:
+        pytest.skip("cuda.bindings._utils not available")
+    bindings_path = f"cuda_bindings/cuda/bindings/_utils/{module_name}.py"
+    core_path = f"cuda_core/cuda/core/_utils/{module_name}.py"
+    if core_mod._CTK_MAJOR_MINOR_PATCH < bindings_mod._CTK_MAJOR_MINOR_PATCH:
+        raise RuntimeError(
+            f"cuda_core copy is older ({core_mod._CTK_MAJOR_MINOR_PATCH})"
+            f" than cuda_bindings ({bindings_mod._CTK_MAJOR_MINOR_PATCH})."
+            f" Please copy the _EXPLANATIONS dict from {bindings_path} to {core_path}"
+        )
+    if (
+        core_mod._CTK_MAJOR_MINOR_PATCH == bindings_mod._CTK_MAJOR_MINOR_PATCH
+        and core_mod._FALLBACK_EXPLANATIONS != bindings_mod._EXPLANATIONS
+    ):
+        raise RuntimeError(
+            f"The cuda_core copy of the cuda_bindings _EXPLANATIONS dict is out of sync"
+            f" (both at CTK {core_mod._CTK_MAJOR_MINOR_PATCH})."
+            f" Please copy the _EXPLANATIONS dict from {bindings_path} to {core_path}"
+        )
 
 
 def test_check_driver_error():