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
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-20 05:46 +0000
1"""Introspection utils for tasks call graphs."""
3import dataclasses
4import io
5import operator
6import sys
7import types
9from . import events
10from . import futures
11from . import tasks
13__all__ = (
14 'capture_call_graph',
15 'format_call_graph',
16 'print_call_graph',
17 'FrameCallGraphEntry',
18 'FutureCallGraph',
19)
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.
29@dataclasses.dataclass(frozen=True, slots=True)
30class FrameCallGraphEntry:
31 frame: types.FrameType
34@dataclasses.dataclass(frozen=True, slots=True)
35class FutureCallGraph:
36 future: futures.Future
37 call_stack: tuple["FrameCallGraphEntry", ...]
38 awaited_by: tuple["FutureCallGraph", ...]
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 )
52 coro = None
53 if get_coro := getattr(future, 'get_coro', None):
54 coro = get_coro() if limit != 0 else None
56 st: list[FrameCallGraphEntry] = []
57 awaited_by: list[FutureCallGraph] = []
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
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))
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))
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.
102 The graph is represented with three data structures:
104 * FutureCallGraph(future, call_stack, awaited_by)
106 Where 'future' is an instance of asyncio.Future or asyncio.Task.
108 'call_stack' is a tuple of FrameGraphEntry objects.
110 'awaited_by' is a tuple of FutureCallGraph objects.
112 * FrameCallGraphEntry(frame)
114 Where 'frame' is a frame object of a regular Python function
115 in the call stack.
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.
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.
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 """
134 loop = events._get_running_loop()
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)
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
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 )
162 call_stack: list[FrameCallGraphEntry] = []
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))
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
179 f = f.f_back
180 finally:
181 del f
183 call_stack = call_stack[max(0, operator.index(depth)):]
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))
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:]
197 return FutureCallGraph(future, tuple(call_stack), tuple(awaited_by))
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`.
209 If `future` is not provided, format the call graph for the current task.
210 """
212 def render_level(st: FutureCallGraph, buf: list[str], level: int) -> None:
213 def add_line(line: str) -> None:
214 buf.append(level * ' ' + line)
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 )
225 if st.call_stack:
226 add_line(
227 f' + Call stack:'
228 )
229 for ste in st.call_stack:
230 f = ste.frame
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
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'
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 )
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)
269 graph = capture_call_graph(future, depth=depth + 1, limit=limit)
270 if graph is None:
271 return ""
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)
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)