Coverage for Lib/asyncio/graph.py: 99%

124 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-20 05:46 +0000

1"""Introspection utils for tasks call graphs.""" 

2 

3import dataclasses 

4import io 

5import operator 

6import sys 

7import types 

8 

9from . import events 

10from . import futures 

11from . import tasks 

12 

13__all__ = ( 

14 'capture_call_graph', 

15 'format_call_graph', 

16 'print_call_graph', 

17 'FrameCallGraphEntry', 

18 'FutureCallGraph', 

19) 

20 

21# Sadly, we can't re-use the traceback module's datastructures as those 

22# are tailored for error reporting, whereas we need to represent an 

23# async call graph. 

24# 

25# Going with pretty verbose names as we'd like to export them to the 

26# top level asyncio namespace, and want to avoid future name clashes. 

27 

28 

29@dataclasses.dataclass(frozen=True, slots=True) 

30class FrameCallGraphEntry: 

31 frame: types.FrameType 

32 

33 

34@dataclasses.dataclass(frozen=True, slots=True) 

35class FutureCallGraph: 

36 future: futures.Future 

37 call_stack: tuple["FrameCallGraphEntry", ...] 

38 awaited_by: tuple["FutureCallGraph", ...] 

39 

40 

41def _build_graph_for_future( 

42 future: futures.Future, 

43 *, 

44 limit: int | None = None, 

45) -> FutureCallGraph: 

46 if not isinstance(future, futures.Future): 

47 raise TypeError( 

48 f"{future!r} object does not appear to be compatible " 

49 f"with asyncio.Future" 

50 ) 

51 

52 coro = None 

53 if get_coro := getattr(future, 'get_coro', None): 

54 coro = get_coro() if limit != 0 else None 

55 

56 st: list[FrameCallGraphEntry] = [] 

57 awaited_by: list[FutureCallGraph] = [] 

58 

59 while coro is not None: 

60 if hasattr(coro, 'cr_await'): 

61 # A native coroutine or duck-type compatible iterator 

62 if coro.cr_frame is not None: 

63 st.append(FrameCallGraphEntry(coro.cr_frame)) 

64 coro = coro.cr_await 

65 elif hasattr(coro, 'ag_await'): 

66 # A native async generator or duck-type compatible iterator 

67 st.append(FrameCallGraphEntry(coro.ag_frame)) 

68 coro = coro.ag_await 

69 elif hasattr(coro, 'gi_yieldfrom'): 

70 # A generator, e.g. returned by __await__ or @types.coroutine 

71 if coro.gi_frame is not None: 71 ↛ 73line 71 didn't jump to line 73 because the condition on line 71 was always true

72 st.append(FrameCallGraphEntry(coro.gi_frame)) 

73 coro = coro.gi_yieldfrom 

74 elif hasattr(coro, 'aga_gen'): 

75 # An asend()/athrow() awaitable: step over it to its generator 

76 coro = coro.aga_gen 

77 else: 

78 break 

79 

80 if future._asyncio_awaited_by: 

81 for parent in future._asyncio_awaited_by: 

82 awaited_by.append(_build_graph_for_future(parent, limit=limit)) 

83 

84 if limit is not None: 

85 if limit > 0: 

86 st = st[:limit] 

87 elif limit < 0: 87 ↛ 89line 87 didn't jump to line 89 because the condition on line 87 was always true

88 st = st[limit:] 

89 st.reverse() 

90 return FutureCallGraph(future, tuple(st), tuple(awaited_by)) 

91 

92 

93def capture_call_graph( 

94 future: futures.Future | None = None, 

95 /, 

96 *, 

97 depth: int = 1, 

98 limit: int | None = None, 

99) -> FutureCallGraph | None: 

100 """Capture the async call graph for the current task or the provided Future. 

101 

102 The graph is represented with three data structures: 

103 

104 * FutureCallGraph(future, call_stack, awaited_by) 

105 

106 Where 'future' is an instance of asyncio.Future or asyncio.Task. 

107 

108 'call_stack' is a tuple of FrameGraphEntry objects. 

109 

110 'awaited_by' is a tuple of FutureCallGraph objects. 

111 

112 * FrameCallGraphEntry(frame) 

113 

114 Where 'frame' is a frame object of a regular Python function 

115 in the call stack. 

116 

117 Receives an optional 'future' argument. If not passed, 

118 the current task will be used. If there's no current task, the function 

119 returns None. 

120 

121 If "capture_call_graph()" is introspecting *the current task*, the 

122 optional keyword-only 'depth' argument can be used to skip the specified 

123 number of frames from top of the stack. 

124 

125 If the optional keyword-only 'limit' argument is provided, each call 

126 stack in the resulting graph is truncated to include at most 

127 ``abs(limit)`` entries. If 'limit' is positive, the entries left are 

128 the closest to the invocation point. If 'limit' is negative, the 

129 topmost entries are left. If 'limit' is omitted or None, all entries 

130 are present. If 'limit' is 0, the call stack is not captured at all, 

131 only "awaited by" information is present. 

132 """ 

133 

134 loop = events._get_running_loop() 

135 

136 if future is not None: 

137 # Check if we're in a context of a running event loop; 

138 # if yes - check if the passed future is the currently 

139 # running task or not. 

140 if loop is None or future is not tasks.current_task(loop=loop): 

141 return _build_graph_for_future(future, limit=limit) 

142 # else: future is the current task, move on. 

143 else: 

144 if loop is None: 

145 raise RuntimeError( 

146 'capture_call_graph() is called outside of a running ' 

147 'event loop and no *future* to introspect was provided') 

148 future = tasks.current_task(loop=loop) 

149 

150 if future is None: 

151 # This isn't a generic call stack introspection utility. If we 

152 # can't determine the current task and none was provided, we 

153 # just return. 

154 return None 

155 

156 if not isinstance(future, futures.Future): 

157 raise TypeError( 

158 f"{future!r} object does not appear to be compatible " 

159 f"with asyncio.Future" 

160 ) 

161 

162 call_stack: list[FrameCallGraphEntry] = [] 

163 

164 # gh-161124: find the task boundary before skipping frames 

165 f = sys._getframe(0) if limit != 0 else None 

166 try: 

167 while f is not None: 

168 # gh-156988: sync gen should not clear the call chain 

169 is_async = isinstance( 

170 f.f_generator, (types.CoroutineType, types.AsyncGeneratorType)) 

171 call_stack.append(FrameCallGraphEntry(f)) 

172 

173 if is_async: 

174 if f.f_back is not None and f.f_back.f_generator is None: 

175 # We've reached the bottom of the coroutine stack, which 

176 # must be the Task that runs it. 

177 break 

178 

179 f = f.f_back 

180 finally: 

181 del f 

182 

183 call_stack = call_stack[max(0, operator.index(depth)):] 

184 

185 awaited_by = [] 

186 if future._asyncio_awaited_by: 

187 for parent in future._asyncio_awaited_by: 

188 awaited_by.append(_build_graph_for_future(parent, limit=limit)) 

189 

190 if limit is not None: 

191 limit *= -1 

192 if limit > 0: 

193 call_stack = call_stack[:limit] 

194 elif limit < 0: 

195 call_stack = call_stack[limit:] 

196 

197 return FutureCallGraph(future, tuple(call_stack), tuple(awaited_by)) 

198 

199 

200def format_call_graph( 

201 future: futures.Future | None = None, 

202 /, 

203 *, 

204 depth: int = 1, 

205 limit: int | None = None, 

206) -> str: 

207 """Return the async call graph as a string for `future`. 

208 

209 If `future` is not provided, format the call graph for the current task. 

210 """ 

211 

212 def render_level(st: FutureCallGraph, buf: list[str], level: int) -> None: 

213 def add_line(line: str) -> None: 

214 buf.append(level * ' ' + line) 

215 

216 if isinstance(st.future, tasks.Task): 

217 add_line( 

218 f'* Task(name={st.future.get_name()!r}, id={id(st.future):#x})' 

219 ) 

220 else: 

221 add_line( 

222 f'* Future(id={id(st.future):#x})' 

223 ) 

224 

225 if st.call_stack: 

226 add_line( 

227 f' + Call stack:' 

228 ) 

229 for ste in st.call_stack: 

230 f = ste.frame 

231 

232 if f.f_generator is None: 

233 f = ste.frame 

234 add_line( 

235 f' | File {f.f_code.co_filename!r},' 

236 f' line {f.f_lineno}, in' 

237 f' {f.f_code.co_qualname}()' 

238 ) 

239 else: 

240 c = f.f_generator 

241 

242 try: 

243 f = c.cr_frame 

244 code = c.cr_code 

245 tag = 'async' 

246 except AttributeError: 

247 try: 

248 f = c.ag_frame 

249 code = c.ag_code 

250 tag = 'async generator' 

251 except AttributeError: 

252 f = c.gi_frame 

253 code = c.gi_code 

254 tag = 'generator' 

255 

256 add_line( 

257 f' | File {f.f_code.co_filename!r},' 

258 f' line {f.f_lineno}, in' 

259 f' {tag} {code.co_qualname}()' 

260 ) 

261 

262 if st.awaited_by: 

263 add_line( 

264 f' + Awaited by:' 

265 ) 

266 for fut in st.awaited_by: 

267 render_level(fut, buf, level + 1) 

268 

269 graph = capture_call_graph(future, depth=depth + 1, limit=limit) 

270 if graph is None: 

271 return "" 

272 

273 buf: list[str] = [] 

274 try: 

275 render_level(graph, buf, 0) 

276 finally: 

277 # 'graph' has references to frames so we should 

278 # make sure it's GC'ed as soon as we don't need it. 

279 del graph 

280 return '\n'.join(buf) 

281 

282def print_call_graph( 

283 future: futures.Future | None = None, 

284 /, 

285 *, 

286 file: io.Writer[str] | None = None, 

287 depth: int = 1, 

288 limit: int | None = None, 

289) -> None: 

290 """Print the async call graph for the current task or the provided Future.""" 

291 # gh-156327: print_call_graph() must not report its own frame 

292 print(format_call_graph(future, depth=depth + 1, limit=limit), file=file)