Skip to content

Commit 1120449

Browse files
committed
Rename "capture_call_stack()" et al to "capture_call_graph()"
1 parent 4f7bf44 commit 1120449

File tree

3 files changed

+53
-53
lines changed

3 files changed

+53
-53
lines changed

Doc/library/asyncio-stack.rst

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ a suspended *future*.
1818
.. versionadded:: 3.14
1919

2020

21-
.. function:: print_call_stack(*, future=None, file=None)
21+
.. function:: print_call_graph(*, future=None, file=None)
2222

23-
Print the async call stack for the current task or the provided
23+
Print the async call graph for the current task or the provided
2424
:class:`Task` or :class:`Future`.
2525

2626
The function recieves an optional keyword-only *future* argument.
@@ -38,7 +38,7 @@ a suspended *future*.
3838
import asyncio
3939
4040
async def test():
41-
asyncio.print_call_stack()
41+
asyncio.print_call_graph()
4242
4343
async def main():
4444
async with asyncio.TaskGroup() as g:
@@ -50,7 +50,7 @@ a suspended *future*.
5050

5151
* Task(name='Task-2', id=0x105038fe0)
5252
+ Call stack:
53-
| * print_call_stack()
53+
| * print_call_graph()
5454
| asyncio/stack.py:231
5555
| * async test()
5656
| test.py:4
@@ -72,37 +72,37 @@ a suspended *future*.
7272
...
7373
7474
buf = io.StringIO()
75-
asyncio.print_call_stack(file=buf)
75+
asyncio.print_call_graph(file=buf)
7676
output = buf.getvalue()
7777
7878
79-
.. function:: capture_call_stack(*, future=None)
79+
.. function:: capture_call_graph(*, future=None)
8080

81-
Capture the async call stack for the current task or the provided
81+
Capture the async call graph for the current task or the provided
8282
:class:`Task` or :class:`Future`.
8383

8484
The function recieves an optional keyword-only *future* argument.
8585
If not passed, the current running task will be used. If there's no
8686
current task, the function returns ``None``.
8787

88-
Returns a ``FutureCallStack`` named tuple:
88+
Returns a ``FutureCallGraph`` named tuple:
8989

90-
* ``FutureCallStack(future, call_stack, awaited_by)``
90+
* ``FutureCallGraph(future, call_graph, awaited_by)``
9191

9292
Where 'future' is a reference to a *Future* or a *Task*
9393
(or their subclasses.)
9494

95-
``call_stack`` is a list of ``FrameCallStackEntry`` and
96-
``CoroutineCallStackEntry`` objects (more on them below.)
95+
``call_graph`` is a list of ``FrameCallGraphEntry`` and
96+
``CoroutineCallGraphEntry`` objects (more on them below.)
9797

98-
``awaited_by`` is a list of ``FutureCallStack`` tuples.
98+
``awaited_by`` is a list of ``FutureCallGraph`` tuples.
9999

100-
* ``FrameCallStackEntry(frame)``
100+
* ``FrameCallGraphEntry(frame)``
101101

102102
Where ``frame`` is a frame object of a regular Python function
103103
in the call stack.
104104

105-
* ``CoroutineCallStackEntry(coroutine)``
105+
* ``CoroutineCallGraphEntry(coroutine)``
106106

107107
Where ``coroutine`` is a coroutine object of an awaiting coroutine
108108
or asyncronous generator.
@@ -111,7 +111,7 @@ a suspended *future*.
111111
Low level utility functions
112112
===========================
113113

114-
To introspect an async call stack asyncio requires cooperation from
114+
To introspect an async call graph asyncio requires cooperation from
115115
control flow structures, such as :func:`shield` or :class:`TaskGroup`.
116116
Any time an intermediate ``Future`` object with low-level APIs like
117117
:meth:`Future.add_done_callback() <asyncio.Future.add_done_callback>` is

Lib/asyncio/stack.py

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@
99
from . import tasks
1010

1111
__all__ = (
12-
'capture_call_stack',
13-
'print_call_stack',
14-
'FrameCallStackEntry',
15-
'CoroutineCallStackEntry',
16-
'FutureCallStack',
12+
'capture_call_graph',
13+
'print_call_graph',
14+
'FrameCallGraphEntry',
15+
'CoroutineCallGraphEntry',
16+
'FutureCallGraph',
1717
)
1818

1919
# Sadly, we can't re-use the traceback's module datastructures as those
@@ -24,21 +24,21 @@
2424
# top level asyncio namespace, and want to avoid future name clashes.
2525

2626

27-
class FrameCallStackEntry(typing.NamedTuple):
27+
class FrameCallGraphEntry(typing.NamedTuple):
2828
frame: types.FrameType
2929

3030

31-
class CoroutineCallStackEntry(typing.NamedTuple):
31+
class CoroutineCallGraphEntry(typing.NamedTuple):
3232
coroutine: types.CoroutineType
3333

3434

35-
class FutureCallStack(typing.NamedTuple):
35+
class FutureCallGraph(typing.NamedTuple):
3636
future: futures.Future
37-
call_stack: list[FrameCallStackEntry | CoroutineCallStackEntry]
38-
awaited_by: list[FutureCallStack]
37+
call_graph: list[FrameCallGraphEntry | CoroutineCallGraphEntry]
38+
awaited_by: list[FutureCallGraph]
3939

4040

41-
def _build_stack_for_future(future: any) -> FutureCallStack:
41+
def _build_stack_for_future(future: any) -> FutureCallGraph:
4242
if not isinstance(future, futures.Future):
4343
raise TypeError(
4444
f"{future!r} object does not appear to be compatible "
@@ -52,17 +52,17 @@ def _build_stack_for_future(future: any) -> FutureCallStack:
5252
else:
5353
coro = get_coro()
5454

55-
st: list[CoroutineCallStackEntry] = []
56-
awaited_by: list[FutureCallStack] = []
55+
st: list[CoroutineCallGraphEntry] = []
56+
awaited_by: list[FutureCallGraph] = []
5757

5858
while coro is not None:
5959
if hasattr(coro, 'cr_await'):
6060
# A native coroutine or duck-type compatible iterator
61-
st.append(CoroutineCallStackEntry(coro))
61+
st.append(CoroutineCallGraphEntry(coro))
6262
coro = coro.cr_await
6363
elif hasattr(coro, 'ag_await'):
6464
# A native async generator or duck-type compatible iterator
65-
st.append(CoroutineCallStackEntry(coro))
65+
st.append(CoroutineCallGraphEntry(coro))
6666
coro = coro.ag_await
6767
else:
6868
break
@@ -72,30 +72,30 @@ def _build_stack_for_future(future: any) -> FutureCallStack:
7272
awaited_by.append(_build_stack_for_future(parent))
7373

7474
st.reverse()
75-
return FutureCallStack(future, st, awaited_by)
75+
return FutureCallGraph(future, st, awaited_by)
7676

7777

78-
def capture_call_stack(*, future: any = None) -> FutureCallStack | None:
78+
def capture_call_graph(*, future: any = None) -> FutureCallGraph | None:
7979
"""Capture async call stack for the current task or the provided Future.
8080
8181
The stack is represented with three data structures:
8282
83-
* FutureCallStack(future, call_stack, awaited_by)
83+
* FutureCallGraph(future, call_graph, awaited_by)
8484
8585
Where 'future' is a reference to an asyncio.Future or asyncio.Task
8686
(or their subclasses.)
8787
88-
'call_stack' is a list of FrameCallStackEntry and CoroutineCallStackEntry
88+
'call_graph' is a list of FrameCallGraphEntry and CoroutineCallGraphEntry
8989
objects (more on them below.)
9090
91-
'awaited_by' is a list of FutureCallStack objects.
91+
'awaited_by' is a list of FutureCallGraph objects.
9292
93-
* FrameCallStackEntry(frame)
93+
* FrameCallGraphEntry(frame)
9494
9595
Where 'frame' is a frame object of a regular Python function
9696
in the call stack.
9797
98-
* CoroutineCallStackEntry(coroutine)
98+
* CoroutineCallGraphEntry(coroutine)
9999
100100
Where 'coroutine' is a coroutine object of an awaiting coroutine
101101
or asyncronous generator.
@@ -117,7 +117,7 @@ def capture_call_stack(*, future: any = None) -> FutureCallStack | None:
117117
else:
118118
if loop is None:
119119
raise RuntimeError(
120-
'capture_call_stack() is called outside of a running '
120+
'capture_call_graph() is called outside of a running '
121121
'event loop and no *future* to introspect was provided')
122122
future = tasks.current_task(loop=loop)
123123

@@ -133,21 +133,21 @@ def capture_call_stack(*, future: any = None) -> FutureCallStack | None:
133133
f"with asyncio.Future"
134134
)
135135

136-
call_stack: list[FrameCallStackEntry | CoroutineCallStackEntry] = []
136+
call_graph: list[FrameCallGraphEntry | CoroutineCallGraphEntry] = []
137137

138138
f = sys._getframe(1)
139139
try:
140140
while f is not None:
141141
is_async = f.f_generator is not None
142142

143143
if is_async:
144-
call_stack.append(CoroutineCallStackEntry(f.f_generator))
144+
call_graph.append(CoroutineCallGraphEntry(f.f_generator))
145145
if f.f_back is not None and f.f_back.f_generator is None:
146146
# We've reached the bottom of the coroutine stack, which
147147
# must be the Task that runs it.
148148
break
149149
else:
150-
call_stack.append(FrameCallStackEntry(f))
150+
call_graph.append(FrameCallGraphEntry(f))
151151

152152
f = f.f_back
153153
finally:
@@ -158,13 +158,13 @@ def capture_call_stack(*, future: any = None) -> FutureCallStack | None:
158158
for parent in fut_waiters:
159159
awaited_by.append(_build_stack_for_future(parent))
160160

161-
return FutureCallStack(future, call_stack, awaited_by)
161+
return FutureCallGraph(future, call_graph, awaited_by)
162162

163163

164-
def print_call_stack(*, future: any = None, file=None) -> None:
164+
def print_call_graph(*, future: any = None, file=None) -> None:
165165
"""Print async call stack for the current task or the provided Future."""
166166

167-
def render_level(st: FutureCallStack, buf: list[str], level: int):
167+
def render_level(st: FutureCallGraph, buf: list[str], level: int):
168168
def add_line(line: str):
169169
buf.append(level * ' ' + line)
170170

@@ -177,12 +177,12 @@ def add_line(line: str):
177177
f'* Future(id=0x{id(st.future):x})'
178178
)
179179

180-
if st.call_stack:
180+
if st.call_graph:
181181
add_line(
182182
f' + Call stack:'
183183
)
184-
for ste in st.call_stack:
185-
if isinstance(ste, FrameCallStackEntry):
184+
for ste in st.call_graph:
185+
if isinstance(ste, FrameCallGraphEntry):
186186
f = ste.frame
187187
add_line(
188188
f' | * {f.f_code.co_qualname}()'
@@ -191,7 +191,7 @@ def add_line(line: str):
191191
f' | {f.f_code.co_filename}:{f.f_lineno}'
192192
)
193193
else:
194-
assert isinstance(ste, CoroutineCallStackEntry)
194+
assert isinstance(ste, CoroutineCallGraphEntry)
195195
c = ste.coroutine
196196

197197
try:
@@ -222,7 +222,7 @@ def add_line(line: str):
222222
for fut in st.awaited_by:
223223
render_level(fut, buf, level + 1)
224224

225-
stack = capture_call_stack(future=future)
225+
stack = capture_call_graph(future=future)
226226
if stack is None:
227227
return
228228

Lib/test/test_asyncio/test_stack.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,13 @@ def walk(s):
2020
[
2121
(
2222
f"s {entry.frame.f_code.co_name}"
23-
if isinstance(entry, asyncio.FrameCallStackEntry) else
23+
if isinstance(entry, asyncio.FrameCallGraphEntry) else
2424
(
2525
f"a {entry.coroutine.cr_code.co_name}"
2626
if hasattr(entry.coroutine, 'cr_code') else
2727
f"ag {entry.coroutine.ag_code.co_name}"
2828
)
29-
) for entry in s.call_stack
29+
) for entry in s.call_graph
3030
]
3131
)
3232

@@ -39,9 +39,9 @@ def walk(s):
3939
return ret
4040

4141
buf = io.StringIO()
42-
asyncio.print_call_stack(future=fut, file=buf)
42+
asyncio.print_call_graph(future=fut, file=buf)
4343

44-
stack = asyncio.capture_call_stack(future=fut)
44+
stack = asyncio.capture_call_graph(future=fut)
4545
return walk(stack), buf.getvalue()
4646

4747

0 commit comments

Comments
 (0)