Coverage for cuda / core / _utils / enum_explanations_helpers.py: 96.49%

1# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. 

2# SPDX-License-Identifier: Apache-2.0 

3 

4"""Internal support for error-enum explanations. 

5 

6``cuda_core`` keeps frozen 13.1.1 fallback tables for older ``cuda-bindings`` 

7releases. Driver/runtime error enums carry usable ``__doc__`` text starting in 

8the 12.x backport line at ``cuda-bindings`` 12.9.6, and in the mainline 13.x 

9series at ``cuda-bindings`` 13.2.0. This module decides which source to use 

10and normalizes generated docstrings so user-facing ``CUDAError`` messages stay 

11presentable. 

12 

13The cleanup rules here were derived while validating generated enum docstrings 

14in PR #1805. Keep them narrow and remove them when codegen quirks or fallback 

15support are no longer needed. 

16""" 

17 

18from __future__ import annotations (empty)

19 

20import importlib.metadata (empty)

21import re (empty)

22from collections.abc import Callable (empty)

23from typing import Any (empty)

24 

25_MIN_12X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS = (12, 9, 6) (empty)

26_MIN_13X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS = (13, 2, 0) (empty)

27_RST_INLINE_ROLE_RE = re.compile(r":(?:[a-z]+:)?[a-z]+:`([^`]+)`") (empty)

28_WORDWRAP_HYPHEN_AFTER_RE = re.compile(r"(?<=[0-9A-Za-z_])- (?=[0-9A-Za-z_])") (empty)

29_WORDWRAP_HYPHEN_BEFORE_RE = re.compile(r"(?<=[0-9A-Za-z_]) -(?=[0-9A-Za-z_])") (empty)

30_ExplanationTable = dict[int, str | tuple[str, ...]] (empty)

31_ExplanationTableLoader = Callable[[], _ExplanationTable] (empty)

32 

33 

34# ``version.pyx`` cannot be reused here (circular import via ``cuda_utils``). 

35def _binding_version() -> tuple[int, int, int]: (empty)

36 """Return the installed ``cuda-bindings`` version, or a conservative old value.""" 

37 try: (empty)

38 parts = importlib.metadata.version("cuda-bindings").split(".")[:3] (empty)

39 except importlib.metadata.PackageNotFoundError: 

40 return (0, 0, 0) # For very old versions of cuda-python 

41 return tuple(int(v) for v in parts) (empty)

42 

43 

44def _binding_version_has_usable_enum_docstrings(version: tuple[int, int, int]) -> bool: (empty)

45 """Whether released bindings are known to carry usable error-enum ``__doc__`` text.""" 

46 return ( 19 ctx1aTdefgUVWXYZNOPQbcR

47 _MIN_12X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS <= version < (13, 0, 0) 

48 or version >= _MIN_13X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS 

49 ) 

50 

51 

52def _fix_hyphenation_wordwrap_spacing(s: str) -> str: (empty)

53 """Remove spaces around hyphens introduced by line wrapping in generated ``__doc__`` text. 

54 

55 This targets asymmetric wrap artifacts such as ``non- linear`` or 

56 ``GPU- Direct`` while leaving intentional ``a - b`` separators alone. 

57 """ 

58 prev = None 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

59 while prev != s: 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

60 prev = s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

61 s = _WORDWRAP_HYPHEN_AFTER_RE.sub("-", s) 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

62 s = _WORDWRAP_HYPHEN_BEFORE_RE.sub("-", s) 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

63 return s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

64 

65 

66def clean_enum_member_docstring(doc: str | None) -> str | None: (empty)

67 """Turn an enum member ``__doc__`` into plain text. 

68 

69 The generated enum docstrings are already close to user-facing prose, but 

70 they may contain Sphinx inline roles, line wrapping, or a small known 

71 codegen defect. Normalize only those differences so the text is suitable 

72 for error messages. 

73 """ 

74 if doc is None: 37 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKSbc

75 return None 1 ctx1S

76 s = doc 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

77 # Known codegen bug on cudaErrorIncompatibleDriverContext. Remove once fixed 

78 # in cuda-bindings code generation. 

79 s = s.replace("\n:py:obj:`~.Interactions`", ' "Interactions ') 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

80 # Drop a leading "~." or "." after removing the surrounding RST inline role. 

81 s = _RST_INLINE_ROLE_RE.sub(lambda m: re.sub(r"^~?\.", "", m.group(1)), s) 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

82 # Strip simple bold emphasis markers. 

83 s = re.sub(r"\*\*([^*]+)\*\*", r"\1", s) 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

84 # Strip simple italic emphasis markers. 

85 s = re.sub(r"\*([^*]+)\*", r"\1", s) 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

86 # Collapse wrapped lines and repeated spaces. 

87 s = re.sub(r"\s+", " ", s).strip() 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

88 s = _fix_hyphenation_wordwrap_spacing(s) 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

89 return s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

90 

91 

92class DocstringBackedExplanations: (empty)

93 """Compatibility shim exposing enum-member ``__doc__`` text via ``dict.get``. 

94 

95 Keeps the existing ``.get(int(error))`` lookup shape used by ``cuda_utils.pyx``. 

96 """ 

97 

98 __slots__ = ("_enum_type",) (empty)

99 

100 def __init__(self, enum_type: Any) -> None: (empty)

101 self._enum_type = enum_type 7 ctx1aLMNbcR

102 

103 def get(self, code: int, default: str | None = None) -> str | None: (empty)

104 try: 22 ctx1ijklmnopqrhdefgstuLMbc

105 member = self._enum_type(code) 22 ctx1ijklmnopqrhdefgstuLMbc

106 except ValueError: 1 ctx1M

107 return default 1 ctx1M

108 

109 raw_doc = member.__doc__ 21 ctx1ijklmnopqrhdefgstuLbc

110 if raw_doc is None: 21 ctx1ijklmnopqrhdefgstuLbc

111 return default 2 ctx1hL

112 

113 return clean_enum_member_docstring(raw_doc) 20 ctx1ijklmnopqrhdefgstubc

114 

115 

116def get_best_available_explanations( (empty)

117 enum_type: Any, 

118 fallback: _ExplanationTable | _ExplanationTableLoader, 

119) -> DocstringBackedExplanations | _ExplanationTable: 

120 """Pick one explanation source per bindings version. 

121 

122 Use enum-member ``__doc__`` only for bindings versions known to expose 

123 usable per-member text (12.9.6+ in the 12.x backport line, 13.2.0+ in the 

124 13.x mainline). Otherwise keep using the frozen 13.1.1 fallback tables. 

125 """ 

126 if not _binding_version_has_usable_enum_docstrings(_binding_version()): 8 ctx1aNOPQbcR

127 if callable(fallback): 3 ctx1OPQ

128 return fallback() 1 ctx1O

129 return fallback 2 ctx1PQ

130 return DocstringBackedExplanations(enum_type) 5 ctx1aNbcR