diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/dis.rst | 30 | ||||
| -rw-r--r-- | Doc/library/doctest.rst | 20 | ||||
| -rw-r--r-- | Doc/library/imp.rst | 96 | ||||
| -rw-r--r-- | Doc/library/re.rst | 10 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 2 | ||||
| -rw-r--r-- | Doc/library/sqlite3.rst | 6 | ||||
| -rw-r--r-- | Doc/library/struct.rst | 5 | ||||
| -rw-r--r-- | Doc/reference/datamodel.rst | 16 | ||||
| -rw-r--r-- | Doc/reference/expressions.rst | 12 | ||||
| -rw-r--r-- | Doc/tools/sphinx-build.py | 4 |
10 files changed, 116 insertions, 85 deletions
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 5f28473..7ce864d 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -474,10 +474,29 @@ Miscellaneous opcodes. 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:: WITH_CLEANUP () + + Cleans up the stack when a :keyword:`with` statement block exits. TOS is the + context manager's :meth:`__exit__` bound method. Below that are 1--3 values + indicating how/why the finally clause was entered: + + * SECOND = None + * (SECOND, THIRD) = (WHY_{RETURN,CONTINUE}), retval + * SECOND = WHY_\*; no retval below it + * (SECOND, THIRD, FOURTH) = exc_info() + + In the last case, ``TOS(SECOND, THIRD, FOURTH)`` is called, otherwise + ``TOS(None, None, None)``. + + In addition, if the stack represents an exception, *and* the function call + returns a 'true' value, this information is "zapped", to prevent ``END_FINALLY`` + from re-raising the exception. (But non-local gotos should still be resumed.) + + All of the following opcodes expect arguments. An argument is two bytes, with the more significant byte last. - .. opcode:: STORE_NAME (namei) Implements ``name = TOS``. *namei* is the index of *name* in the attribute @@ -722,11 +741,10 @@ the more significant byte last. .. opcode:: MAKE_CLOSURE (argc) - Creates a new function object, sets its *__closure__* slot, and pushes it on the - stack. TOS is the code associated with the function. If the code object has N - free variables, the next N items on the stack are the cells for these variables. - The function also has *argc* default parameters, where are found before the - cells. + Creates a new function object, sets its *__closure__* slot, and pushes it on + the stack. TOS is the code associated with the function, TOS1 the tuple + containing cells for the closure's free variables. The function also has + *argc* default parameters, which are found below the cells. .. opcode:: BUILD_SLICE (argc) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 23f96e4..4f4f511 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -69,11 +69,6 @@ Here's a complete but small example module:: OverflowError: n too large """ - -.. % allow LaTeX to break here. - -:: - import math if not n >= 0: raise ValueError("n must be >= 0") @@ -88,12 +83,10 @@ Here's a complete but small example module:: factor += 1 return result - def _test(): - import doctest - doctest.testmod() if __name__ == "__main__": - _test() + import doctest + doctest.testmod() If you run :file:`example.py` directly from the command line, :mod:`doctest` works its magic:: @@ -131,12 +124,10 @@ And so on, eventually ending with:: ... OverflowError: n too large ok - 1 items had no tests: - __main__._test 2 items passed all tests: 1 tests in __main__ 8 tests in __main__.factorial - 9 tests in 3 items. + 9 tests in 2 items. 9 passed and 0 failed. Test passed. $ @@ -156,13 +147,10 @@ Simple Usage: Checking Examples in Docstrings The simplest way to start using doctest (but not necessarily the way you'll continue to do it) is to end each module :mod:`M` with:: - def _test(): + if __name__ == "__main__": import doctest doctest.testmod() - if __name__ == "__main__": - _test() - :mod:`doctest` then examines docstrings in module :mod:`M`. Running the module as a script causes the examples in the docstrings to get diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst index f80bea3..7943604 100644 --- a/Doc/library/imp.rst +++ b/Doc/library/imp.rst @@ -22,63 +22,73 @@ This module provides an interface to the mechanisms used to implement the .. function:: get_suffixes() - Return a list of triples, each describing a particular type of module. Each - triple has the form ``(suffix, mode, type)``, where *suffix* is a string to be - appended to the module name to form the filename to search for, *mode* is the - mode string to pass to the built-in :func:`open` function to open the file (this - can be ``'r'`` for text files or ``'rb'`` for binary files), and *type* is the - file type, which has one of the values :const:`PY_SOURCE`, :const:`PY_COMPILED`, - or :const:`C_EXTENSION`, described below. + Return a list of 3-element tuples, each describing a particular type of + module. Each triple has the form ``(suffix, mode, type)``, where *suffix* is + a string to be appended to the module name to form the filename to search + for, *mode* is the mode string to pass to the built-in :func:`open` function + to open the file (this can be ``'r'`` for text files or ``'rb'`` for binary + files), and *type* is the file type, which has one of the values + :const:`PY_SOURCE`, :const:`PY_COMPILED`, or :const:`C_EXTENSION`, described + below. .. function:: find_module(name[, path]) - Try to find the module *name* on the search path *path*. If *path* is a list of - directory names, each directory is searched for files with any of the suffixes - returned by :func:`get_suffixes` above. Invalid names in the list are silently - ignored (but all list items must be strings). If *path* is omitted or ``None``, - the list of directory names given by ``sys.path`` is searched, but first it - searches a few special places: it tries to find a built-in module with the given - name (:const:`C_BUILTIN`), then a frozen module (:const:`PY_FROZEN`), and on - some systems some other places are looked in as well (on the Mac, it looks for a - resource (:const:`PY_RESOURCE`); on Windows, it looks in the registry which may - point to a specific file). - - If search is successful, the return value is a triple ``(file, pathname, - description)`` where *file* is an open file object positioned at the beginning, - *pathname* is the pathname of the file found, and *description* is a triple as + Try to find the module *name* on the search path *path*. If *path* is a list + of directory names, each directory is searched for files with any of the + suffixes returned by :func:`get_suffixes` above. Invalid names in the list + are silently ignored (but all list items must be strings). If *path* is + omitted or ``None``, the list of directory names given by ``sys.path`` is + searched, but first it searches a few special places: it tries to find a + built-in module with the given name (:const:`C_BUILTIN`), then a frozen + module (:const:`PY_FROZEN`), and on some systems some other places are looked + in as well (on the Mac, it looks for a resource (:const:`PY_RESOURCE`); on + Windows, it looks in the registry which may point to a specific file). + + If search is successful, the return value is a 3-element tuple ``(file, + pathname, description)``: + + *file* is an open file object positioned at the beginning, *pathname* is the + pathname of the file found, and *description* is a 3-element tuple as contained in the list returned by :func:`get_suffixes` describing the kind of - module found. If the module does not live in a file, the returned *file* is - ``None``, *filename* is the empty string, and the *description* tuple contains - empty strings for its suffix and mode; the module type is as indicate in - parentheses above. If the search is unsuccessful, :exc:`ImportError` is raised. - Other exceptions indicate problems with the arguments or environment. - - This function does not handle hierarchical module names (names containing dots). - In order to find *P*.*M*, that is, submodule *M* of package *P*, use + module found. + + If the module does not live in a file, the returned *file* is ``None``, + *pathname* is the empty string, and the *description* tuple contains empty + strings for its suffix and mode; the module type is indicated as given in + parentheses above. If the search is unsuccessful, :exc:`ImportError` is + raised. Other exceptions indicate problems with the arguments or + environment. + + If the module is a package, *file* is ``None``, *pathname* is the package + path and the last item in the *description* tuple is :const:`PKG_DIRECTORY`. + + This function does not handle hierarchical module names (names containing + dots). In order to find *P*.*M*, that is, submodule *M* of package *P*, use :func:`find_module` and :func:`load_module` to find and load package *P*, and then use :func:`find_module` with the *path* argument set to ``P.__path__``. When *P* itself has a dotted name, apply this recipe recursively. -.. function:: load_module(name, file, filename, description) +.. function:: load_module(name, file, pathname, description) Load a module that was previously found by :func:`find_module` (or by an otherwise conducted search yielding compatible results). This function does more than importing the module: if the module was already imported, it will - reload the module! The *name* argument indicates the full module name (including - the package name, if this is a submodule of a package). The *file* argument is - an open file, and *filename* is the corresponding file name; these can be - ``None`` and ``''``, respectively, when the module is not being loaded from a - file. The *description* argument is a tuple, as would be returned by - :func:`get_suffixes`, describing what kind of module must be loaded. - - If the load is successful, the return value is the module object; otherwise, an - exception (usually :exc:`ImportError`) is raised. - - **Important:** the caller is responsible for closing the *file* argument, if it - was not ``None``, even when an exception is raised. This is best done using a - :keyword:`try` ... :keyword:`finally` statement. + reload the module! The *name* argument indicates the full + module name (including the package name, if this is a submodule of a + package). The *file* argument is an open file, and *pathname* is the + corresponding file name; these can be ``None`` and ``''``, respectively, when + the module is a package or not being loaded from a file. The *description* + argument is a tuple, as would be returned by :func:`get_suffixes`, describing + what kind of module must be loaded. + + If the load is successful, the return value is the module object; otherwise, + an exception (usually :exc:`ImportError`) is raised. + + **Important:** the caller is responsible for closing the *file* argument, if + it was not ``None``, even when an exception is raised. This is best done + using a :keyword:`try` ... :keyword:`finally` statement. .. function:: new_module(name) diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 027ff16..d5abcdd 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -393,12 +393,12 @@ Matching vs Searching Python offers two different primitive operations based on regular expressions: -match and search. If you are accustomed to Perl's semantics, the search -operation is what you're looking for. See the :func:`search` function and -corresponding method of compiled regular expression objects. +**match** checks for a match only at the beginning of the string, while +**search** checks for a match anywhere in the string (this is what Perl does +by default). -Note that match may differ from search using a regular expression beginning with -``'^'``: ``'^'`` matches only at the start of the string, or in +Note that match may differ from search even when using a regular expression +beginning with ``'^'``: ``'^'`` matches only at the start of the string, or in :const:`MULTILINE` mode also immediately following a newline. The "match" operation succeeds only if the pattern matches at the start of the string regardless of mode, or at the starting position given by the optional *pos* diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 68a32fe..46774a3 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -197,7 +197,7 @@ The module :mod:`socket` exports the following constants and functions: :func:`socket` function. *canonname* is a string representing the canonical name of the *host*. It can be a numeric IPv4/v6 address when :const:`AI_CANONNAME` is specified for a numeric *host*. *sockaddr* is a tuple describing a socket - address, as described above. See the source for the :mod:`httplib` and other + address, as described above. See the source for :mod:`socket` and other library modules for a typical usage of the function. .. versionadded:: 2.2 diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 707092b..bee32e6 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -440,9 +440,6 @@ A :class:`Cursor` instance has the following attributes and methods: attribute, the database engine's own support for the determination of "rows affected"/"rows selected" is quirky. - For ``SELECT`` statements, :attr:`rowcount` is always None because we cannot - determine the number of rows a query produced until all rows were fetched. - For ``DELETE`` statements, SQLite reports :attr:`rowcount` as 0 if you make a ``DELETE FROM table`` without any condition. @@ -453,6 +450,9 @@ A :class:`Cursor` instance has the following attributes and methods: case no executeXX() has been performed on the cursor or the rowcount of the last operation is not determinable by the interface". + This includes ``SELECT`` statements because we cannot determine the number of + rows a query produced until all rows were fetched. + .. _sqlite3-types: diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index 2f27d13..9cf4eb2 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -290,3 +290,8 @@ Compiled Struct objects support the following methods and attributes: The format string used to construct this Struct object. +.. attribute:: Struct.size + + The calculated size of the struct (and hence of the string) corresponding + to :attr:`format`. + diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 2f6013e..baa6eaa 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1544,11 +1544,11 @@ Super Binding ``A.__dict__['m'].__get__(obj, A)``. For instance bindings, the precedence of descriptor invocation depends on the -which descriptor methods are defined. Data descriptors define both -:meth:`__get__` and :meth:`__set__`. Non-data descriptors have just the +which descriptor methods are defined. Normally, data descriptors define both +:meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the :meth:`__get__` method. Data descriptors always override a redefinition in an instance dictionary. In contrast, non-data descriptors can be overridden by -instances. +instances. [#]_ Python methods (including :func:`staticmethod` and :func:`classmethod`) are implemented as non-data descriptors. Accordingly, instances can redefine and @@ -1817,6 +1817,9 @@ objects. Immutable sequences methods should at most only define .. deprecated:: 2.0 Support slice objects as parameters to the :meth:`__getitem__` method. + (However, built-in types in CPython currently still implement + :meth:`__getslice__`. Therefore, you have to override it in derived + classes when implementing slicing.) Called to implement evaluation of ``self[i:j]``. The returned object should be of the same type as *self*. Note that missing *i* or *j* in the slice @@ -2112,6 +2115,13 @@ For more information on context managers, see :ref:`typecontextmanager`. .. [#] This, and other statements, are only roughly true for instances of new-style classes. +.. [#] A descriptor can define any combination of :meth:`__get__`, + :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`, + then accessing the attribute even on an instance will return the descriptor + object itself. If the descriptor defines :meth:`__set__` and/or + :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a + non-data descriptor. + .. [#] For operands of the same type, it is assumed that if the non-reflected method (such as :meth:`__add__`) fails the operation is not supported, which is why the reflected method is not called. diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 476c82d..ef71a80 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -741,7 +741,7 @@ less tightly than unary operators on its right. The syntax is: Thus, in an unparenthesized sequence of power and unary operators, the operators are evaluated from right to left (this does not constrain the evaluation order -for the operands). +for the operands): ``-1**2`` results in ``-1``. The power operator has the same semantics as the built-in :func:`pow` function, when called with two arguments: it yields its left argument raised to the power @@ -959,12 +959,12 @@ Comparisons can be chained arbitrarily, e.g., ``x < y <= z`` is equivalent to ``x < y and y <= z``, except that ``y`` is evaluated only once (but in both cases ``z`` is not evaluated at all when ``x < y`` is found to be false). -Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *opa*, *opb*, ..., -*opy* are comparison operators, then *a opa b opb c* ...*y opy z* is equivalent -to *a opa b* :keyword:`and` *b opb c* :keyword:`and` ... *y opy z*, except that -each expression is evaluated at most once. +Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *op1*, *op2*, ..., +*opN* are comparison operators, then ``a op1 b op2 c ... y opN z`` is equivalent +to ``a op1 b and b op2 c and ... y opN z``, except that each expression is +evaluated at most once. -Note that *a opa b opb c* doesn't imply any kind of comparison between *a* and +Note that ``a op1 b op2 c`` doesn't imply any kind of comparison between *a* and *c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not pretty). diff --git a/Doc/tools/sphinx-build.py b/Doc/tools/sphinx-build.py index e19b10a..8f952be 100644 --- a/Doc/tools/sphinx-build.py +++ b/Doc/tools/sphinx-build.py @@ -11,9 +11,9 @@ import sys if __name__ == '__main__': - if sys.version_info[:3] < (2, 5, 0): + if sys.version_info[:3] < (2, 5, 1): print >>sys.stderr, """\ -Error: Sphinx needs to be executed with Python 2.5 or newer +Error: Sphinx needs to be executed with Python 2.5.1 or newer (If you run this from the Makefile, you can set the PYTHON variable to the path of an alternative interpreter executable, e.g., ``make html PYTHON=python2.5``). |