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
« 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
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
12__all__ = 'Debug', 'debug' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
24class DebugArgument: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
25 __slots__ = 'extra', 'name', 'value' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
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
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
58 def __str__(self) -> StrType: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
59 return self.str() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
62class DebugOutput: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
63 """
64 Represents the output of a debug command.
65 """
67 arg_class = DebugArgument 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
68 __slots__ = 'arguments', 'filename', 'frame', 'lineno', 'warning' 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
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
99 def __str__(self) -> StrType: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
100 return self.str() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
107class Debug: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
108 output_class = DebugOutput 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
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
132 def format(self, *args: Any, frame_depth_: int = 2, **kwargs: Any) -> DebugOutput: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
133 return self._process(args, kwargs, frame_depth_) 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
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
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
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 )
170 function = call_frame.f_code.co_name 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
172 from pathlib import Path 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
184 lineno = call_frame.f_lineno 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
185 warning = None 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
187 import executing 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
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 )
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
216 def _process_args(self, ex: Any, args: Any, kwargs: Any) -> Generator[DebugArgument, None, None]: 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
217 import ast 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ
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
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
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
237debug = Debug() 1abghijklmnopcdqrstuvwxyzefABCDEFGHIJ