Changeset 391 for python/trunk/Doc/library/dis.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/dis.rst (modified) (7 diffs)

python/trunk/Doc/library/dis.rst

@@ -1 @@
-
 :mod:`dis` --- Disassembler for Python bytecode
 ===============================================
@@ -6 +5 @@
    :synopsis: Disassembler for Python bytecode.
 
-
-The :mod:`dis` module supports the analysis of Python :term:`bytecode` by disassembling
-it.  Since there is no Python assembler, this module defines the Python assembly
-language.  The Python 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.
+**Source code:** :source:`Lib/dis.py`
+
+--------------
+
+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.
+
+.. impl-detail::
+
+   Bytecode is an implementation detail of the CPython interpreter!  No
+   guarantees are made that bytecode will not be added, removed, or changed
+   between versions of Python.  Use of this module should not be considered to
+   work across Python VMs or Python releases.
 
 Example: Given the function :func:`myfunc`::
@@ -65 +73 @@
 .. function:: disco(code[, lasti])
 
-   A synonym for disassemble.  It is more convenient to type, and kept for
-   compatibility with earlier Python releases.
+   A synonym for :func:`disassemble`.  It is more convenient to type, and kept
+   for compatibility with earlier Python releases.
+
+
+.. function:: findlinestarts(code)
+
+   This generator function uses the ``co_firstlineno`` and ``co_lnotab``
+   attributes of the code object *code* to find the offsets which are starts of
+   lines in the source code.  They are generated as ``(offset, lineno)`` pairs.
+
+
+.. function:: findlabels(code)
+
+   Detect all offsets in the code object *code* which are jump targets, and
+   return a list of these offsets.
 
 
@@ -76 +97 @@
 .. data:: opmap
 
-   Dictionary mapping bytecodes to operation names.
+   Dictionary mapping operation names to bytecodes.
 
 
@@ -464 +485 @@
 
 
-.. opcode:: LIST_APPEND ()
-
-   Calls ``list.append(TOS1, TOS)``.  Used to implement list comprehensions.
+.. opcode:: LIST_APPEND (i)
+
+   Calls ``list.append(TOS[-i], TOS)``.  Used to implement list comprehensions.
+   While the appended value is popped off, the list object remains on the
+   stack so that it is available for further iterations of the loop.
 
 
@@ -516 +539 @@
    Creates a new class object.  TOS is the methods dictionary, TOS1 the tuple of
    the names of the base classes, and TOS2 the class name.
+
+
+.. opcode:: SETUP_WITH (delta)
+
+   This opcode performs several operations before a with block starts.  First,
+   it loads :meth:`~object.__exit__` from the context manager and pushes it onto
+   the stack for later use by :opcode:`WITH_CLEANUP`.  Then,
+   :meth:`~object.__enter__` is called, and a finally block pointing to *delta*
+   is pushed.  Finally, the result of calling the enter method is pushed onto
+   the stack.  The next opcode will either ignore it (:opcode:`POP_TOP`), or
+   store it in (a) variable(s) (:opcode:`STORE_FAST`, :opcode:`STORE_NAME`, or
+   :opcode:`UNPACK_SEQUENCE`).
 
 
@@ -650 +685 @@
 
 
-.. opcode:: JUMP_IF_TRUE (delta)
-
-   If TOS is true, increment the bytecode counter by *delta*.  TOS is left on the
-   stack.
-
-
-.. opcode:: JUMP_IF_FALSE (delta)
-
-   If TOS is false, increment the bytecode counter by *delta*.  TOS is not
-   changed.
+.. opcode:: POP_JUMP_IF_TRUE (target)
+
+   If TOS is true, sets the bytecode counter to *target*.  TOS is popped.
+
+
+.. opcode:: POP_JUMP_IF_FALSE (target)
+
+   If TOS is false, sets the bytecode counter to *target*.  TOS is popped.
+
+
+.. 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.
+
+
+.. 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.