gh-122058: Lib/inspect: Update docstrings for isfunction, isgenerator, isframe, iscode. (#122059)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Victor Stinner <vstinner@python.org>

Author: 3 people

Doc/library/inspect.rst

@@ -153,6 +153,19 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 |                 | f_trace           | tracing function for this |
 |                 |                   | frame, or ``None``        |
 +-----------------+-------------------+---------------------------+
+|                 | f_trace_lines     | indicate whether a        |
+|                 |                   | tracing event is          |
+|                 |                   | triggered for each source |
+|                 |                   | source line               |
++-----------------+-------------------+---------------------------+
+|                 | f_trace_opcodes   | indicate whether          |
+|                 |                   | per-opcode events are     |
+|                 |                   | requested                 |
++-----------------+-------------------+---------------------------+
+|                 | clear()           | used to clear all         |
+|                 |                   | references to local       |
+|                 |                   | variables                 |
++-----------------+-------------------+---------------------------+
 | code            | co_argcount       | number of arguments (not  |
 |                 |                   | including keyword only    |
 |                 |                   | arguments, \* or \*\*     |
@@ -214,6 +227,18 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
 |                 |                   | arguments and local       |
 |                 |                   | variables                 |
 +-----------------+-------------------+---------------------------+
+|                 | co_lines()        | returns an iterator that  |
+|                 |                   | yields successive         |
+|                 |                   | bytecode ranges           |
++-----------------+-------------------+---------------------------+
+|                 | co_positions()    | returns an iterator of    |
+|                 |                   | source code positions for |
+|                 |                   | each bytecode instruction |
++-----------------+-------------------+---------------------------+
+|                 | replace()         | returns a copy of the     |
+|                 |                   | code object with new      |
+|                 |                   | values                    |
++-----------------+-------------------+---------------------------+
 | generator       | __name__          | name                      |
 +-----------------+-------------------+---------------------------+
 |                 | __qualname__      | qualified name            |

Lib/inspect.py

@@ -264,11 +264,16 @@ def isfunction(object):
     Function objects provide these attributes:
         __doc__         documentation string
         __name__        name with which this function was defined
+        __qualname__    qualified name of this function
+        __module__      name of the module the function was defined in or None
         __code__        code object containing compiled function bytecode
         __defaults__    tuple of any default values for arguments
         __globals__     global namespace in which this function was defined
         __annotations__ dict of parameter annotations
-        __kwdefaults__  dict of keyword only parameters with defaults"""
+        __kwdefaults__  dict of keyword only parameters with defaults
+        __dict__        namespace which is supporting arbitrary function attributes
+        __closure__     a tuple of cells or None
+        __type_params__ tuple of type parameters"""
     return isinstance(object, types.FunctionType)
 
 def _has_code_flag(f, flag):
@@ -333,17 +338,18 @@ def isgenerator(object):
     """Return true if the object is a generator.
 
     Generator objects provide these attributes:
-        __iter__        defined to support iteration over container
-        close           raises a new GeneratorExit exception inside the
-                        generator to terminate the iteration
         gi_code         code object
         gi_frame        frame object or possibly None once the generator has
                         been exhausted
         gi_running      set to 1 when generator is executing, 0 otherwise
-        next            return the next item from the container
-        send            resumes the generator and "sends" a value that becomes
+        gi_yieldfrom    object being iterated by yield from or None
+
+        __iter__()      defined to support iteration over container
+        close()         raises a new GeneratorExit exception inside the
+                        generator to terminate the iteration
+        send()          resumes the generator and "sends" a value that becomes
                         the result of the current yield-expression
-        throw           used to raise an exception inside the generator"""
+        throw()         used to raise an exception inside the generator"""
     return isinstance(object, types.GeneratorType)
 
 def iscoroutine(object):
@@ -378,7 +384,11 @@ def isframe(object):
         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"""
+        f_trace         tracing function for this frame, or None
+        f_trace_lines   is a tracing event triggered for each source line?
+        f_trace_opcodes are per-opcode events being requested?
+
+        clear()          used to clear all references to local variables"""
     return isinstance(object, types.FrameType)
 
 def iscode(object):
@@ -403,7 +413,12 @@ def iscode(object):
         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"""
+        co_varnames         tuple of names of arguments and local variables
+        co_qualname         fully qualified function name
+
+        co_lines()          returns an iterator that yields successive bytecode ranges
+        co_positions()      returns an iterator of source code positions for each bytecode instruction
+        replace()           returns a copy of the code object with a new values"""
     return isinstance(object, types.CodeType)
 
 def isbuiltin(object):

Objects/frameobject.c

@@ -1721,7 +1721,7 @@ frame_clear(PyFrameObject *f, PyObject *Py_UNUSED(ignored))
 }
 
 PyDoc_STRVAR(clear__doc__,
-"F.clear(): clear most references held by the frame");
+"F.clear(): clear all references held by the frame");
 
 static PyObject *
 frame_sizeof(PyFrameObject *f, PyObject *Py_UNUSED(ignored))