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

Eclips4 · picnixz · vstinner · web-flow · commit 8ce70d6c697c · 2024-08-06T14:47:31.000+02:00
Co-authored-by: Bénédikt Tran &lt;10796600+picnixz@users.noreply.github.com&gt;
Co-authored-by: Victor Stinner &lt;vstinner@python.org&gt;
diff --git a/Doc/library/inspect.rst b/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            |
diff --git a/Lib/inspect.py b/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):
diff --git a/Objects/frameobject.c b/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))

Original file line number	Diff line number	Diff line change
`@@ -1721,7 +1721,7 @@ frame_clear(PyFrameObject f, PyObject Py_UNUSED(ignored))`
`1721`	`1721`	`}`
`1722`	`1722`
`1723`	`1723`	`PyDoc_STRVAR(clear__doc__,`
`1724`		`-"F.clear(): clear most references held by the frame");`
	`1724`	`+"F.clear(): clear all references held by the frame");`
`1725`	`1725`
`1726`	`1726`	`static PyObject *`
`1727`	`1727`	`frame_sizeof(PyFrameObject f, PyObject Py_UNUSED(ignored))`