cuda_core: lazily import frozen enum explanation tables

Keep cuda_utils.pyx unchanged while moving the large 13.1.1 explanation tables into frozen-only modules that are imported only for older bindings. Use loader-aware selection in enum_explanations_helpers.py and add tests that prove docstring-capable bindings skip the frozen-module imports.

Made-with: Cursor

Author: rwgk

cuda_core/cuda/core/_utils/driver_cu_result_explanations.py

@@ -19,13 +19,16 @@
 
 import importlib.metadata
 import re
+from collections.abc import Callable
 from typing import Any
 
 _MIN_12X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS = (12, 9, 6)
 _MIN_13X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS = (13, 2, 0)
 _RST_INLINE_ROLE_RE = re.compile(r":(?:[a-z]+:)?[a-z]+:`([^`]+)`")
 _WORDWRAP_HYPHEN_AFTER_RE = re.compile(r"(?<=[0-9A-Za-z_])- (?=[0-9A-Za-z_])")
 _WORDWRAP_HYPHEN_BEFORE_RE = re.compile(r"(?<=[0-9A-Za-z_]) -(?=[0-9A-Za-z_])")
+_ExplanationTable = dict[int, str | tuple[str, ...]]
+_ExplanationTableLoader = Callable[[], _ExplanationTable]
 
 
 # ``version.pyx`` cannot be reused here (circular import via ``cuda_utils``).
@@ -111,14 +114,17 @@ def get(self, code: int, default: str | None = None) -> str | None:
 
 
 def get_best_available_explanations(
-    enum_type: Any, fallback: dict[int, str | tuple[str, ...]]
-) -> DocstringBackedExplanations | dict[int, str | tuple[str, ...]]:
+    enum_type: Any,
+    fallback: _ExplanationTable | _ExplanationTableLoader,
+) -> DocstringBackedExplanations | _ExplanationTable:
     """Pick one explanation source per bindings version.
 
     Use enum-member ``__doc__`` only for bindings versions known to expose
     usable per-member text (12.9.6+ in the 12.x backport line, 13.2.0+ in the
     13.x mainline). Otherwise keep using the frozen 13.1.1 fallback tables.
     """
     if not _binding_version_has_usable_enum_docstrings(_binding_version()):
+        if callable(fallback):
+            return fallback()
         return fallback
     return DocstringBackedExplanations(enum_type)