Skip to content

Commit 5d2b036

Browse files
committed
Update documentation to reflect enhanced async debugging output
This commit updates the What's New documentation to showcase the improved async debugging capabilities introduced in the remote debugging module and asyncio tools. The documentation now demonstrates the enhanced output format that provides much more detailed execution information. The key documentation updates include: 1. Updated example output showing both "coroutine stack" and "awaiter chain" columns in the table format, clearly distinguishing between internal task execution state and external dependencies. 2. Enhanced tree output examples that include function names and complete file paths with line numbers, making the debugging information much more actionable for developers. 3. Addition of cycle detection error example showing how the tools handle problematic await patterns that could indicate programming issues. The updated examples demonstrate how the enhanced debugging output transforms from showing basic file paths to revealing detailed function call stacks and execution context. This improvement makes it significantly easier for developers to understand complex async execution patterns and debug issues in production asyncio applications, especially when dealing with nested coroutines and complex task hierarchies.
1 parent e17e3fa commit 5d2b036

File tree

1 file changed

+37
-22
lines changed

1 file changed

+37
-22
lines changed

Doc/whatsnew/3.14.rst

Lines changed: 37 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -816,43 +816,58 @@ Executing the new tool on the running process will yield a table like this:
816816
817817
python -m asyncio ps 12345
818818
819-
tid task id task name coroutine chain awaiter name awaiter id
820-
---------------------------------------------------------------------------------------------------------------------------------------
821-
8138752 0x564bd3d0210 Task-1 0x0
822-
8138752 0x564bd3d0410 Sundowning _aexit -> __aexit__ -> main Task-1 0x564bd3d0210
823-
8138752 0x564bd3d0610 TMBTE _aexit -> __aexit__ -> main Task-1 0x564bd3d0210
824-
8138752 0x564bd3d0810 TNDNBTG _aexit -> __aexit__ -> album Sundowning 0x564bd3d0410
825-
8138752 0x564bd3d0a10 Levitate _aexit -> __aexit__ -> album Sundowning 0x564bd3d0410
826-
8138752 0x564bd3e0550 DYWTYLM _aexit -> __aexit__ -> album TMBTE 0x564bd3d0610
827-
8138752 0x564bd3e0710 Aqua Regia _aexit -> __aexit__ -> album TMBTE 0x564bd3d0610
828-
829-
830-
or:
819+
tid task id task name coroutine stack awaiter chain awaiter name awaiter id
820+
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
821+
1935500 0x7fc930c18050 Task-1 TaskGroup._aexit -> TaskGroup.__aexit__ -> main 0x0
822+
1935500 0x7fc930c18230 Sundowning TaskGroup._aexit -> TaskGroup.__aexit__ -> album TaskGroup._aexit -> TaskGroup.__aexit__ -> main Task-1 0x7fc930c18050
823+
1935500 0x7fc93173fa50 TMBTE TaskGroup._aexit -> TaskGroup.__aexit__ -> album TaskGroup._aexit -> TaskGroup.__aexit__ -> main Task-1 0x7fc930c18050
824+
1935500 0x7fc93173fdf0 TNDNBTG sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album Sundowning 0x7fc930c18230
825+
1935500 0x7fc930d32510 Levitate sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album Sundowning 0x7fc930c18230
826+
1935500 0x7fc930d32890 DYWTYLM sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album TMBTE 0x7fc93173fa50
827+
1935500 0x7fc93161ec30 Aqua Regia sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album TMBTE 0x7fc93173fa50
828+
829+
or a tree like this:
831830

832831
.. code-block:: bash
833832
834833
python -m asyncio pstree 12345
835834
836835
└── (T) Task-1
837-
└── main
838-
└── __aexit__
839-
└── _aexit
836+
└── main example.py:13
837+
└── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
838+
└── TaskGroup._aexit Lib/asyncio/taskgroups.py:121
840839
├── (T) Sundowning
841-
│ └── album
842-
│ └── __aexit__
843-
│ └── _aexit
840+
│ └── album example.py:8
841+
│ └── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
842+
│ └── TaskGroup._aexit Lib/asyncio/taskgroups.py:121
844843
│ ├── (T) TNDNBTG
844+
│ │ └── play example.py:4
845+
│ │ └── sleep Lib/asyncio/tasks.py:702
845846
│ └── (T) Levitate
847+
│ └── play example.py:4
848+
│ └── sleep Lib/asyncio/tasks.py:702
846849
└── (T) TMBTE
847-
└── album
848-
└── __aexit__
849-
└── _aexit
850+
└── album example.py:8
851+
└── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
852+
└── TaskGroup._aexit Lib/asyncio/taskgroups.py:121
850853
├── (T) DYWTYLM
854+
│ └── play example.py:4
855+
│ └── sleep Lib/asyncio/tasks.py:702
851856
└── (T) Aqua Regia
857+
└── play example.py:4
858+
└── sleep Lib/asyncio/tasks.py:702
852859
853860
If a cycle is detected in the async await graph (which could indicate a
854861
programming issue), the tool raises an error and lists the cycle paths that
855-
prevent tree construction.
862+
prevent tree construction:
863+
864+
.. code-block:: bash
865+
866+
python -m asyncio pstree 12345
867+
868+
ERROR: await-graph contains cycles - cannot print a tree!
869+
870+
cycle: Task-2 → Task-3 → Task-2
856871
857872
(Contributed by Pablo Galindo, Łukasz Langa, Yury Selivanov, and Marta
858873
Gomez Macias in :gh:`91048`.)

0 commit comments

Comments
 (0)