[Python-checkins] cpython (merge 3.4 -> default): merge 3.4 (#23561)
benjamin.peterson
python-checkins at python.org
Mon Mar 2 15:37:15 CET 2015
https://hg.python.org/cpython/rev/760f222103c7
changeset: 94823:760f222103c7
parent: 94819:84ac7e437cdc
parent: 94821:1a6f5c18e317
user: Benjamin Peterson <benjamin at python.org>
date: Mon Mar 02 09:36:48 2015 -0500
summary:
merge 3.4 (#23561)
files:
Doc/library/dis.rst | 200 ++++++++++++++++----------------
1 files changed, 100 insertions(+), 100 deletions(-)
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
--- a/Doc/library/dis.rst
+++ b/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
-input is defined in the file :file:`Include/opcode.h` and used by the compiler
-and the interpreter.
+disassembling it. The CPython bytecode which this module takes as an input is
+defined in the file :file:`Include/opcode.h` and used by the compiler and the
+interpreter.
.. impl-detail::
@@ -43,33 +43,32 @@
.. 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
-compiled code.
+:class:`Bytecode` object that provides easy access to details of the compiled
+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,
- most notably :func:`get_instructions`, as iterating over a
- :class:`Bytecode` instance yields the bytecode operations as
- :class:`Instruction` instances.
+ Analyse the bytecode corresponding to a function, generator, method, string
+ of source code, or a code object (as returned by :func:`compile`).
- If *first_line* is not None, it indicates the line number that should
- be reported for the first source line in the disassembled code.
- Otherwise, the source line information (if any) is taken directly from
- the disassembled code object.
+ This is a convenience wrapper around many of the functions listed below, most
+ notably :func:`get_instructions`, as iterating over a :class:`Bytecode`
+ instance yields the bytecode operations as :class:`Instruction` instances.
- 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.
+ If *first_line* is not None, it indicates the line number that should be
+ reported for the first source line in the disassembled code. Otherwise, the
+ 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,
- setting *current_offset* to the instruction responsible for the
- exception.
+ Construct a :class:`Bytecode` instance from the given traceback, setting
+ *current_offset* to the instruction responsible for the exception.
.. data:: codeobj
@@ -81,8 +80,8 @@
.. method:: dis()
- Return a formatted view of the bytecode operations (the same as
- printed by :func:`dis`, but returned as a multi-line string).
+ Return a formatted view of the bytecode operations (the same as printed by
+ :func:`dis.dis`, but returned as a multi-line string).
.. method:: info()
@@ -104,10 +103,9 @@
Analysis functions
------------------
-The :mod:`dis` module also defines the following analysis functions that
-convert the input directly to the desired output. They can be useful if
-only a single operation is being performed, so the intermediate analysis
-object isn't useful:
+The :mod:`dis` module also defines the following analysis functions that convert
+the input directly to the desired output. They can be useful if only a single
+operation is being performed, so the intermediate analysis object isn't useful:
.. function:: code_info(x)
@@ -196,13 +194,13 @@
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
- giving the details of each operation in the supplied code.
+ The iterator generates a series of :class:`Instruction` named tuples giving
+ the details of each operation in the supplied code.
- If *first_line* is not None, it indicates the line number that should
- be reported for the first source line in the disassembled code.
- Otherwise, the source line information (if any) is taken directly from
- the disassembled code object.
+ If *first_line* is not None, it indicates the line number that should be
+ reported for the first source line in the disassembled code. Otherwise, the
+ source line information (if any) is taken directly from the disassembled code
+ object.
.. versionadded:: 3.4
@@ -511,8 +509,8 @@
.. 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
- terminated with :opcode:`POP_TOP`.
+ from the stack and printed. In non-interactive mode, an expression statement
+ is terminated with :opcode:`POP_TOP`.
.. opcode:: BREAK_LOOP
@@ -542,9 +540,9 @@
comprehensions.
For all of the :opcode:`SET_ADD`, :opcode:`LIST_APPEND` and :opcode:`MAP_ADD`
-instructions, while the
-added value or key/value pair is popped off, the container object remains on
-the stack so that it is available for further iterations of the loop.
+instructions, while the added value or key/value pair is popped off, the
+container object remains on the stack so that it is available for further
+iterations of the loop.
.. opcode:: RETURN_VALUE
@@ -566,23 +564,23 @@
.. opcode:: IMPORT_STAR
- Loads all symbols not starting with ``'_'`` directly from the module TOS to the
- local namespace. The module is popped after loading all names. This opcode
- implements ``from module import *``.
+ Loads all symbols not starting with ``'_'`` directly from the module TOS to
+ the local namespace. The module is popped after loading all names. This
+ opcode implements ``from module import *``.
.. opcode:: POP_BLOCK
- Removes one block from the block stack. Per frame, there is a stack of blocks,
- denoting nested loops, try statements, and such.
+ Removes one block from the block stack. Per frame, there is a stack of
+ 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.
- In addition to popping extraneous values from the frame stack, the
- last three popped values are used to restore the exception state.
+ handler block, as implicitly created when entering an except handler. In
+ addition to popping extraneous values from the frame stack, the last three
+ popped values are used to restore the exception state.
.. opcode:: END_FINALLY
@@ -612,9 +610,9 @@
.. opcode:: WITH_CLEANUP
- Cleans up the stack when a :keyword:`with` statement block exits. TOS is
- the context manager's :meth:`__exit__` bound method. Below TOS are 1--3
- values indicating how/why the finally clause was entered:
+ Cleans up the stack when a :keyword:`with` statement block exits. TOS is the
+ context manager's :meth:`__exit__` bound method. Below TOS are 1--3 values
+ indicating how/why the finally clause was entered:
* SECOND = ``None``
* (SECOND, THIRD) = (``WHY_{RETURN,CONTINUE}``), retval
@@ -624,10 +622,10 @@
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
- a 'true' value, this information is "zapped" and replaced with a single
- ``WHY_SILENCED`` to prevent :opcode:`END_FINALLY` from re-raising the exception.
- (But non-local gotos will still be resumed.)
+ If the stack represents an exception, *and* the function call returns a
+ 'true' value, this information is "zapped" and replaced with a single
+ ``WHY_SILENCED`` to prevent :opcode:`END_FINALLY` from re-raising the
+ exception. (But non-local gotos will still be resumed.)
.. XXX explain the WHY stuff!
@@ -638,8 +636,8 @@
.. 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`
- or :opcode:`STORE_GLOBAL` if possible.
+ :attr:`co_names` of the code object. The compiler tries to use
+ :opcode:`STORE_FAST` or :opcode:`STORE_GLOBAL` if possible.
.. opcode:: DELETE_NAME (namei)
@@ -699,8 +697,8 @@
.. opcode:: BUILD_TUPLE (count)
- Creates a tuple consuming *count* items from the stack, and pushes the resulting
- tuple onto the stack.
+ Creates a tuple consuming *count* items from the stack, and pushes the
+ resulting tuple onto the stack.
.. opcode:: BUILD_LIST (count)
@@ -734,8 +732,8 @@
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:
- for a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
+ object is pushed onto the stack. The current namespace is not affected: for
+ a proper import statement, a subsequent :opcode:`STORE_FAST` instruction
modifies the namespace.
@@ -763,14 +761,14 @@
.. opcode:: JUMP_IF_TRUE_OR_POP (target)
- If TOS is true, sets the bytecode counter to *target* and leaves TOS
- on the stack. Otherwise (TOS is false), TOS is popped.
+ If TOS is true, sets the bytecode counter to *target* and leaves TOS on the
+ 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
- TOS on the stack. Otherwise (TOS is true), TOS is popped.
+ If TOS is false, sets the bytecode counter to *target* and leaves TOS on the
+ stack. Otherwise (TOS is true), TOS is popped.
.. opcode:: JUMP_ABSOLUTE (target)
@@ -780,10 +778,10 @@
.. opcode:: FOR_ITER (delta)
- TOS is an :term:`iterator`. Call its :meth:`~iterator.__next__` method.
- If 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
- byte code counter is incremented by *delta*.
+ TOS is an :term:`iterator`. Call its :meth:`~iterator.__next__` method. If
+ 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 byte
+ code counter is incremented by *delta*.
.. opcode:: LOAD_GLOBAL (namei)
@@ -799,19 +797,19 @@
.. opcode:: SETUP_EXCEPT (delta)
- Pushes a try block from a try-except clause onto the block stack. *delta* points
- to the first except block.
+ Pushes a try block from a try-except clause onto the block stack. *delta*
+ 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
- to the finally block.
+ Pushes a try block from a try-except clause onto the block stack. *delta*
+ points to the finally block.
.. opcode:: STORE_MAP
- Store a key and value pair in a dictionary. Pops the key and value while leaving
- the dictionary on the stack.
+ Store a key and value pair in a dictionary. Pops the key and value while
+ leaving the dictionary on the stack.
.. opcode:: LOAD_FAST (var_num)
@@ -831,8 +829,8 @@
.. 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
- less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i -
+ 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 -
len(co_cellvars)]``.
@@ -872,11 +870,12 @@
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
- is on top of the key. Below the keyword parameters, the positional parameters
- are on the stack, with the right-most parameter on top. Below the parameters,
- the function object to call is on the stack. Pops all function arguments, and
- the function itself off the stack, and pushes the return value.
+ opcode finds the keyword parameters first. For each keyword argument, the
+ value is on top of the key. Below the keyword parameters, the positional
+ parameters are on the stack, with the right-most parameter on top. Below the
+ parameters, the function object to call is on the stack. Pops all function
+ arguments, and the function itself off the stack, and pushes the return
+ value.
.. opcode:: MAKE_FUNCTION (argc)
@@ -899,8 +898,8 @@
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,
- which are found below the cells.
+ the closure's free variables. The function also has *argc* default
+ parameters, which are found below the cells.
.. opcode:: BUILD_SLICE (argc)
@@ -916,36 +915,37 @@
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
- most-significant bytes.
+ subsequent opcode's argument, comprise a four-byte argument, *ext* being the
+ two most-significant bytes.
.. opcode:: CALL_FUNCTION_VAR (argc)
- Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The top element
- on the stack contains the variable argument list, followed by keyword and
- positional arguments.
+ Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
+ top element on the stack contains the variable argument list, followed by
+ keyword and positional arguments.
.. opcode:: CALL_FUNCTION_KW (argc)
- Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The top element
- on the stack contains the keyword arguments dictionary, followed by explicit
- keyword and positional arguments.
+ Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
+ top element on the stack contains the keyword arguments dictionary, followed
+ 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
- element on the stack contains the keyword arguments dictionary, followed by the
- variable-arguments tuple, followed by explicit keyword and positional arguments.
+ Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
+ top element on the stack contains the keyword arguments dictionary, followed
+ 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
- which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>=
- HAVE_ARGUMENT``.
+ This is not really an opcode. It identifies the dividing line between
+ opcodes which don't take arguments ``< HAVE_ARGUMENT`` and those which do
+ ``>= HAVE_ARGUMENT``.
.. _opcode_collections:
@@ -977,10 +977,10 @@
.. data:: hasfree
- Sequence of bytecodes that access a free variable (note that 'free' in
- this context refers to names in the current scope that are referenced by
- inner scopes or names in outer scopes that are referenced from this scope.
- It does *not* include references to global or builtin scopes).
+ Sequence of bytecodes that access a free variable (note that 'free' in this
+ context refers to names in the current scope that are referenced by inner
+ scopes or names in outer scopes that are referenced from this scope. It does
+ *not* include references to global or builtin scopes).
.. data:: hasname
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list