merge 3.4 (#23561)

Doc/library/dis.rst

@@ -9,9 +9,9 @@
 --------------
 
 The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
-disassembling it. The CPython bytecode which this module takes as an
+disassembling it. The CPython bytecode which this module takes as an input is
-input is defined in the file :file:`Include/opcode.h` and used by the compiler
+defined in the file :file:`Include/opcode.h` and used by the compiler and the
-and the interpreter.
+interpreter.
 
 .. impl-detail::
 
@@ -43,33 +43,32 @@ Bytecode analysis
 .. versionadded:: 3.4
 
 The bytecode analysis API allows pieces of Python code to be wrapped in a
-:class:`Bytecode` object that provides easy access to details of the
+:class:`Bytecode` object that provides easy access to details of the compiled
-compiled code.
+code.
 
 .. class:: Bytecode(x, *, first_line=None, current_offset=None)
 
-   Analyse the bytecode corresponding to a function, generator, method,
-   string of source code, or a code object (as returned by :func:`compile`).
 
-   This is a convenience wrapper around many of the functions listed below,
+   Analyse the bytecode corresponding to a function, generator, method, string
-   most notably :func:`get_instructions`, as iterating over a
+   of source code, or a code object (as returned by :func:`compile`).
-   :class:`Bytecode` instance yields the bytecode operations as
-   :class:`Instruction` instances.
 
-   If *first_line* is not None, it indicates the line number that should
+   This is a convenience wrapper around many of the functions listed below, most
-   be reported for the first source line in the disassembled code.
+   notably :func:`get_instructions`, as iterating over a :class:`Bytecode`
-   Otherwise, the source line information (if any) is taken directly from
+   instance yields the bytecode operations as :class:`Instruction` instances.
-   the disassembled code object.
 
-   If *current_offset* is not None, it refers to an instruction offset
+   If *first_line* is not None, it indicates the line number that should be
-   in the disassembled code. Setting this means :meth:`dis` will display
+   reported for the first source line in the disassembled code.  Otherwise, the
-   a "current instruction" marker against the specified opcode.
+   source line information (if any) is taken directly from the disassembled code
+   object.
+
+   If *current_offset* is not None, it refers to an instruction offset in the
+   disassembled code. Setting this means :meth:`.dis` will display a "current
+   instruction" marker against the specified opcode.
 
    .. classmethod:: from_traceback(tb)
 
-      Construct a :class:`Bytecode` instance from the given traceback,
+      Construct a :class:`Bytecode` instance from the given traceback, setting
-      setting *current_offset* to the instruction responsible for the
+      *current_offset* to the instruction responsible for the exception.
-      exception.
 
    .. data:: codeobj
 
@@ -81,8 +80,8 @@ compiled code.
 
    .. method:: dis()
 
-      Return a formatted view of the bytecode operations (the same as
+      Return a formatted view of the bytecode operations (the same as printed by
-      printed by :func:`dis`, but returned as a multi-line string).
+      :func:`dis.dis`, but returned as a multi-line string).
 
    .. method:: info()
 
@@ -104,10 +103,9 @@ Example::
 Analysis functions
 ------------------
 
-The :mod:`dis` module also defines the following analysis functions that
+The :mod:`dis` module also defines the following analysis functions that convert
-convert the input directly to the desired output. They can be useful if
+the input directly to the desired output. They can be useful if only a single
-only a single operation is being performed, so the intermediate analysis
+operation is being performed, so the intermediate analysis object isn't useful:
-object isn't useful:
 
 .. function:: code_info(x)
 
@@ -196,13 +194,13 @@ object isn't useful:
    Return an iterator over the instructions in the supplied function, method,
    source code string or code object.
 
-   The iterator generates a series of :class:`Instruction` named tuples
+   The iterator generates a series of :class:`Instruction` named tuples giving
-   giving the details of each operation in the supplied code.
+   the details of each operation in the supplied code.
 
-   If *first_line* is not None, it indicates the line number that should
+   If *first_line* is not None, it indicates the line number that should be
-   be reported for the first source line in the disassembled code.
+   reported for the first source line in the disassembled code.  Otherwise, the
-   Otherwise, the source line information (if any) is taken directly from
+   source line information (if any) is taken directly from the disassembled code
-   the disassembled code object.
+   object.
 
    .. versionadded:: 3.4
 
@@ -511,8 +509,8 @@ the original TOS1.
 .. opcode:: PRINT_EXPR
 
    Implements the expression statement for the interactive mode.  TOS is removed
-   from the stack and printed.  In non-interactive mode, an expression statement is
+   from the stack and printed.  In non-interactive mode, an expression statement
-   terminated with :opcode:`POP_TOP`.
+   is terminated with :opcode:`POP_TOP`.
 
 
 .. opcode:: BREAK_LOOP
@@ -542,9 +540,9 @@ the original TOS1.
    comprehensions.
 
 For all of the :opcode:`SET_ADD`, :opcode:`LIST_APPEND` and :opcode:`MAP_ADD`
-instructions, while the
+instructions, while the added value or key/value pair is popped off, the
-added value or key/value pair is popped off, the container object remains on
+container object remains on the stack so that it is available for further
-the stack so that it is available for further iterations of the loop.
+iterations of the loop.
 
 
 .. opcode:: RETURN_VALUE
@@ -566,23 +564,23 @@ the stack so that it is available for further iterations of the loop.
 
 .. opcode:: IMPORT_STAR
 
-   Loads all symbols not starting with ``'_'`` directly from the module TOS to the
+   Loads all symbols not starting with ``'_'`` directly from the module TOS to
-   local namespace. The module is popped after loading all names. This opcode
+   the local namespace. The module is popped after loading all names. This
-   implements ``from module import *``.
+   opcode implements ``from module import *``.
 
 
 .. opcode:: POP_BLOCK
 
-   Removes one block from the block stack.  Per frame, there is a  stack of blocks,
+   Removes one block from the block stack.  Per frame, there is a stack of
-   denoting nested loops, try statements, and such.
+   blocks, denoting nested loops, try statements, and such.
 
 
 .. opcode:: POP_EXCEPT
 
    Removes one block from the block stack. The popped block must be an exception
-   handler block, as implicitly created when entering an except handler.
+   handler block, as implicitly created when entering an except handler.  In
-   In addition to popping extraneous values from the frame stack, the
+   addition to popping extraneous values from the frame stack, the last three
-   last three popped values are used to restore the exception state.
+   popped values are used to restore the exception state.
 
 
 .. opcode:: END_FINALLY
@@ -612,9 +610,9 @@ the stack so that it is available for further iterations of the loop.
 
 .. opcode:: WITH_CLEANUP
 
-   Cleans up the stack when a :keyword:`with` statement block exits.  TOS is
+   Cleans up the stack when a :keyword:`with` statement block exits.  TOS is the
-   the context manager's :meth:`__exit__` bound method. Below TOS are 1--3
+   context manager's :meth:`__exit__` bound method. Below TOS are 1--3 values
-   values indicating how/why the finally clause was entered:
+   indicating how/why the finally clause was entered:
 
    * SECOND = ``None``
    * (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval
@@ -624,10 +622,10 @@ the stack so that it is available for further iterations of the loop.
    In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise
    ``TOS(None, None, None)``.  In addition, TOS is removed from the stack.
 
-   If the stack represents an exception, *and* the function call returns
+   If the stack represents an exception, *and* the function call returns a
-   a 'true' value, this information is "zapped" and replaced with a single
+   'true' value, this information is "zapped" and replaced with a single
-   ``WHY_SILENCED`` to prevent :opcode:`END_FINALLY` from re-raising the exception.
+   ``WHY_SILENCED`` to prevent :opcode:`END_FINALLY` from re-raising the
-   (But non-local gotos will still be resumed.)
+   exception.  (But non-local gotos will still be resumed.)
 
    .. XXX explain the WHY stuff!
 
@@ -638,8 +636,8 @@ the more significant byte last.
 .. opcode:: STORE_NAME (namei)
 
    Implements ``name = TOS``. *namei* is the index of *name* in the attribute
-   :attr:`co_names` of the code object. The compiler tries to use :opcode:`STORE_FAST`
+   :attr:`co_names` of the code object. The compiler tries to use
-   or :opcode:`STORE_GLOBAL` if possible.
+   :opcode:`STORE_FAST` or :opcode:`STORE_GLOBAL` if possible.
 
 
 .. opcode:: DELETE_NAME (namei)
@@ -699,8 +697,8 @@ the more significant byte last.
 
 .. opcode:: BUILD_TUPLE (count)
 
-   Creates a tuple consuming *count* items from the stack, and pushes the resulting
+   Creates a tuple consuming *count* items from the stack, and pushes the
-   tuple onto the stack.
+   resulting tuple onto the stack.
 
 
 .. opcode:: BUILD_LIST (count)
@@ -734,8 +732,8 @@ the more significant byte last.
 
    Imports the module ``co_names[namei]``.  TOS and TOS1 are popped and provide
    the *fromlist* and *level* arguments of :func:`__import__`.  The module
-   object is pushed onto the stack.  The current namespace is not affected:
+   object is pushed onto the stack.  The current namespace is not affected: for
-   for a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
+   a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
    modifies the namespace.
 
 
@@ -763,14 +761,14 @@ the more significant byte last.
 
 .. opcode:: JUMP_IF_TRUE_OR_POP (target)
 
-   If TOS is true, sets the bytecode counter to *target* and leaves TOS
+   If TOS is true, sets the bytecode counter to *target* and leaves TOS on the
-   on the stack.  Otherwise (TOS is false), TOS is popped.
+   stack.  Otherwise (TOS is false), TOS is popped.
 
 
 .. opcode:: JUMP_IF_FALSE_OR_POP (target)
 
-   If TOS is false, sets the bytecode counter to *target* and leaves
+   If TOS is false, sets the bytecode counter to *target* and leaves TOS on the
-   TOS on the stack.  Otherwise (TOS is true), TOS is popped.
+   stack.  Otherwise (TOS is true), TOS is popped.
 
 
 .. opcode:: JUMP_ABSOLUTE (target)
@@ -780,10 +778,10 @@ the more significant byte last.
 
 .. opcode:: FOR_ITER (delta)
 
-   TOS is an :term:`iterator`.  Call its :meth:`~iterator.__next__` method.
+   TOS is an :term:`iterator`.  Call its :meth:`~iterator.__next__` method.  If
-   If this yields a new value, push it on the stack (leaving the iterator below
+   this yields a new value, push it on the stack (leaving the iterator below
-   it).  If the iterator indicates it is exhausted TOS is popped, and the
+   it).  If the iterator indicates it is exhausted TOS is popped, and the byte
-   byte code counter is incremented by *delta*.
+   code counter is incremented by *delta*.
 
 
 .. opcode:: LOAD_GLOBAL (namei)
@@ -799,19 +797,19 @@ the more significant byte last.
 
 .. opcode:: SETUP_EXCEPT (delta)
 
-   Pushes a try block from a try-except clause onto the block stack. *delta* points
+   Pushes a try block from a try-except clause onto the block stack. *delta*
-   to the first except block.
+   points to the first except block.
 
 
 .. opcode:: SETUP_FINALLY (delta)
 
-   Pushes a try block from a try-except clause onto the block stack. *delta* points
+   Pushes a try block from a try-except clause onto the block stack. *delta*
-   to the finally block.
+   points to the finally block.
 
 .. opcode:: STORE_MAP
 
-   Store a key and value pair in a dictionary.  Pops the key and value while leaving
+   Store a key and value pair in a dictionary.  Pops the key and value while
-   the dictionary on the stack.
+   leaving the dictionary on the stack.
 
 .. opcode:: LOAD_FAST (var_num)
 
@@ -831,8 +829,8 @@ the more significant byte last.
 .. opcode:: LOAD_CLOSURE (i)
 
    Pushes a reference to the cell contained in slot *i* of the cell and free
-   variable storage.  The name of the variable is  ``co_cellvars[i]`` if *i* is
+   variable storage.  The name of the variable is ``co_cellvars[i]`` if *i* is
-   less than the length of *co_cellvars*.  Otherwise it is  ``co_freevars[i -
+   less than the length of *co_cellvars*.  Otherwise it is ``co_freevars[i -
    len(co_cellvars)]``.
 
 
@@ -872,11 +870,12 @@ the more significant byte last.
 
    Calls a function.  The low byte of *argc* indicates the number of positional
    parameters, the high byte the number of keyword parameters. On the stack, the
-   opcode finds the keyword parameters first.  For each keyword argument, the value
+   opcode finds the keyword parameters first.  For each keyword argument, the
-   is on top of the key.  Below the keyword parameters, the positional parameters
+   value is on top of the key.  Below the keyword parameters, the positional
-   are on the stack, with the right-most parameter on top.  Below the parameters,
+   parameters are on the stack, with the right-most parameter on top.  Below the
-   the function object to call is on the stack.  Pops all function arguments, and
+   parameters, the function object to call is on the stack.  Pops all function
-   the function itself off the stack, and pushes the return value.
+   arguments, and the function itself off the stack, and pushes the return
+   value.
 
 
 .. opcode:: MAKE_FUNCTION (argc)
@@ -899,8 +898,8 @@ the more significant byte last.
    Creates a new function object, sets its *__closure__* slot, and pushes it on
    the stack.  TOS is the :term:`qualified name` of the function, TOS1 is the
    code associated with the function, and TOS2 is the tuple containing cells for
-   the closure's free variables.  The function also has *argc* default parameters,
+   the closure's free variables.  The function also has *argc* default
-   which are found below the cells.
+   parameters, which are found below the cells.
 
 
 .. opcode:: BUILD_SLICE (argc)
@@ -916,36 +915,37 @@ the more significant byte last.
 
    Prefixes any opcode which has an argument too big to fit into the default two
    bytes.  *ext* holds two additional bytes which, taken together with the
-   subsequent opcode's argument, comprise a four-byte argument, *ext* being the two
+   subsequent opcode's argument, comprise a four-byte argument, *ext* being the
-   most-significant bytes.
+   two most-significant bytes.
 
 
 .. opcode:: CALL_FUNCTION_VAR (argc)
 
-   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The top element
+   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
-   on the stack contains the variable argument list, followed by keyword and
+   top element on the stack contains the variable argument list, followed by
-   positional arguments.
+   keyword and positional arguments.
 
 
 .. opcode:: CALL_FUNCTION_KW (argc)
 
-   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The top element
+   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
-   on the stack contains the keyword arguments dictionary,  followed by explicit
+   top element on the stack contains the keyword arguments dictionary, followed
-   keyword and positional arguments.
+   by explicit keyword and positional arguments.
 
 
 .. opcode:: CALL_FUNCTION_VAR_KW (argc)
 
-   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`.  The top
+   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`.  The
-   element on the stack contains the keyword arguments dictionary, followed by the
+   top element on the stack contains the keyword arguments dictionary, followed
-   variable-arguments tuple, followed by explicit keyword and positional arguments.
+   by the variable-arguments tuple, followed by explicit keyword and positional
+   arguments.
 
 
 .. opcode:: HAVE_ARGUMENT
 
-   This is not really an opcode.  It identifies the dividing line between opcodes
+   This is not really an opcode.  It identifies the dividing line between
-   which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=
+   opcodes which don't take arguments ``< HAVE_ARGUMENT`` and those which do
-   HAVE_ARGUMENT``.
+   ``>= HAVE_ARGUMENT``.
 
 .. _opcode_collections:
 
@@ -977,10 +977,10 @@ instructions:
 
 .. data:: hasfree
 
-   Sequence of bytecodes that access a free variable (note that 'free' in
+   Sequence of bytecodes that access a free variable (note that 'free' in this
-   this context refers to names in the current scope that are referenced by
+   context refers to names in the current scope that are referenced by inner
-   inner scopes or names in outer scopes that are referenced from this scope.
+   scopes or names in outer scopes that are referenced from this scope.  It does
-   It does *not* include references to global or builtin scopes).
+   *not* include references to global or builtin scopes).
 
 
 .. data:: hasname