[3.13] gh-120773: document introspective attributes of an async generator object in the inspect module (GH-120778) (#120827)

gh-120773: document introspective attributes of an async generator object in the inspect module (GH-120778)
(cherry picked from commit 83d3d7aace32b8536f552f78dd29610344f13160)

Co-authored-by: blhsing <blhsing@gmail.com>

1 files changed, 227 insertions, 214 deletions

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 0ec7d7c..7838eee 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -42,220 +42,233 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 .. this function name is too big to fit in the ascii-art table below
 .. |coroutine-origin-link| replace:: :func:`sys.set_coroutine_origin_tracking_depth`
 
-+-----------+-------------------+---------------------------+
-| Type      | Attribute         | Description               |
-+===========+===================+===========================+
-| class     | __doc__           | documentation string      |
-+-----------+-------------------+---------------------------+
-|           | __name__          | name with which this      |
-|           |                   | class was defined         |
-+-----------+-------------------+---------------------------+
-|           | __qualname__      | qualified name            |
-+-----------+-------------------+---------------------------+
-|           | __module__        | name of module in which   |
-|           |                   | this class was defined    |
-+-----------+-------------------+---------------------------+
-|           | __type_params__   | A tuple containing the    |
-|           |                   | :ref:`type parameters     |
-|           |                   | <type-params>` of         |
-|           |                   | a generic class           |
-+-----------+-------------------+---------------------------+
-| method    | __doc__           | documentation string      |
-+-----------+-------------------+---------------------------+
-|           | __name__          | name with which this      |
-|           |                   | method was defined        |
-+-----------+-------------------+---------------------------+
-|           | __qualname__      | qualified name            |
-+-----------+-------------------+---------------------------+
-|           | __func__          | function object           |
-|           |                   | containing implementation |
-|           |                   | of method                 |
-+-----------+-------------------+---------------------------+
-|           | __self__          | instance to which this    |
-|           |                   | method is bound, or       |
-|           |                   | ``None``                  |
-+-----------+-------------------+---------------------------+
-|           | __module__        | name of module in which   |
-|           |                   | this method was defined   |
-+-----------+-------------------+---------------------------+
-| function  | __doc__           | documentation string      |
-+-----------+-------------------+---------------------------+
-|           | __name__          | name with which this      |
-|           |                   | function was defined      |
-+-----------+-------------------+---------------------------+
-|           | __qualname__      | qualified name            |
-+-----------+-------------------+---------------------------+
-|           | __code__          | code object containing    |
-|           |                   | compiled function         |
-|           |                   | :term:`bytecode`          |
-+-----------+-------------------+---------------------------+
-|           | __defaults__      | tuple of any default      |
-|           |                   | values for positional or  |
-|           |                   | keyword parameters        |
-+-----------+-------------------+---------------------------+
-|           | __kwdefaults__    | mapping of any default    |
-|           |                   | values for keyword-only   |
-|           |                   | parameters                |
-+-----------+-------------------+---------------------------+
-|           | __globals__       | global namespace in which |
-|           |                   | this function was defined |
-+-----------+-------------------+---------------------------+
-|           | __builtins__      | builtins namespace        |
-+-----------+-------------------+---------------------------+
-|           | __annotations__   | mapping of parameters     |
-|           |                   | names to annotations;     |
-|           |                   | ``"return"`` key is       |
-|           |                   | reserved for return       |
-|           |                   | annotations.              |
-+-----------+-------------------+---------------------------+
-|           | __type_params__   | A tuple containing the    |
-|           |                   | :ref:`type parameters     |
-|           |                   | <type-params>` of         |
-|           |                   | a generic function        |
-+-----------+-------------------+---------------------------+
-|           | __module__        | name of module in which   |
-|           |                   | this function was defined |
-+-----------+-------------------+---------------------------+
-| traceback | tb_frame          | frame object at this      |
-|           |                   | level                     |
-+-----------+-------------------+---------------------------+
-|           | tb_lasti          | index of last attempted   |
-|           |                   | instruction in bytecode   |
-+-----------+-------------------+---------------------------+
-|           | tb_lineno         | current line number in    |
-|           |                   | Python source code        |
-+-----------+-------------------+---------------------------+
-|           | tb_next           | next inner traceback      |
-|           |                   | object (called by this    |
-|           |                   | level)                    |
-+-----------+-------------------+---------------------------+
-| frame     | f_back            | next outer frame object   |
-|           |                   | (this frame's caller)     |
-+-----------+-------------------+---------------------------+
-|           | f_builtins        | builtins namespace seen   |
-|           |                   | by this frame             |
-+-----------+-------------------+---------------------------+
-|           | f_code            | code object being         |
-|           |                   | executed in this frame    |
-+-----------+-------------------+---------------------------+
-|           | f_globals         | global namespace seen by  |
-|           |                   | this frame                |
-+-----------+-------------------+---------------------------+
-|           | f_lasti           | index of last attempted   |
-|           |                   | instruction in bytecode   |
-+-----------+-------------------+---------------------------+
-|           | f_lineno          | current line number in    |
-|           |                   | Python source code        |
-+-----------+-------------------+---------------------------+
-|           | f_locals          | local namespace seen by   |
-|           |                   | this frame                |
-+-----------+-------------------+---------------------------+
-|           | f_trace           | tracing function for this |
-|           |                   | frame, or ``None``        |
-+-----------+-------------------+---------------------------+
-| code      | co_argcount       | number of arguments (not  |
-|           |                   | including keyword only    |
-|           |                   | arguments, \* or \*\*     |
-|           |                   | args)                     |
-+-----------+-------------------+---------------------------+
-|           | co_code           | string of raw compiled    |
-|           |                   | bytecode                  |
-+-----------+-------------------+---------------------------+
-|           | co_cellvars       | tuple of names of cell    |
-|           |                   | variables (referenced by  |
-|           |                   | containing scopes)        |
-+-----------+-------------------+---------------------------+
-|           | co_consts         | tuple of constants used   |
-|           |                   | in the bytecode           |
-+-----------+-------------------+---------------------------+
-|           | co_filename       | name of file in which     |
-|           |                   | this code object was      |
-|           |                   | created                   |
-+-----------+-------------------+---------------------------+
-|           | co_firstlineno    | number of first line in   |
-|           |                   | Python source code        |
-+-----------+-------------------+---------------------------+
-|           | co_flags          | bitmap of ``CO_*`` flags, |
-|           |                   | read more :ref:`here      |
-|           |                   | <inspect-module-co-flags>`|
-+-----------+-------------------+---------------------------+
-|           | co_lnotab         | encoded mapping of line   |
-|           |                   | numbers to bytecode       |
-|           |                   | indices                   |
-+-----------+-------------------+---------------------------+
-|           | co_freevars       | tuple of names of free    |
-|           |                   | variables (referenced via |
-|           |                   | a function's closure)     |
-+-----------+-------------------+---------------------------+
-|           | co_posonlyargcount| number of positional only |
-|           |                   | arguments                 |
-+-----------+-------------------+---------------------------+
-|           | co_kwonlyargcount | number of keyword only    |
-|           |                   | arguments (not including  |
-|           |                   | \*\* arg)                 |
-+-----------+-------------------+---------------------------+
-|           | co_name           | name with which this code |
-|           |                   | object was defined        |
-+-----------+-------------------+---------------------------+
-|           | co_qualname       | fully qualified name with |
-|           |                   | which this code object    |
-|           |                   | was defined               |
-+-----------+-------------------+---------------------------+
-|           | co_names          | tuple of names other      |
-|           |                   | than arguments and        |
-|           |                   | function locals           |
-+-----------+-------------------+---------------------------+
-|           | co_nlocals        | number of local variables |
-+-----------+-------------------+---------------------------+
-|           | co_stacksize      | virtual machine stack     |
-|           |                   | space required            |
-+-----------+-------------------+---------------------------+
-|           | co_varnames       | tuple of names of         |
-|           |                   | arguments and local       |
-|           |                   | variables                 |
-+-----------+-------------------+---------------------------+
-| generator | __name__          | name                      |
-+-----------+-------------------+---------------------------+
-|           | __qualname__      | qualified name            |
-+-----------+-------------------+---------------------------+
-|           | gi_frame          | frame                     |
-+-----------+-------------------+---------------------------+
-|           | gi_running        | is the generator running? |
-+-----------+-------------------+---------------------------+
-|           | gi_code           | code                      |
-+-----------+-------------------+---------------------------+
-|           | gi_yieldfrom      | object being iterated by  |
-|           |                   | ``yield from``, or        |
-|           |                   | ``None``                  |
-+-----------+-------------------+---------------------------+
-| coroutine | __name__          | name                      |
-+-----------+-------------------+---------------------------+
-|           | __qualname__      | qualified name            |
-+-----------+-------------------+---------------------------+
-|           | cr_await          | object being awaited on,  |
-|           |                   | or ``None``               |
-+-----------+-------------------+---------------------------+
-|           | cr_frame          | frame                     |
-+-----------+-------------------+---------------------------+
-|           | cr_running        | is the coroutine running? |
-+-----------+-------------------+---------------------------+
-|           | cr_code           | code                      |
-+-----------+-------------------+---------------------------+
-|           | cr_origin         | where coroutine was       |
-|           |                   | created, or ``None``. See |
-|           |                   | |coroutine-origin-link|   |
-+-----------+-------------------+---------------------------+
-| builtin   | __doc__           | documentation string      |
-+-----------+-------------------+---------------------------+
-|           | __name__          | original name of this     |
-|           |                   | function or method        |
-+-----------+-------------------+---------------------------+
-|           | __qualname__      | qualified name            |
-+-----------+-------------------+---------------------------+
-|           | __self__          | instance to which a       |
-|           |                   | method is bound, or       |
-|           |                   | ``None``                  |
-+-----------+-------------------+---------------------------+
++-----------------+-------------------+---------------------------+
+| Type            | Attribute         | Description               |
++=================+===================+===========================+
+| class           | __doc__           | documentation string      |
++-----------------+-------------------+---------------------------+
+|                 | __name__          | name with which this      |
+|                 |                   | class was defined         |
++-----------------+-------------------+---------------------------+
+|                 | __qualname__      | qualified name            |
++-----------------+-------------------+---------------------------+
+|                 | __module__        | name of module in which   |
+|                 |                   | this class was defined    |
++-----------------+-------------------+---------------------------+
+|                 | __type_params__   | A tuple containing the    |
+|                 |                   | :ref:`type parameters     |
+|                 |                   | <type-params>` of         |
+|                 |                   | a generic class           |
++-----------------+-------------------+---------------------------+
+| method          | __doc__           | documentation string      |
++-----------------+-------------------+---------------------------+
+|                 | __name__          | name with which this      |
+|                 |                   | method was defined        |
++-----------------+-------------------+---------------------------+
+|                 | __qualname__      | qualified name            |
++-----------------+-------------------+---------------------------+
+|                 | __func__          | function object           |
+|                 |                   | containing implementation |
+|                 |                   | of method                 |
++-----------------+-------------------+---------------------------+
+|                 | __self__          | instance to which this    |
+|                 |                   | method is bound, or       |
+|                 |                   | ``None``                  |
++-----------------+-------------------+---------------------------+
+|                 | __module__        | name of module in which   |
+|                 |                   | this method was defined   |
++-----------------+-------------------+---------------------------+
+| function        | __doc__           | documentation string      |
++-----------------+-------------------+---------------------------+
+|                 | __name__          | name with which this      |
+|                 |                   | function was defined      |
++-----------------+-------------------+---------------------------+
+|                 | __qualname__      | qualified name            |
++-----------------+-------------------+---------------------------+
+|                 | __code__          | code object containing    |
+|                 |                   | compiled function         |
+|                 |                   | :term:`bytecode`          |
++-----------------+-------------------+---------------------------+
+|                 | __defaults__      | tuple of any default      |
+|                 |                   | values for positional or  |
+|                 |                   | keyword parameters        |
++-----------------+-------------------+---------------------------+
+|                 | __kwdefaults__    | mapping of any default    |
+|                 |                   | values for keyword-only   |
+|                 |                   | parameters                |
++-----------------+-------------------+---------------------------+
+|                 | __globals__       | global namespace in which |
+|                 |                   | this function was defined |
++-----------------+-------------------+---------------------------+
+|                 | __builtins__      | builtins namespace        |
++-----------------+-------------------+---------------------------+
+|                 | __annotations__   | mapping of parameters     |
+|                 |                   | names to annotations;     |
+|                 |                   | ``"return"`` key is       |
+|                 |                   | reserved for return       |
+|                 |                   | annotations.              |
++-----------------+-------------------+---------------------------+
+|                 | __type_params__   | A tuple containing the    |
+|                 |                   | :ref:`type parameters     |
+|                 |                   | <type-params>` of         |
+|                 |                   | a generic function        |
++-----------------+-------------------+---------------------------+
+|                 | __module__        | name of module in which   |
+|                 |                   | this function was defined |
++-----------------+-------------------+---------------------------+
+| traceback       | tb_frame          | frame object at this      |
+|                 |                   | level                     |
++-----------------+-------------------+---------------------------+
+|                 | tb_lasti          | index of last attempted   |
+|                 |                   | instruction in bytecode   |
++-----------------+-------------------+---------------------------+
+|                 | tb_lineno         | current line number in    |
+|                 |                   | Python source code        |
++-----------------+-------------------+---------------------------+
+|                 | tb_next           | next inner traceback      |
+|                 |                   | object (called by this    |
+|                 |                   | level)                    |
++-----------------+-------------------+---------------------------+
+| frame           | f_back            | next outer frame object   |
+|                 |                   | (this frame's caller)     |
++-----------------+-------------------+---------------------------+
+|                 | f_builtins        | builtins namespace seen   |
+|                 |                   | by this frame             |
++-----------------+-------------------+---------------------------+
+|                 | f_code            | code object being         |
+|                 |                   | executed in this frame    |
++-----------------+-------------------+---------------------------+
+|                 | f_globals         | global namespace seen by  |
+|                 |                   | this frame                |
++-----------------+-------------------+---------------------------+
+|                 | f_lasti           | index of last attempted   |
+|                 |                   | instruction in bytecode   |
++-----------------+-------------------+---------------------------+
+|                 | f_lineno          | current line number in    |
+|                 |                   | Python source code        |
++-----------------+-------------------+---------------------------+
+|                 | f_locals          | local namespace seen by   |
+|                 |                   | this frame                |
++-----------------+-------------------+---------------------------+
+|                 | f_trace           | tracing function for this |
+|                 |                   | frame, or ``None``        |
++-----------------+-------------------+---------------------------+
+| code            | co_argcount       | number of arguments (not  |
+|                 |                   | including keyword only    |
+|                 |                   | arguments, \* or \*\*     |
+|                 |                   | args)                     |
++-----------------+-------------------+---------------------------+
+|                 | co_code           | string of raw compiled    |
+|                 |                   | bytecode                  |
++-----------------+-------------------+---------------------------+
+|                 | co_cellvars       | tuple of names of cell    |
+|                 |                   | variables (referenced by  |
+|                 |                   | containing scopes)        |
++-----------------+-------------------+---------------------------+
+|                 | co_consts         | tuple of constants used   |
+|                 |                   | in the bytecode           |
++-----------------+-------------------+---------------------------+
+|                 | co_filename       | name of file in which     |
+|                 |                   | this code object was      |
+|                 |                   | created                   |
++-----------------+-------------------+---------------------------+
+|                 | co_firstlineno    | number of first line in   |
+|                 |                   | Python source code        |
++-----------------+-------------------+---------------------------+
+|                 | co_flags          | bitmap of ``CO_*`` flags, |
+|                 |                   | read more :ref:`here      |
+|                 |                   | <inspect-module-co-flags>`|
++-----------------+-------------------+---------------------------+
+|                 | co_lnotab         | encoded mapping of line   |
+|                 |                   | numbers to bytecode       |
+|                 |                   | indices                   |
++-----------------+-------------------+---------------------------+
+|                 | co_freevars       | tuple of names of free    |
+|                 |                   | variables (referenced via |
+|                 |                   | a function's closure)     |
++-----------------+-------------------+---------------------------+
+|                 | co_posonlyargcount| number of positional only |
+|                 |                   | arguments                 |
++-----------------+-------------------+---------------------------+
+|                 | co_kwonlyargcount | number of keyword only    |
+|                 |                   | arguments (not including  |
+|                 |                   | \*\* arg)                 |
++-----------------+-------------------+---------------------------+
+|                 | co_name           | name with which this code |
+|                 |                   | object was defined        |
++-----------------+-------------------+---------------------------+
+|                 | co_qualname       | fully qualified name with |
+|                 |                   | which this code object    |
+|                 |                   | was defined               |
++-----------------+-------------------+---------------------------+
+|                 | co_names          | tuple of names other      |
+|                 |                   | than arguments and        |
+|                 |                   | function locals           |
++-----------------+-------------------+---------------------------+
+|                 | co_nlocals        | number of local variables |
++-----------------+-------------------+---------------------------+
+|                 | co_stacksize      | virtual machine stack     |
+|                 |                   | space required            |
++-----------------+-------------------+---------------------------+
+|                 | co_varnames       | tuple of names of         |
+|                 |                   | arguments and local       |
+|                 |                   | variables                 |
++-----------------+-------------------+---------------------------+
+| generator       | __name__          | name                      |
++-----------------+-------------------+---------------------------+
+|                 | __qualname__      | qualified name            |
++-----------------+-------------------+---------------------------+
+|                 | gi_frame          | frame                     |
++-----------------+-------------------+---------------------------+
+|                 | gi_running        | is the generator running? |
++-----------------+-------------------+---------------------------+
+|                 | gi_code           | code                      |
++-----------------+-------------------+---------------------------+
+|                 | gi_yieldfrom      | object being iterated by  |
+|                 |                   | ``yield from``, or        |
+|                 |                   | ``None``                  |
++-----------------+-------------------+---------------------------+
+| async generator | __name__          | name                      |
++-----------------+-------------------+---------------------------+
+|                 | __qualname__      | qualified name            |
++-----------------+-------------------+---------------------------+
+|                 | ag_await          | object being awaited on,  |
+|                 |                   | or ``None``               |
++-----------------+-------------------+---------------------------+
+|                 | ag_frame          | frame                     |
++-----------------+-------------------+---------------------------+
+|                 | ag_running        | is the generator running? |
++-----------------+-------------------+---------------------------+
+|                 | ag_code           | code                      |
++-----------------+-------------------+---------------------------+
+| coroutine       | __name__          | name                      |
++-----------------+-------------------+---------------------------+
+|                 | __qualname__      | qualified name            |
++-----------------+-------------------+---------------------------+
+|                 | cr_await          | object being awaited on,  |
+|                 |                   | or ``None``               |
++-----------------+-------------------+---------------------------+
+|                 | cr_frame          | frame                     |
++-----------------+-------------------+---------------------------+
+|                 | cr_running        | is the coroutine running? |
++-----------------+-------------------+---------------------------+
+|                 | cr_code           | code                      |
++-----------------+-------------------+---------------------------+
+|                 | cr_origin         | where coroutine was       |
+|                 |                   | created, or ``None``. See |
+|                 |                   | |coroutine-origin-link|   |
++-----------------+-------------------+---------------------------+
+| builtin         | __doc__           | documentation string      |
++-----------------+-------------------+---------------------------+
+|                 | __name__          | original name of this     |
+|                 |                   | function or method        |
++-----------------+-------------------+---------------------------+
+|                 | __qualname__      | qualified name            |
++-----------------+-------------------+---------------------------+
+|                 | __self__          | instance to which a       |
+|                 |                   | method is bound, or       |
+|                 |                   | ``None``                  |
++-----------------+-------------------+---------------------------+
 
 .. versionchanged:: 3.5