bpo-26985: Add missing info of code object in inspect documentation (GH-1090)

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 4ff2187b45f8ebf7e0a3b2f2d3ab64f9eeeb29ae..6be28a2b31cb66ac9ac53529a47b1e7954d318cd 100644 (file)
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -34,185 +34,198 @@ provided as convenient choices for the second argument to :func:`getmembers`.
 They also help you determine when you can expect to find the following special
 attributes:
 
-+-----------+-----------------+---------------------------+
-| Type      | Attribute       | Description               |
-+===========+=================+===========================+
-| module    | __doc__         | documentation string      |
-+-----------+-----------------+---------------------------+
-|           | __file__        | filename (missing for     |
-|           |                 | built-in modules)         |
-+-----------+-----------------+---------------------------+
-| 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    |
-+-----------+-----------------+---------------------------+
-| 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``                  |
-+-----------+-----------------+---------------------------+
-| 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 |
-+-----------+-----------------+---------------------------+
-|           | __annotations__ | mapping of parameters     |
-|           |                 | names to annotations;     |
-|           |                 | ``"return"`` key is       |
-|           |                 | reserved for return       |
-|           |                 | annotations.              |
-+-----------+-----------------+---------------------------+
-| 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_restricted    | 0 or 1 if frame is in     |
-|           |                 | restricted execution mode |
-+-----------+-----------------+---------------------------+
-|           | f_trace         | tracing function for this |
-|           |                 | frame, or ``None``        |
-+-----------+-----------------+---------------------------+
-| code      | co_argcount     | number of arguments (not  |
-|           |                 | including \* or \*\*      |
-|           |                 | args)                     |
-+-----------+-----------------+---------------------------+
-|           | co_code         | string of raw compiled    |
-|           |                 | bytecode                  |
-+-----------+-----------------+---------------------------+
-|           | 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_name         | name with which this code |
-|           |                 | object was defined        |
-+-----------+-----------------+---------------------------+
-|           | co_names        | tuple of names of local   |
-|           |                 | variables                 |
-+-----------+-----------------+---------------------------+
-|           | 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                      |
-+-----------+-----------------+---------------------------+
-| 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               |
++===========+===================+===========================+
+| module    | __doc__           | documentation string      |
++-----------+-------------------+---------------------------+
+|           | __file__          | filename (missing for     |
+|           |                   | built-in modules)         |
++-----------+-------------------+---------------------------+
+| 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    |
++-----------+-------------------+---------------------------+
+| 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``                  |
++-----------+-------------------+---------------------------+
+| 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 |
++-----------+-------------------+---------------------------+
+|           | __annotations__   | mapping of parameters     |
+|           |                   | names to annotations;     |
+|           |                   | ``"return"`` key is       |
+|           |                   | reserved for return       |
+|           |                   | annotations.              |
++-----------+-------------------+---------------------------+
+| 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_restricted      | 0 or 1 if frame is in     |
+|           |                   | restricted execution mode |
++-----------+-------------------+---------------------------+
+|           | 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_kwonlyargcount | number of keyword only    |
+|           |                   | arguments (not including  |
+|           |                   | \*\* arg)                 |
++-----------+-------------------+---------------------------+
+|           | co_name           | name with which this code |
+|           |                   | object was defined        |
++-----------+-------------------+---------------------------+
+|           | co_names          | tuple of names of local   |
+|           |                   | variables                 |
++-----------+-------------------+---------------------------+
+|           | 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                      |
++-----------+-------------------+---------------------------+
+| 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
 
@@ -1268,6 +1281,10 @@ Code Objects Bit Flags
 Python code objects have a ``co_flags`` attribute, which is a bitmap of
 the following flags:
 
+.. data:: CO_OPTIMIZED
+
+   The code object is optimized, using fast locals.
+
 .. data:: CO_NEWLOCALS
 
    If set, a new dict will be created for the frame's ``f_locals`` when
@@ -1281,6 +1298,10 @@ the following flags:
 
    The code object has a variable keyword parameter (``**kwargs``-like).
 
+.. data:: CO_NESTED
+
+   The flag is set when the code object is a nested function.
+
 .. data:: CO_GENERATOR
 
    The flag is set when the code object is a generator function, i.e.

diff --git a/Lib/inspect.py b/Lib/inspect.py
index 4d56ef5d41b47f700c25434f0334e64c5df2878c..a2dcb888a0c6094f768d6c83ecdb367b88da0eea 100644 (file)
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -253,18 +253,24 @@ def iscode(object):
     """Return true if the object is a code object.
 
     Code objects provide these attributes:
-        co_argcount     number of arguments (not including * or ** args)
-        co_code         string of raw compiled bytecode
-        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: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
-        co_lnotab       encoded mapping of line numbers to bytecode indices
-        co_name         name with which this code object was defined
-        co_names        tuple of names of local variables
-        co_nlocals      number of local variables
-        co_stacksize    virtual machine stack space required
-        co_varnames     tuple of names of arguments and local variables"""
+        co_argcount         number of arguments (not including *, ** args
+                            or keyword only arguments)
+        co_code             string of raw compiled bytecode
+        co_cellvars         tuple of names of cell variables
+        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: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
+                            | 16=nested | 32=generator | 64=nofree | 128=coroutine
+                            | 256=iterable_coroutine | 512=async_generator
+        co_freevars         tuple of names of free variables
+        co_kwonlyargcount   number of keyword only arguments (not including ** arg)
+        co_lnotab           encoded mapping of line numbers to bytecode indices
+        co_name             name with which this code object was defined
+        co_names            tuple of names of local variables
+        co_nlocals          number of local variables
+        co_stacksize        virtual machine stack space required
+        co_varnames         tuple of names of arguments and local variables"""
     return isinstance(object, types.CodeType)
 
 def isbuiltin(object):

diff --git a/Misc/NEWS b/Misc/NEWS
index b6f8c7094c9ef5db138d59ede2483d64a18c90cd..440f0b25cb682b4545bebb3d5ade6321f9786fac 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -945,6 +945,8 @@ C API
 Documentation
 -------------
 
+- bpo-26985: Add missing info of code object in inspect documentation.
+
 - bpo-19824, bpo-20314, bpo-12518: Improve the documentation for, and links
   to, template strings by emphasizing their utility for internationalization,
   and by clarifying some usage constraints.