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

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 version = importlib.metadata.version("cuda-bindings") (empty)

39 except importlib.metadata.PackageNotFoundError: 

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

41 

42 parts = version.partition("+")[0].split(".")[:3] (empty)

43 parts_int = ([int(v) for v in parts] + [0, 0, 0])[:3] (empty)

44 return (parts_int[0], parts_int[1], parts_int[2]) (empty)

45 

46 

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

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

49 return ( 19 ctx1aTdefgUVWXYZNOPQbcR

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

51 or version >= _MIN_13X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS 

52 ) 

53 

54 

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

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

57 

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

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

60 """ 

61 prev = None 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

62 while prev != s: 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

63 prev = s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

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

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

66 return s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

67 

68 

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

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

71 

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

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

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

75 for error messages. 

76 """ 

77 if doc is None: 37 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKSbc

78 return None 1 ctx1S

79 s = doc 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

80 # Known codegen bug on cudaErrorIncompatibleDriverContext. Remove once fixed 

81 # in cuda-bindings code generation. 

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

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

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

85 # Strip simple bold emphasis markers. 

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

87 # Strip simple italic emphasis markers. 

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

89 # Collapse wrapped lines and repeated spaces. 

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

91 s = _fix_hyphenation_wordwrap_spacing(s) 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

92 return s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

93 

94 

95class DocstringBackedExplanations: (empty)

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

97 

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

99 """ 

100 

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

102 

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

104 self._enum_type = enum_type 7 ctx1aLMNbcR

105 

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

107 try: 22 ctx1ijklmnopqrhdefgstuLMbc

108 member = self._enum_type(code) 22 ctx1ijklmnopqrhdefgstuLMbc

109 except ValueError: 1 ctx1M

110 return default 1 ctx1M

111 

112 raw_doc = member.__doc__ 21 ctx1ijklmnopqrhdefgstuLbc

113 if raw_doc is None: 21 ctx1ijklmnopqrhdefgstuLbc

114 return default 2 ctx1hL

115 

116 return clean_enum_member_docstring(raw_doc) 20 ctx1ijklmnopqrhdefgstubc

117 

118 

119def get_best_available_explanations( (empty)

120 enum_type: Any, 

121 fallback: _ExplanationTable | _ExplanationTableLoader, 

122) -> DocstringBackedExplanations | _ExplanationTable: 

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

124 

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

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

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

128 """ 

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

130 if callable(fallback): 3 ctx1OPQ

131 return fallback() 1 ctx1O

132 return fallback 2 ctx1PQ

133 return DocstringBackedExplanations(enum_type) 5 ctx1aNbcR