Coverage for devtools/debug.py: 100.00%

136 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-11 17:56 +0000

1import os 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

2import sys 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

3from collections.abc import Generator 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

4from types import FrameType 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

5from typing import Any, TextIO, cast 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

6 

7from .ansi import sformat 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

8from .prettier import PrettyFormat 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

9from .timer import Timer 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

10from .utils import env_bool, env_true, is_literal, use_highlight 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

11 

12__all__ = 'Debug', 'debug' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

13 

14pformat = PrettyFormat( 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

15 indent_step=int(os.getenv('PY_DEVTOOLS_INDENT', '4')), 

16 simple_cutoff=int(os.getenv('PY_DEVTOOLS_SIMPLE_CUTOFF', '10')), 

17 width=int(os.getenv('PY_DEVTOOLS_WIDTH', '120')), 

18 yield_from_generators=env_true('PY_DEVTOOLS_YIELD_FROM_GEN', True), 

19) 

20# required for type hinting because I (stupidly) added methods called `str` 

21StrType = str 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

22 

23 

24class DebugArgument: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

25 __slots__ = 'extra', 'name', 'value' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

26 

27 def __init__(self, value: Any, *, name: str | None = None, **extra: Any) -> None: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

28 self.value = value 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

29 self.name = name 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

30 self.extra: list[tuple[str, Any]] = [] 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

31 try: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

32 length = len(value) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

33 except TypeError: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

34 pass 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

35 else: 

36 self.extra.append(('len', length)) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

37 self.extra += [(k, v) for k, v in extra.items() if v is not None] 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

38 

39 def str(self, highlight: bool = False) -> StrType: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

40 s = '' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

41 if self.name and not is_literal(self.name): 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

42 s = f'{sformat(self.name, sformat.blue, apply=highlight)}: ' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

43 

44 suffix = sformat( 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

45 f' ({self.value.__class__.__name__}){"".join(f" {k}={v}" for k, v in self.extra)}', 

46 sformat.dim, 

47 apply=highlight, 

48 ) 

49 try: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

50 s += pformat(self.value, indent=4, highlight=highlight) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

51 except Exception as exc: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

52 v = sformat(f'!!! error pretty printing value: {exc!r}', sformat.yellow, apply=highlight) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

53 s += f'{self.value!r}{suffix}\n {v}' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

54 else: 

55 s += suffix 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

56 return s 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

57 

58 def __str__(self) -> StrType: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

59 return self.str() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

60 

61 

62class DebugOutput: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

63 """ 

64 Represents the output of a debug command. 

65 """ 

66 

67 arg_class = DebugArgument 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

68 __slots__ = 'arguments', 'filename', 'frame', 'lineno', 'warning' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

69 

70 def __init__( 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

71 self, 

72 *, 

73 filename: str, 

74 lineno: int, 

75 frame: str, 

76 arguments: list[DebugArgument], 

77 warning: None | str | bool = None, 

78 ) -> None: 

79 self.filename = filename 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

80 self.lineno = lineno 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

81 self.frame = frame 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

82 self.arguments = arguments 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

83 self.warning = warning 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

84 

85 def str(self, highlight: bool = False) -> StrType: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

86 if highlight: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

87 prefix = ( 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

88 f'{sformat(self.filename, sformat.magenta)}:{sformat(self.lineno, sformat.green)} ' 

89 f'{sformat(self.frame, sformat.green, sformat.italic)}' 

90 ) 

91 if self.warning: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

92 prefix += sformat(f' ({self.warning})', sformat.dim) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

93 else: 

94 prefix = f'{self.filename}:{self.lineno} {self.frame}' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

95 if self.warning: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

96 prefix += f' ({self.warning})' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

97 return f'{prefix}\n ' + '\n '.join(a.str(highlight) for a in self.arguments) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

98 

99 def __str__(self) -> StrType: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

100 return self.str() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

101 

102 def __repr__(self) -> StrType: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

103 arguments = ' '.join(str(a) for a in self.arguments) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

104 return f'<DebugOutput {self.filename}:{self.lineno} {self.frame} arguments: {arguments}>' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

105 

106 

107class Debug: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

108 output_class = DebugOutput 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

109 

110 def __init__(self, *, warnings: bool | None = None, highlight: bool | None = None): 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

111 self._show_warnings = env_bool(warnings, 'PY_DEVTOOLS_WARNINGS', True) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

112 self._highlight = highlight 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

113 

114 def __call__( 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

115 self, 

116 *args: Any, 

117 file_: TextIO | None = None, 

118 flush_: bool = True, 

119 frame_depth_: int = 2, 

120 **kwargs: Any, 

121 ) -> Any: 

122 d_out = self._process(args, kwargs, frame_depth_) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

123 s = d_out.str(use_highlight(self._highlight, file_)) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

124 print(s, file=file_, flush=flush_) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

125 if kwargs: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

126 return (*args, kwargs) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

127 elif len(args) == 1: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

128 return args[0] 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

129 else: 

130 return args 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

131 

132 def format(self, *args: Any, frame_depth_: int = 2, **kwargs: Any) -> DebugOutput: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

133 return self._process(args, kwargs, frame_depth_) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

134 

135 def breakpoint(self) -> None: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

136 """ 

137 Start the IPython debugger if IPython is installed, otherwise `pdb`. 

138 """ 

139 import pdb # noqa: T100 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

140 

141 pdb_class: type[pdb.Pdb] 

142 try: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

143 from IPython.terminal.debugger import TerminalPdb # pyright: ignore[reportMissingImports, reportUnknownVariableType] 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

144 except ImportError: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

145 pdb_class = pdb.Pdb 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

146 else: 

147 pdb_class = cast('type[pdb.Pdb]', TerminalPdb) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

148 pdb_class(skip=['devtools.*']).set_trace() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

149 

150 def timer(self, name: str | None = None, *, verbose: bool = True, file: TextIO | None = None, dp: int = 3) -> Timer: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

151 return Timer(name=name, verbose=verbose, file=file, dp=dp) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

152 

153 def _process(self, args: Any, kwargs: Any, frame_depth: int) -> DebugOutput: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

154 """ 

155 BEWARE: this must be called from a function exactly `frame_depth` levels below the top of the stack. 

156 """ 

157 # HELP: any errors other than ValueError from _getframe? If so please submit an issue 

158 try: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

159 call_frame: FrameType = sys._getframe(frame_depth) # pyright: ignore[reportPrivateUsage] 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

160 except ValueError: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

161 # "If [ValueError] is deeper than the call stack, ValueError is raised" 

162 return self.output_class( 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

163 filename='<unknown>', 

164 lineno=0, 

165 frame='', 

166 arguments=list(self._args_inspection_failed(args, kwargs)), 

167 warning=self._show_warnings and 'error parsing code, call stack too shallow', 

168 ) 

169 

170 function = call_frame.f_code.co_name 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

171 

172 from pathlib import Path 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

173 

174 path = Path(call_frame.f_code.co_filename) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

175 if path.is_absolute(): 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

176 # make the path relative 

177 cwd = Path.cwd() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

178 try: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

179 path = path.relative_to(cwd) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

180 except ValueError: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

181 # happens if filename path is not within CWD 

182 pass 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

183 

184 lineno = call_frame.f_lineno 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

185 warning = None 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

186 

187 import executing 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

188 

189 source = executing.Source.for_frame(call_frame) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

190 if not source.text: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

191 warning = 'no code context for debug call, code inspection impossible' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

192 arguments = list(self._args_inspection_failed(args, kwargs)) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

193 else: 

194 ex = source.executing(call_frame) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

195 function = ex.code_qualname() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

196 if not ex.node: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

197 warning = 'executing failed to find the calling node' 1abcdef

198 arguments = list(self._args_inspection_failed(args, kwargs)) 1abcdef

199 else: 

200 arguments = list(self._process_args(ex, args, kwargs)) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

201 

202 return self.output_class( 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

203 filename=str(path), 

204 lineno=lineno, 

205 frame=function, 

206 arguments=arguments, 

207 warning=self._show_warnings and warning, 

208 ) 

209 

210 def _args_inspection_failed(self, args: Any, kwargs: Any) -> Generator[DebugArgument, None, None]: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

211 for arg in args: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

212 yield self.output_class.arg_class(arg) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

213 for name, value in kwargs.items(): 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

214 yield self.output_class.arg_class(value, name=name) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

215 

216 def _process_args(self, ex: Any, args: Any, kwargs: Any) -> Generator[DebugArgument, None, None]: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

217 import ast 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

218 

219 func_ast = ex.node 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

220 atok = ex.source.asttokens() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

221 for arg, ast_arg in zip(args, func_ast.args): 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

222 if isinstance(ast_arg, ast.Name): 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

223 yield self.output_class.arg_class(arg, name=ast_arg.id) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

224 else: 

225 name = ' '.join(map(str.strip, atok.get_text(ast_arg).splitlines())) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

226 yield self.output_class.arg_class(arg, name=name) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

227 

228 kw_arg_names: dict[str | None, str] = {} 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

229 for kw in func_ast.keywords: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

230 if isinstance(kw.value, ast.Name): 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

231 kw_arg_names[kw.arg] = kw.value.id 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

232 

233 for name, value in kwargs.items(): 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

234 yield self.output_class.arg_class(value, name=name, variable=kw_arg_names.get(name)) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ

235 

236 

237debug = Debug() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ