Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

/ok to test

/ok to test

I manually reviewed the cleaned driver/runtime enum-doc output for both cuda-bindings 13.2.0 and cuda-bindings 12.9.6 using this local helper script:

from __future__ import annotations

import cuda.bindings
from cuda.bindings import driver, runtime

from cuda.core._utils.enum_explanations_helpers import clean_enum_member_docstring


def dump_enum_docs(label, enum_type):
    print(f"=== {label} ===")
    for member in enum_type:
        cleaned = clean_enum_member_docstring(member.__doc__)
        print(f"{member.name} ({int(member)})")
        print(cleaned if cleaned is not None else "<None>")
        print()


def main():
    print(f"cuda.bindings.__version__ = {cuda.bindings.__version__}")
    print()
    dump_enum_docs("driver.CUresult", driver.CUresult)
    dump_enum_docs("runtime.cudaError_t", runtime.cudaError_t)


if __name__ == "__main__":
    main()

High-level result from the manual review:

• the cleaned output looks presentable in both versions
• I did not see leftover ~, ::, or Sphinx-role markup in the cleaned strings
• this gave me enough confidence to use the docstring-backed path for 12.9.6 <= cuda-bindings < 13.0.0 as well as cuda-bindings >= 13.2.0
• the only remaining oddities I noticed look upstream/generated rather than cleanup-related: cudaErrorIncompatibleDriverContext still says this the CUDA Runtime, and cudaErrorApiFailureBase has no docstring (which still falls back to cudaGetErrorString() in cuda_core)

/ok to test

My Cursor prompt:

Regarding: importing _FALLBACK_EXPLANATIONS only when needed.

Brainstorming: I guess we could achieve this by leaving cuda_utils.pyx untouched, but maybe it's better (especially long-term) if we also consider changing cuda_utils.pyx? Could you please think through the alternatives, how this would shake out either way? What's your recommendation?

Cursor response:

I checked the current import path:

• cuda_core/cuda/core/_utils/cuda_utils.pyx:29 imports DRIVER_CU_RESULT_EXPLANATIONS and RUNTIME_CUDA_ERROR_EXPLANATIONS at module import time.
• cuda_core/cuda/core/_utils/driver_cu_result_explanations.py:355 and cuda_core/cuda/core/_utils/runtime_cuda_error_explanations.py:543 each define a huge _FALLBACK_EXPLANATIONS dict and then immediately call get_best_available_explanations(...).

So today, even on 13.2.x and 12.9.6, importing cuda_utils still imports both big fallback-table modules.

Option 1

• Leave cuda_utils.pyx untouched.
• Move the large dicts into new fallback-only modules, for example driver_cu_result_explanations_fallback.py and runtime_cuda_error_explanations_fallback.py.
• Keep the current driver_cu_result_explanations.py and runtime_cuda_error_explanations.py as thin selector modules that either:
  • return DocstringBackedExplanations(...), or
  • import the fallback module only on old bindings.

How it shakes out:

• cuda_utils.pyx stays exactly as-is.
• No Cython rebuild.
• Public/import shape stays stable.
• Existing tests in cuda_core/tests/test_cuda_utils.py mostly continue to work unchanged.
• If we want to avoid duplicating the version gate twice, enum_explanations_helpers.py can grow a small loader-based helper, e.g. “pick docstrings or call this fallback loader”.

Tradeoff:

• adds two small new modules
• a little bit of plumbing in pure Python

Option 2

• Move the version-selection logic up into cuda_utils.pyx.
• cuda_utils.pyx would either:
  • import fallback modules only when old bindings are detected, or
  • lazily initialize the explanation source on first use.

How it shakes out:

• this is the most literal reading of “move it one level up”
• could avoid importing even the selector modules until needed
• but it pushes import orchestration into Cython

Tradeoff:

• requires rebuilding cuda_core
• more invasive diff
• more logic in compiled code for something that is really import/selection policy
• less nice to unit-test in isolation than the pure-Python helper path
• you would likely need to touch cuda_core/tests/test_cuda_utils.py more, and maybe lose some of the clean separation you currently have in enum_explanations_helpers.py

Option 3

• Hybrid: keep cuda_utils.pyx mostly unchanged, but have it import lightweight getter functions instead of precomputed objects.
• That still means touching cuda_utils.pyx, but not much.

Tradeoff:

• more churn than Option 1
• not obviously better unless you specifically want first-use lazy initialization inside cuda_utils.pyx

Recommendation

• I would keep cuda_utils.pyx untouched for this PR.
• I’d implement the lazy fallback import entirely in Python by splitting the big tables into fallback-only modules and making the current driver/runtime modules thin selectors.
• If we want the selector code to stay tidy, I’d slightly generalize get_best_available_explanations() so it can accept a fallback loader instead of an already-imported dict.

Why I think this is the best fit:

• it satisfies the reviewer’s actual performance/import concern
• it avoids a Cython rebuild for an import-policy change
• it keeps the existing .get(int(error)) shape intact everywhere
• it preserves the current separation of concerns: cuda_utils.pyx consumes explanations, while _utils decides where they come from