@@ -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)
 
@@ -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
 
@@ -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)
 
@@ -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*
 
@@ -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
 
@@ -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:
 
 
@@ -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`.
+
@@ -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.
 
@@ -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).
 
 
@@ -11,9 +11,9 @@
 
 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``).