diff options
Diffstat (limited to 'Doc/library')
| -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 |
7 files changed, 95 insertions, 74 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`. + |