Rename "asyncio.stack" to "asyncio.graph"

ambv · ambv · commit 07748059f4ba · 2024-11-13T17:17:31.000+01:00
diff --git a/Doc/library/asyncio-graph.rst b/Doc/library/asyncio-graph.rst
@@ -1,17 +1,17 @@
 .. currentmodule:: asyncio
 
 
-.. _asyncio-stack:
+.. _asyncio-graph:
 
 ===================
 Stack Introspection
 ===================
 
-**Source code:** :source:`Lib/asyncio/stack.py`
+**Source code:** :source:`Lib/asyncio/graph.py`
 
 -------------------------------------
 
-asyncio has powerful runtime call stack introspection utilities
+asyncio has powerful runtime call graph introspection utilities
 to trace the entire call graph of a running coroutine or task, or
 a suspended *future*.  These utilities and the underlying machinery
 can be used by users in their Python code or by external profilers
diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
@@ -99,7 +99,7 @@ You can experiment with an ``asyncio`` concurrent context in the :term:`REPL`:
    asyncio-subprocess.rst
    asyncio-queue.rst
    asyncio-exceptions.rst
-   asyncio-stack.rst
+   asyncio-graph.rst
 
 .. toctree::
    :caption: Low-level APIs
diff --git a/Lib/asyncio/__init__.py b/Lib/asyncio/__init__.py
@@ -14,7 +14,7 @@
 from .protocols import *
 from .runners import *
 from .queues import *
-from .stack import *
+from .graph import *
 from .streams import *
 from .subprocess import *
 from .tasks import *
@@ -32,7 +32,7 @@
            protocols.__all__ +
            runners.__all__ +
            queues.__all__ +
-           stack.__all__ +
+           graph.__all__ +
            streams.__all__ +
            subprocess.__all__ +
            tasks.__all__ +
diff --git a/Lib/asyncio/graph.py b/Lib/asyncio/graph.py
@@ -1,4 +1,4 @@
-"""Introspection utils for tasks call stacks."""
+"""Introspection utils for tasks call graphs."""
 
 import dataclasses
 import sys
@@ -18,7 +18,7 @@
 
 # Sadly, we can't re-use the traceback's module datastructures as those
 # are tailored for error reporting, whereas we need to represent an
-# async call stack.
+# async call graph.
 #
 # Going with pretty verbose names as we'd like to export them to the
 # top level asyncio namespace, and want to avoid future name clashes.
@@ -36,7 +36,7 @@ class FutureCallGraph:
     awaited_by: list[FutureCallGraph]
 
 
-def _build_stack_for_future(future: futures.Future) -> FutureCallGraph:
+def _build_graph_for_future(future: futures.Future) -> FutureCallGraph:
     if not isinstance(future, futures.Future):
         raise TypeError(
             f"{future!r} object does not appear to be compatible "
@@ -64,7 +64,7 @@ def _build_stack_for_future(future: futures.Future) -> FutureCallGraph:
 
     if future._asyncio_awaited_by:
         for parent in future._asyncio_awaited_by:
-            awaited_by.append(_build_stack_for_future(parent))
+            awaited_by.append(_build_graph_for_future(parent))
 
     st.reverse()
     return FutureCallGraph(future, st, awaited_by)
@@ -75,9 +75,9 @@ def capture_call_graph(
     future: futures.Future | None = None,
     depth: int = 1,
 ) -> FutureCallGraph | None:
-    """Capture async call stack for the current task or the provided Future.
+    """Capture async call graph for the current task or the provided Future.
 
-    The stack is represented with three data structures:
+    The graph is represented with three data structures:
 
     * FutureCallGraph(future, call_stack, awaited_by)
 
@@ -109,7 +109,7 @@ def capture_call_graph(
         # if yes - check if the passed future is the currently
         # running task or not.
         if loop is None or future is not tasks.current_task(loop=loop):
-            return _build_stack_for_future(future)
+            return _build_graph_for_future(future)
         # else: future is the current task, move on.
     else:
         if loop is None:
@@ -151,7 +151,7 @@ def capture_call_graph(
     awaited_by = []
     if future._asyncio_awaited_by:
         for parent in future._asyncio_awaited_by:
-            awaited_by.append(_build_stack_for_future(parent))
+            awaited_by.append(_build_graph_for_future(parent))
 
     return FutureCallGraph(future, call_stack, awaited_by)
 
@@ -162,7 +162,7 @@ def print_call_graph(
     file: typing.TextIO | None = None,
     depth: int = 1,
 ) -> None:
-    """Print async call stack for the current task or the provided Future."""
+    """Print async call graph for the current task or the provided Future."""
 
     def render_level(st: FutureCallGraph, buf: list[str], level: int) -> None:
         def add_line(line: str) -> None:
@@ -221,16 +221,16 @@ def add_line(line: str) -> None:
             for fut in st.awaited_by:
                 render_level(fut, buf, level + 1)
 
-    stack = capture_call_graph(future=future, depth=depth + 1)
-    if stack is None:
+    graph = capture_call_graph(future=future, depth=depth + 1)
+    if graph is None:
         return
 
     try:
         buf: list[str] = []
-        render_level(stack, buf, 0)
+        render_level(graph, buf, 0)
         rendered = '\n'.join(buf)
         print(rendered, file=file)
     finally:
-        # 'stack' has references to frames so we should
+        # 'graph' has references to frames so we should
         # make sure it's GC'ed as soon as we don't need it.
-        del stack
+        del graph
diff --git a/Lib/test/test_asyncio/test_graph.py b/Lib/test/test_asyncio/test_graph.py
