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

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 return tuple(int(v) for v in parts) (empty)

44 

45 

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

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

48 return ( 19 ctx1aTdefgUVWXYZNOPQbcR

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

50 or version >= _MIN_13X_BINDING_VERSION_FOR_ENUM_DOCSTRINGS 

51 ) 

52 

53 

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

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

56 

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

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

59 """ 

60 prev = None 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

61 while prev != s: 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

62 prev = s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

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

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

65 return s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

66 

67 

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

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

70 

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

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

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

74 for error messages. 

75 """ 

76 if doc is None: 37 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKSbc

77 return None 1 ctx1S

78 s = doc 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

79 # Known codegen bug on cudaErrorIncompatibleDriverContext. Remove once fixed 

80 # in cuda-bindings code generation. 

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

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

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

84 # Strip simple bold emphasis markers. 

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

86 # Strip simple italic emphasis markers. 

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

88 # Collapse wrapped lines and repeated spaces. 

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

90 s = _fix_hyphenation_wordwrap_spacing(s) 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

91 return s 36 ctx1ijklmnopqrhdefgstuvwxyzABCDEFGHIJKbc

92 

93 

94class DocstringBackedExplanations: (empty)

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

96 

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

98 """ 

99 

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

101 

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

103 self._enum_type = enum_type 7 ctx1aLMNbcR

104 

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

106 try: 22 ctx1ijklmnopqrhdefgstuLMbc

107 member = self._enum_type(code) 22 ctx1ijklmnopqrhdefgstuLMbc

108 except ValueError: 1 ctx1M

109 return default 1 ctx1M

110 

111 raw_doc = member.__doc__ 21 ctx1ijklmnopqrhdefgstuLbc

112 if raw_doc is None: 21 ctx1ijklmnopqrhdefgstuLbc

113 return default 2 ctx1hL

114 

115 return clean_enum_member_docstring(raw_doc) 20 ctx1ijklmnopqrhdefgstubc

116 

117 

118def get_best_available_explanations( (empty)

119 enum_type: Any, 

120 fallback: _ExplanationTable | _ExplanationTableLoader, 

121) -> DocstringBackedExplanations | _ExplanationTable: 

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

123 

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

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

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

127 """ 

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

129 if callable(fallback): 3 ctx1OPQ

130 return fallback() 1 ctx1O

131 return fallback 2 ctx1PQ

132 return DocstringBackedExplanations(enum_type) 5 ctx1aNbcR