cuda_core: recognize 12.9.6 enum docstrings

Treat the 12.9.6 backport line as docstring-capable and reuse the same version predicate in tests so error explanations follow the bindings releases that already expose usable enum docs.

Made-with: Cursor

Author: rwgk

cuda_core/cuda/core/_utils/enum_explanations_helpers.py

@@ -4,9 +4,10 @@
 """Internal support for error-enum explanations.
 
 ``cuda_core`` keeps frozen 13.1.1 fallback tables for older ``cuda-bindings``
-releases. Starting with ``cuda-bindings`` 13.2.0, driver/runtime error enums
-carry usable ``__doc__`` text. This module decides which source to use and
-normalizes generated docstrings so user-facing ``CUDAError`` messages stay
+releases. Driver/runtime error enums carry usable ``__doc__`` text starting in
+the 12.x backport line at ``cuda-bindings`` 12.9.6, and in the mainline 13.x
+series at ``cuda-bindings`` 13.2.0. This module decides which source to use
+and normalizes generated docstrings so user-facing ``CUDAError`` messages stay
 close to the long-form explanation prose.
 
 The cleanup rules here were derived while validating docstring-vs-dict parity
@@ -20,7 +21,8 @@
 import re
 from typing import Any
 
-_MIN_BINDING_VERSION_FOR_ENUM_DOCSTRINGS = (13, 2, 0)
+_MIN_12X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS = (12, 9, 6)
+_MIN_13X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS = (13, 2, 0)
 
 
 # ``version.pyx`` cannot be reused here (circular import via ``cuda_utils``).
@@ -33,6 +35,14 @@ def _binding_version() -> tuple[int, int, int]:
     return tuple(int(v) for v in parts)
 
 
+def _binding_version_has_usable_enum_docstrings(version: tuple[int, int, int]) -> bool:
+    """Whether released bindings are known to carry usable error-enum ``__doc__`` text."""
+    return (
+        _MIN_12X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS <= version < (13, 0, 0)
+        or version >= _MIN_13X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS
+    )
+
+
 def _strip_doxygen_double_colon_prefixes(s: str) -> str:
     """Remove Doxygen-style ``::`` before CUDA identifiers (not C++ ``Foo::Bar`` scope).
 
@@ -119,9 +129,10 @@ def get_best_available_explanations(
 ) -> DocstringBackedExplanations | dict[int, str | tuple[str, ...]]:
     """Pick one explanation source per bindings version.
 
-    ``cuda-bindings`` < 13.2.0: use the frozen 13.1.1 fallback tables.
-    ``cuda-bindings`` >= 13.2.0: use enum-member ``__doc__`` exclusively.
+    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 _binding_version() < _MIN_BINDING_VERSION_FOR_ENUM_DOCSTRINGS:
+    if not _binding_version_has_usable_enum_docstrings(_binding_version()):
         return fallback
     return DocstringBackedExplanations(enum_type)

cuda_core/tests/test_cuda_utils.py

@@ -12,10 +12,11 @@
 
 
 def _skip_if_bindings_pre_enum_docstrings():
+    from cuda.core._utils.enum_explanations_helpers import _binding_version_has_usable_enum_docstrings
     from cuda.core._utils.version import binding_version
 
-    if binding_version() < (13, 2, 0):
-        pytest.skip("cuda-bindings < 13.2.0 may not expose enum __doc__ strings")
+    if not _binding_version_has_usable_enum_docstrings(binding_version()):
+        pytest.skip("cuda-bindings version does not expose usable enum __doc__ strings")
 
 
 def test_check_driver_error():

cuda_core/tests/test_utils_enum_explanations_helpers.py

@@ -6,6 +6,7 @@
 
 from cuda.core._utils.enum_explanations_helpers import (
     DocstringBackedExplanations,
+    _binding_version_has_usable_enum_docstrings,
     _strip_doxygen_double_colon_prefixes,
     clean_enum_member_docstring,
 )
@@ -96,25 +97,43 @@ def test_docstring_backed_get_returns_default_for_missing_docstring_without_fall
     assert lut.get(7, default="sentinel") == "sentinel"
 
 
-def test_get_best_available_explanations_uses_fallback_before_13_2(monkeypatch):
-    import cuda.core._utils.enum_explanations_helpers as cleanup
-
-    fallback = {7: "fallback text"}
-    monkeypatch.setattr(cleanup, "_binding_version", lambda: (13, 1, 1))
-    assert cleanup.get_best_available_explanations(_FakeEnumType({7: _FakeEnumMember("doc")}), fallback) is fallback
+@pytest.mark.parametrize(
+    ("version", "expected"),
+    [
+        pytest.param((12, 9, 5), False, id="before_12_9_6"),
+        pytest.param((12, 9, 6), True, id="from_12_9_6"),
+        pytest.param((13, 0, 0), False, id="13_0_mainline_gap"),
+        pytest.param((13, 1, 1), False, id="13_1_1"),
+        pytest.param((13, 2, 0), True, id="from_13_2_0"),
+    ],
+)
+def test_binding_version_has_usable_enum_docstrings(version, expected):
+    assert _binding_version_has_usable_enum_docstrings(version) is expected
 
 
-def test_get_best_available_explanations_prefers_docstrings_from_13_2(monkeypatch):
+@pytest.mark.parametrize(
+    ("version", "expects_docstrings"),
+    [
+        pytest.param((12, 9, 5), False, id="before_12_9_6"),
+        pytest.param((12, 9, 6), True, id="from_12_9_6"),
+        pytest.param((13, 0, 0), False, id="13_0_mainline_gap"),
+        pytest.param((13, 2, 0), True, id="from_13_2_0"),
+    ],
+)
+def test_get_best_available_explanations_switches_by_version(monkeypatch, version, expects_docstrings):
     import cuda.core._utils.enum_explanations_helpers as cleanup
 
     fallback = {7: "fallback text"}
-    monkeypatch.setattr(cleanup, "_binding_version", lambda: (13, 2, 0))
+    monkeypatch.setattr(cleanup, "_binding_version", lambda: version)
     expl = cleanup.get_best_available_explanations(
         _FakeEnumType({7: _FakeEnumMember("clean me")}),
         fallback,
     )
-    assert isinstance(expl, DocstringBackedExplanations)
-    assert expl.get(7) == "clean me"
+    if expects_docstrings:
+        assert isinstance(expl, DocstringBackedExplanations)
+        assert expl.get(7) == "clean me"
+    else:
+        assert expl is fallback
 
 
 def test_driver_cu_result_explanations_get_matches_clean_docstring():