diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/unicode.rst | 8 | ||||
| -rw-r--r-- | Doc/glossary.rst | 3 | ||||
| -rw-r--r-- | Doc/library/dis.rst | 142 | ||||
| -rw-r--r-- | Doc/library/http.server.rst | 30 | ||||
| -rw-r--r-- | Doc/tools/sphinxext/pyspecific.py | 11 | ||||
| -rw-r--r-- | Doc/tutorial/controlflow.rst | 5 | ||||
| -rw-r--r-- | Doc/using/cmdline.rst | 2 |
7 files changed, 107 insertions, 94 deletions
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index e8e0db8..32a7ca9 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -328,10 +328,10 @@ APIs: Coerce an encoded object *obj* to an Unicode object and return a reference with incremented refcount. - String and other char buffer compatible objects are decoded according to the - given encoding and using the error handling defined by errors. Both can be - *NULL* to have the interface use the default values (see the next section for - details). + :class:`bytes`, :class:`bytearray` and other char buffer compatible objects + are decoded according to the given encoding and using the error handling + defined by errors. Both can be *NULL* to have the interface use the default + values (see the next section for details). All other objects, including Unicode objects, cause a :exc:`TypeError` to be set. diff --git a/Doc/glossary.rst b/Doc/glossary.rst index f1474cf..cc7b28e 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -63,6 +63,9 @@ Glossary "intermediate language" is said to run on a :term:`virtual machine` that executes the machine code corresponding to each bytecode. + A list of bytecode instructions can be found in the documentation for + :ref:`the dis module <bytecodes>`. + class A template for creating user-defined objects. Class definitions normally contain method definitions which operate on instances of the diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index e97743c..49b5673 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -17,6 +17,7 @@ and the interpreter. 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`:: def myfunc(alist): @@ -37,23 +38,27 @@ The :mod:`dis` module defines the following functions and constants: .. function:: dis(x=None) - Disassemble the *x* object. *x* can denote either a module, a - class, a method, a function, or a code object. For a module, it disassembles - all functions. For a class, it disassembles all methods. For a single code - sequence, it prints one line per bytecode instruction. If no object is - provided, it disassembles the last traceback. + Disassemble the *x* object. *x* can denote either a module, a + class, a method, a function, a code object, a string of source code or a + byte sequence of raw bytecode. For a module, it disassembles all + functions. For a class, it disassembles all methods. For a code object + or sequence of raw bytecode, it prints one line per bytecode instruction. + Strings are first compiled to code objects with the :func:`compile` + built-in function before being disassembled. If no object is provided, + this function disassembles the last traceback. .. function:: distb(tb=None) - Disassembles the top-of-stack function of a traceback, using the last traceback - if none was passed. The instruction causing the exception is indicated. + Disassemble the top-of-stack function of a traceback, using the last + traceback if none was passed. The instruction causing the exception is + indicated. .. function:: disassemble(code, lasti=-1) disco(code, lasti=-1) - Disassembles a code object, indicating the last instruction if *lasti* was + Disassemble a code object, indicating the last instruction if *lasti* was provided. The output is divided in the following columns: #. the line number, for the first instruction of each line @@ -139,225 +144,233 @@ Python Bytecode Instructions The Python compiler currently generates the following bytecode instructions. -.. opcode:: STOP_CODE () +**General instructions** + +.. opcode:: STOP_CODE Indicates end-of-code to the compiler, not used by the interpreter. -.. opcode:: NOP () +.. opcode:: NOP Do nothing code. Used as a placeholder by the bytecode optimizer. -.. opcode:: POP_TOP () +.. opcode:: POP_TOP Removes the top-of-stack (TOS) item. -.. opcode:: ROT_TWO () +.. opcode:: ROT_TWO Swaps the two top-most stack items. -.. opcode:: ROT_THREE () +.. opcode:: ROT_THREE Lifts second and third stack item one position up, moves top down to position three. -.. opcode:: ROT_FOUR () +.. opcode:: ROT_FOUR Lifts second, third and forth stack item one position up, moves top down to position four. -.. opcode:: DUP_TOP () +.. opcode:: DUP_TOP Duplicates the reference on top of the stack. -Unary Operations take the top of the stack, apply the operation, and push the -result back on the stack. +**Unary operations** -.. opcode:: UNARY_POSITIVE () +Unary operations take the top of the stack, apply the operation, and push the +result back on the stack. + +.. opcode:: UNARY_POSITIVE Implements ``TOS = +TOS``. -.. opcode:: UNARY_NEGATIVE () +.. opcode:: UNARY_NEGATIVE Implements ``TOS = -TOS``. -.. opcode:: UNARY_NOT () +.. opcode:: UNARY_NOT Implements ``TOS = not TOS``. -.. opcode:: UNARY_INVERT () +.. opcode:: UNARY_INVERT Implements ``TOS = ~TOS``. -.. opcode:: GET_ITER () +.. opcode:: GET_ITER Implements ``TOS = iter(TOS)``. + +**Binary operations** + Binary operations remove the top of the stack (TOS) and the second top-most stack item (TOS1) from the stack. They perform the operation, and put the result back on the stack. - -.. opcode:: BINARY_POWER () +.. opcode:: BINARY_POWER Implements ``TOS = TOS1 ** TOS``. -.. opcode:: BINARY_MULTIPLY () +.. opcode:: BINARY_MULTIPLY Implements ``TOS = TOS1 * TOS``. -.. opcode:: BINARY_FLOOR_DIVIDE () +.. opcode:: BINARY_FLOOR_DIVIDE Implements ``TOS = TOS1 // TOS``. -.. opcode:: BINARY_TRUE_DIVIDE () +.. opcode:: BINARY_TRUE_DIVIDE Implements ``TOS = TOS1 / TOS``. -.. opcode:: BINARY_MODULO () +.. opcode:: BINARY_MODULO Implements ``TOS = TOS1 % TOS``. -.. opcode:: BINARY_ADD () +.. opcode:: BINARY_ADD Implements ``TOS = TOS1 + TOS``. -.. opcode:: BINARY_SUBTRACT () +.. opcode:: BINARY_SUBTRACT Implements ``TOS = TOS1 - TOS``. -.. opcode:: BINARY_SUBSCR () +.. opcode:: BINARY_SUBSCR Implements ``TOS = TOS1[TOS]``. -.. opcode:: BINARY_LSHIFT () +.. opcode:: BINARY_LSHIFT Implements ``TOS = TOS1 << TOS``. -.. opcode:: BINARY_RSHIFT () +.. opcode:: BINARY_RSHIFT Implements ``TOS = TOS1 >> TOS``. -.. opcode:: BINARY_AND () +.. opcode:: BINARY_AND Implements ``TOS = TOS1 & TOS``. -.. opcode:: BINARY_XOR () +.. opcode:: BINARY_XOR Implements ``TOS = TOS1 ^ TOS``. -.. opcode:: BINARY_OR () +.. opcode:: BINARY_OR Implements ``TOS = TOS1 | TOS``. + +**In-place operations** + In-place operations are like binary operations, in that they remove TOS and TOS1, and push the result back on the stack, but the operation is done in-place when TOS1 supports it, and the resulting TOS may be (but does not have to be) the original TOS1. - -.. opcode:: INPLACE_POWER () +.. opcode:: INPLACE_POWER Implements in-place ``TOS = TOS1 ** TOS``. -.. opcode:: INPLACE_MULTIPLY () +.. opcode:: INPLACE_MULTIPLY Implements in-place ``TOS = TOS1 * TOS``. -.. opcode:: INPLACE_FLOOR_DIVIDE () +.. opcode:: INPLACE_FLOOR_DIVIDE Implements in-place ``TOS = TOS1 // TOS``. -.. opcode:: INPLACE_TRUE_DIVIDE () +.. opcode:: INPLACE_TRUE_DIVIDE Implements in-place ``TOS = TOS1 / TOS``. -.. opcode:: INPLACE_MODULO () +.. opcode:: INPLACE_MODULO Implements in-place ``TOS = TOS1 % TOS``. -.. opcode:: INPLACE_ADD () +.. opcode:: INPLACE_ADD Implements in-place ``TOS = TOS1 + TOS``. -.. opcode:: INPLACE_SUBTRACT () +.. opcode:: INPLACE_SUBTRACT Implements in-place ``TOS = TOS1 - TOS``. -.. opcode:: INPLACE_LSHIFT () +.. opcode:: INPLACE_LSHIFT Implements in-place ``TOS = TOS1 << TOS``. -.. opcode:: INPLACE_RSHIFT () +.. opcode:: INPLACE_RSHIFT Implements in-place ``TOS = TOS1 >> TOS``. -.. opcode:: INPLACE_AND () +.. opcode:: INPLACE_AND Implements in-place ``TOS = TOS1 & TOS``. -.. opcode:: INPLACE_XOR () +.. opcode:: INPLACE_XOR Implements in-place ``TOS = TOS1 ^ TOS``. -.. opcode:: INPLACE_OR () +.. opcode:: INPLACE_OR Implements in-place ``TOS = TOS1 | TOS``. -.. opcode:: STORE_SUBSCR () +.. opcode:: STORE_SUBSCR Implements ``TOS1[TOS] = TOS2``. -.. opcode:: DELETE_SUBSCR () +.. opcode:: DELETE_SUBSCR Implements ``del TOS1[TOS]``. -Miscellaneous opcodes. +**Miscellaneous opcodes** -.. opcode:: PRINT_EXPR () +.. 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 ``POP_STACK``. -.. opcode:: BREAK_LOOP () +.. opcode:: BREAK_LOOP Terminates a loop due to a :keyword:`break` statement. @@ -383,36 +396,35 @@ Miscellaneous opcodes. Calls ``dict.setitem(TOS1[-i], TOS, TOS1)``. Used to implement dict comprehensions. - For all of the SET_ADD, LIST_APPEND and 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. -.. opcode:: RETURN_VALUE () +.. opcode:: RETURN_VALUE Returns with TOS to the caller of the function. -.. opcode:: YIELD_VALUE () +.. opcode:: YIELD_VALUE Pops ``TOS`` and yields it from a :term:`generator`. -.. opcode:: IMPORT_STAR () +.. 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 *``. -.. opcode:: POP_BLOCK () +.. 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. -.. opcode:: POP_EXCEPT () +.. 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. @@ -420,20 +432,20 @@ the stack so that it is available for further iterations of the loop. last three popped values are used to restore the exception state. -.. opcode:: END_FINALLY () +.. opcode:: END_FINALLY Terminates a :keyword:`finally` clause. The interpreter recalls whether the exception has to be re-raised, or whether the function returns, and continues with the outer-next block. -.. opcode:: LOAD_BUILD_CLASS () +.. opcode:: LOAD_BUILD_CLASS Pushes :func:`builtins.__build_class__` onto the stack. It is later called by ``CALL_FUNCTION`` to construct a class. -.. opcode:: WITH_CLEANUP () +.. 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 @@ -643,7 +655,7 @@ the more significant byte last. Pushes a try block from a try-except clause onto the block stack. *delta* points to the finally block. -.. opcode:: STORE_MAP () +.. opcode:: STORE_MAP Store a key and value pair in a dictionary. Pops the key and value while leaving the dictionary on the stack. @@ -759,7 +771,7 @@ the more significant byte last. variable-arguments tuple, followed by explicit keyword and positional arguments. -.. opcode:: HAVE_ARGUMENT () +.. 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 ``>= diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 5fdb543..1ca1620 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -284,30 +284,30 @@ of which this module provides three different variants: For example usage, see the implementation of the :func:`test` function invocation in the :mod:`http.server` module. -The :class:`SimpleHTTPRequestHandler` class can be invoked the following manner -with the :mod:`http.server` to create a very basic webserver serving files -relative to the current directory.:: - import http.server - import socketserver +The :class:`SimpleHTTPRequestHandler` class can be used in the following +manner in order to create a very basic webserver serving files relative to +the current directory. :: - PORT = 8000 + import http.server + import socketserver - Handler = http.server.SimpleHTTPRequestHandler + PORT = 8000 - httpd = socketserver.TCPServer(("", PORT), Handler) + Handler = http.server.SimpleHTTPRequestHandler - print("serving at port", PORT) - httpd.serve_forever() + httpd = socketserver.TCPServer(("", PORT), Handler) -:mod:`http.server` can also be invoked directly using the ``-m`` switch of -interpreter a with ``port number`` argument which uses -:class:`SimpleHTTPRequestHandler` as the default request Handler. Similar to -the previous example, even this serves files relative to the current -directory.:: + print("serving at port", PORT) + httpd.serve_forever() + +:mod:`http.server` can also be invoked directly using the :option:`-m` +switch of the interpreter a with ``port number`` argument. Similar to +the previous example, this serves files relative to the current directory. :: python -m http.server 8000 + .. class:: CGIHTTPRequestHandler(request, client_address, server) This class is used to serve either files or output of CGI scripts from the diff --git a/Doc/tools/sphinxext/pyspecific.py b/Doc/tools/sphinxext/pyspecific.py index 143003f..7111c06 100644 --- a/Doc/tools/sphinxext/pyspecific.py +++ b/Doc/tools/sphinxext/pyspecific.py @@ -5,7 +5,7 @@ Sphinx extension with Python doc-specific markup. - :copyright: 2008, 2009 by Georg Brandl. + :copyright: 2008, 2009, 2010 by Georg Brandl. :license: Python license. """ @@ -149,7 +149,7 @@ import suspicious import re from sphinx import addnodes -opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)\s*\((.*)\)') +opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?') def parse_opcode_signature(env, sig, signode): """Transform an opcode signature into RST nodes.""" @@ -158,9 +158,10 @@ def parse_opcode_signature(env, sig, signode): raise ValueError opname, arglist = m.groups() signode += addnodes.desc_name(opname, opname) - paramlist = addnodes.desc_parameterlist() - signode += paramlist - paramlist += addnodes.desc_parameter(arglist, arglist) + if arglist is not None: + paramlist = addnodes.desc_parameterlist() + signode += paramlist + paramlist += addnodes.desc_parameter(arglist, arglist) return opname.strip() diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index 8a2d645..bd88ad6 100644 --- a/Doc/tutorial/controlflow.rst +++ b/Doc/tutorial/controlflow.rst @@ -87,7 +87,6 @@ The :func:`range` Function If you do need to iterate over a sequence of numbers, the built-in function :func:`range` comes in handy. It generates arithmetic progressions:: - >>> for i in range(5): ... print(i) ... @@ -97,9 +96,7 @@ If you do need to iterate over a sequence of numbers, the built-in function 3 4 - - -The given end point is never part of the generated list; ``range(10)`` generates +The given end point is never part of the generated sequence; ``range(10)`` generates 10 values, the legal indices for items of a sequence of length 10. It is possible to let the range start at another number, or to specify a different increment (even negative; sometimes this is called the 'step'):: diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 0978770..3fe0c7a 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -58,7 +58,7 @@ source. .. cmdoption:: -c <command> - Execute the Python code in *command*. *command* can be one ore more + Execute the Python code in *command*. *command* can be one or more statements separated by newlines, with significant leading whitespace as in normal module code. |