Merged revisions 85530,85534,85538,85540-85542 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r85530 | georg.brandl | 2010-10-15 17:32:05 +0200 (Fr, 15 Okt 2010) | 1 line

  Refrain from using inline suites.
........
  r85534 | georg.brandl | 2010-10-15 18:19:43 +0200 (Fr, 15 Okt 2010) | 1 line

  #9801: document how list and dict proxies created by Managers behave w.r.t. mutable items.
........
  r85538 | georg.brandl | 2010-10-15 18:35:46 +0200 (Fr, 15 Okt 2010) | 1 line

  #7303: add documentation for useful pkgutil functions and classes.
........
  r85540 | georg.brandl | 2010-10-15 18:42:37 +0200 (Fr, 15 Okt 2010) | 1 line

  #6798: fix wrong docs for the arguments to several trace events.
........
  r85541 | georg.brandl | 2010-10-15 18:53:24 +0200 (Fr, 15 Okt 2010) | 1 line

  #4968: updates to inspect.is* function docs.
........
  r85542 | georg.brandl | 2010-10-15 19:01:15 +0200 (Fr, 15 Okt 2010) | 1 line

  #7790: move table of struct_time members to the actual description of struct_time.
........

Doc/c-api/init.rst

@@ -925,13 +925,14 @@ in previous versions.
    +------------------------------+--------------------------------------+
    | :const:`PyTrace_LINE`        | Always *NULL*.                       |
    +------------------------------+--------------------------------------+
-   | :const:`PyTrace_RETURN`      | Value being returned to the caller.  |
+   | :const:`PyTrace_RETURN`      | Value being returned to the caller,  |
+   |                              | or *NULL* if caused by an exception. |
    +------------------------------+--------------------------------------+
-   | :const:`PyTrace_C_CALL`      | Name of function being called.       |
+   | :const:`PyTrace_C_CALL`      | Function object being called.        |
    +------------------------------+--------------------------------------+
-   | :const:`PyTrace_C_EXCEPTION` | Always *NULL*.                       |
+   | :const:`PyTrace_C_EXCEPTION` | Function object being called.        |
    +------------------------------+--------------------------------------+
-   | :const:`PyTrace_C_RETURN`    | Always *NULL*.                       |
+   | :const:`PyTrace_C_RETURN`    | Function object being called.        |
    +------------------------------+--------------------------------------+
 
 

Doc/library/inspect.rst

@@ -263,17 +263,20 @@ Note:
 
 .. function:: isclass(object)
 
-   Return true if the object is a class.
+   Return true if the object is a class, whether built-in or created in Python
+   code.
 
 
 .. function:: ismethod(object)
 
-   Return true if the object is a method.
+   Return true if the object is a bound method written in Python.
 
 
 .. function:: isfunction(object)
 
-   Return true if the object is a Python function or unnamed (:term:`lambda`) function.
+   Return true if the object is a Python function, which includes functions
+   created by a :term:`lambda` expression.
+
 
 .. function:: isgeneratorfunction(object)
 
@@ -281,12 +284,14 @@ Note:
 
    .. versionadded:: 2.6
 
+
 .. function:: isgenerator(object)
 
    Return true if the object is a generator.
 
    .. versionadded:: 2.6
 
+
 .. function:: istraceback(object)
 
    Return true if the object is a traceback.
@@ -304,13 +309,14 @@ Note:
 
 .. function:: isbuiltin(object)
 
-   Return true if the object is a built-in function.
+   Return true if the object is a built-in function or a bound built-in method.
 
 
 .. function:: isroutine(object)
 
    Return true if the object is a user-defined or built-in function or method.
 
+
 .. function:: isabstract(object)
 
    Return true if the object is an abstract base class.
@@ -320,8 +326,9 @@ Note:
 
 .. function:: ismethoddescriptor(object)
 
-   Return true if the object is a method descriptor, but not if :func:`ismethod`
-   or :func:`isclass` or :func:`isfunction` are true.
+   Return true if the object is a method descriptor, but not if
+   :func:`ismethod`, :func:`isclass`, :func:`isfunction` or :func:`isbuiltin`
+   are true.
 
    This is new as of Python 2.2, and, for example, is true of
    ``int.__add__``. An object passing this test has a :attr:`__get__` attribute

Doc/library/multiprocessing.rst

@@ -1286,6 +1286,24 @@ their parent process exits.  The manager classes are defined in the
 
       Create a shared ``list`` object and return a proxy for it.
 
+   .. note::
+
+      Modifications to mutable values or items in dict and list proxies will not
+      be propagated through the manager, because the proxy has no way of knowing
+      when its values or items are modified.  To modify such an item, you can
+      re-assign the modified object to the container proxy::
+
+         # create a list proxy and append a mutable object (a dictionary)
+         lproxy = manager.list()
+         lproxy.append({})
+         # now mutate the dictionary
+         d = lproxy[0]
+         d['a'] = 1
+         d['b'] = 2
+         # at this point, the changes to d are not yet synced, but by
+         # reassigning the dictionary, the proxy is notified of the change
+         lproxy[0] = d
+
 
 Namespace objects
 >>>>>>>>>>>>>>>>>

Doc/library/pkgutil.rst

@@ -3,62 +3,187 @@
 ============================================
 
 .. module:: pkgutil
-   :synopsis: Utilities to support extension of packages.
+   :synopsis: Utilities for the import system.
 
+This module provides utilities for the import system, in particular package
+support.
 
 .. versionadded:: 2.3
 
-This module provides functions to manipulate packages:
-
 
 .. function:: extend_path(path, name)
 
-   Extend the search path for the modules which comprise a package. Intended use is
-   to place the following code in a package's :file:`__init__.py`::
+   Extend the search path for the modules which comprise a package.  Intended
+   use is to place the following code in a package's :file:`__init__.py`::
 
       from pkgutil import extend_path
       __path__ = extend_path(__path__, __name__)
 
-   This will add to the package's ``__path__`` all subdirectories of directories on
-   ``sys.path`` named after the package.  This is useful if one wants to distribute
-   different parts of a single logical package as multiple directories.
+   This will add to the package's ``__path__`` all subdirectories of directories
+   on ``sys.path`` named after the package.  This is useful if one wants to
+   distribute different parts of a single logical package as multiple
+   directories.
 
-   It also looks for :file:`\*.pkg` files beginning where ``*`` matches the *name*
-   argument.  This feature is similar to :file:`\*.pth` files (see the :mod:`site`
-   module for more information), except that it doesn't special-case lines starting
-   with ``import``.  A :file:`\*.pkg` file is trusted at face value: apart from
-   checking for duplicates, all entries found in a :file:`\*.pkg` file are added to
-   the path, regardless of whether they exist on the filesystem.  (This is a
-   feature.)
+   It also looks for :file:`\*.pkg` files beginning where ``*`` matches the
+   *name* argument.  This feature is similar to :file:`\*.pth` files (see the
+   :mod:`site` module for more information), except that it doesn't special-case
+   lines starting with ``import``.  A :file:`\*.pkg` file is trusted at face
+   value: apart from checking for duplicates, all entries found in a
+   :file:`\*.pkg` file are added to the path, regardless of whether they exist
+   on the filesystem.  (This is a feature.)
 
    If the input path is not a list (as is the case for frozen packages) it is
    returned unchanged.  The input path is not modified; an extended copy is
    returned.  Items are only appended to the copy at the end.
 
-   It is assumed that ``sys.path`` is a sequence.  Items of ``sys.path`` that are
-   not (Unicode or 8-bit) strings referring to existing directories are ignored.
-   Unicode items on ``sys.path`` that cause errors when used as filenames may cause
-   this function to raise an exception (in line with :func:`os.path.isdir`
-   behavior).
+   It is assumed that :data:`sys.path` is a sequence.  Items of :data:`sys.path`
+   that are not (Unicode or 8-bit) strings referring to existing directories are
+   ignored.  Unicode items on :data:`sys.path` that cause errors when used as
+   filenames may cause this function to raise an exception (in line with
+   :func:`os.path.isdir` behavior).
+
+
+.. class:: ImpImporter(dirname=None)
+
+   :pep:`302` Importer that wraps Python's "classic" import algorithm.
+
+   If *dirname* is a string, a :pep:`302` importer is created that searches that
+   directory.  If *dirname* is ``None``, a :pep:`302` importer is created that
+   searches the current :data:`sys.path`, plus any modules that are frozen or
+   built-in.
+
+   Note that :class:`ImpImporter` does not currently support being used by
+   placement on :data:`sys.meta_path`.
+
+
+.. class:: ImpLoader(fullname, file, filename, etc)
+
+   :pep:`302` Loader that wraps Python's "classic" import algorithm.
+
+
+.. function:: find_loader(fullname)
+
+   Find a :pep:`302` "loader" object for *fullname*.
+
+   If *fullname* contains dots, path must be the containing package's
+   ``__path__``.  Returns ``None`` if the module cannot be found or imported.
+   This function uses :func:`iter_importers`, and is thus subject to the same
+   limitations regarding platform-specific special import locations such as the
+   Windows registry.
+
+
+.. function:: get_importer(path_item)
+
+   Retrieve a :pep:`302` importer for the given *path_item*.
+
+   The returned importer is cached in :data:`sys.path_importer_cache` if it was
+   newly created by a path hook.
+
+   If there is no importer, a wrapper around the basic import machinery is
+   returned.  This wrapper is never inserted into the importer cache (None is
+   inserted instead).
+
+   The cache (or part of it) can be cleared manually if a rescan of
+   :data:`sys.path_hooks` is necessary.
+
+
+.. function:: get_loader(module_or_name)
+
+   Get a :pep:`302` "loader" object for *module_or_name*.
+
+   If the module or package is accessible via the normal import mechanism, a
+   wrapper around the relevant part of that machinery is returned.  Returns
+   ``None`` if the module cannot be found or imported.  If the named module is
+   not already imported, its containing package (if any) is imported, in order
+   to establish the package ``__path__``.
+
+   This function uses :func:`iter_importers`, and is thus subject to the same
+   limitations regarding platform-specific special import locations such as the
+   Windows registry.
+
+
+.. function:: iter_importers(fullname='')
+
+   Yield :pep:`302` importers for the given module name.
+
+   If fullname contains a '.', the importers will be for the package containing
+   fullname, otherwise they will be importers for :data:`sys.meta_path`,
+   :data:`sys.path`, and Python's "classic" import machinery, in that order.  If
+   the named module is in a package, that package is imported as a side effect
+   of invoking this function.
+
+   Non-:pep:`302` mechanisms (e.g. the Windows registry) used by the standard
+   import machinery to find files in alternative locations are partially
+   supported, but are searched *after* :data:`sys.path`.  Normally, these
+   locations are searched *before* :data:`sys.path`, preventing :data:`sys.path`
+   entries from shadowing them.
+
+   For this to cause a visible difference in behaviour, there must be a module
+   or package name that is accessible via both :data:`sys.path` and one of the
+   non-:pep:`302` file system mechanisms.  In this case, the emulation will find
+   the former version, while the builtin import mechanism will find the latter.
+
+   Items of the following types can be affected by this discrepancy:
+   ``imp.C_EXTENSION``, ``imp.PY_SOURCE``, ``imp.PY_COMPILED``,
+   ``imp.PKG_DIRECTORY``.
+
+
+.. function:: iter_modules(path=None, prefix='')
+
+   Yields ``(module_loader, name, ispkg)`` for all submodules on *path*, or, if
+   path is ``None``, all top-level modules on ``sys.path``.
+
+   *path* should be either ``None`` or a list of paths to look for modules in.
+
+   *prefix* is a string to output on the front of every module name on output.
+
+
+.. function:: walk_packages(path=None, prefix='', onerror=None)
+
+   Yields ``(module_loader, name, ispkg)`` for all modules recursively on
+   *path*, or, if path is ``None``, all accessible modules.
+
+   *path* should be either ``None`` or a list of paths to look for modules in.
+
+   *prefix* is a string to output on the front of every module name on output.
+
+   Note that this function must import all *packages* (*not* all modules!) on
+   the given *path*, in order to access the ``__path__`` attribute to find
+   submodules.
+
+   *onerror* is a function which gets called with one argument (the name of the
+   package which was being imported) if any exception occurs while trying to
+   import a package.  If no *onerror* function is supplied, :exc:`ImportError`\s
+   are caught and ignored, while all other exceptions are propagated,
+   terminating the search.
+
+   Examples::
+
+      # list all modules python can access
+      walk_packages()
+
+      # list all submodules of ctypes
+      walk_packages(ctypes.__path__, ctypes.__name__ + '.')
+
 
 .. function:: get_data(package, resource)
 
    Get a resource from a package.
 
-   This is a wrapper for the :pep:`302` loader :func:`get_data` API. The package
-   argument should be the name of a package, in standard module format
-   (foo.bar). The resource argument should be in the form of a relative
-   filename, using ``/`` as the path separator. The parent directory name
+   This is a wrapper for the :pep:`302` loader :func:`get_data` API.  The
+   *package* argument should be the name of a package, in standard module format
+   (``foo.bar``).  The *resource* argument should be in the form of a relative
+   filename, using ``/`` as the path separator.  The parent directory name
    ``..`` is not allowed, and nor is a rooted name (starting with a ``/``).
 
-   The function returns a binary string that is the contents of the
-   specified resource.
+   The function returns a binary string that is the contents of the specified
+   resource.
 
    For packages located in the filesystem, which have already been imported,
    this is the rough equivalent of::
 
-       d = os.path.dirname(sys.modules[package].__file__)
-       data = open(os.path.join(d, resource), 'rb').read()
+      d = os.path.dirname(sys.modules[package].__file__)
+      data = open(os.path.join(d, resource), 'rb').read()
 
    If the package cannot be located or loaded, or it uses a :pep:`302` loader
-   which does not support :func:`get_data`, then None is returned.
+   which does not support :func:`get_data`, then ``None`` is returned.

Doc/library/sys.rst

@@ -874,8 +874,9 @@ always available.
 
    ``'return'``
       A function (or other code block) is about to return.  The local trace
-      function is called; *arg* is the value that will be returned.  The trace
-      function's return value is ignored.
+      function is called; *arg* is the value that will be returned, or ``None``
+      if the event is caused by an exception being raised.  The trace function's
+      return value is ignored.
 
    ``'exception'``
       An exception has occurred.  The local trace function is called; *arg* is a
@@ -887,10 +888,10 @@ always available.
       a built-in.  *arg* is the C function object.
 
    ``'c_return'``
-      A C function has returned. *arg* is ``None``.
+      A C function has returned. *arg* is the C function object.
 
    ``'c_exception'``
-      A C function has raised an exception.  *arg* is ``None``.
+      A C function has raised an exception.  *arg* is the C function object.
 
    Note that as an exception is propagated down the chain of callers, an
    ``'exception'`` event is generated at each level.

Doc/library/time.rst

@@ -17,21 +17,23 @@ semantics of these functions varies among platforms.
 
 An explanation of some terminology and conventions is in order.
 
-  .. index:: single: epoch
+.. index:: single: epoch
 
 * The :dfn:`epoch` is the point where the time starts.  On January 1st of that
   year, at 0 hours, the "time since the epoch" is zero.  For Unix, the epoch is
   1970.  To find out what the epoch is, look at ``gmtime(0)``.
 
-  .. index:: single: Year 2038
+.. index:: single: Year 2038
 
 * The functions in this module do not handle dates and times before the epoch or
   far in the future.  The cut-off point in the future is determined by the C
   library; for Unix, it is typically in 2038.
 
-  .. index::
-     single: Year 2000
-     single: Y2K
+.. index::
+   single: Year 2000
+   single: Y2K
+
+.. _time-y2kissues:
 
 * **Year 2000 (Y2K) issues**:  Python depends on the platform's C library, which
   generally doesn't have year 2000 issues, since all dates and times are
@@ -48,16 +50,16 @@ An explanation of some terminology and conventions is in order.
   Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python
   1.5.1 and 1.5.2a1, would add 1900 to year values below 1900.
 
-  .. index::
-     single: UTC
-     single: Coordinated Universal Time
-     single: Greenwich Mean Time
+.. index::
+   single: UTC
+   single: Coordinated Universal Time
+   single: Greenwich Mean Time
 
 * UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
   GMT).  The acronym UTC is not a mistake but a compromise between English and
   French.
 
-  .. index:: single: Daylight Saving Time
+.. index:: single: Daylight Saving Time
 
 * DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
   hour during part of the year.  DST rules are magic (determined by local law) and
@@ -82,38 +84,7 @@ An explanation of some terminology and conventions is in order.
   values of :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer
   attribute names for individual fields.
 
-  +-------+-------------------+---------------------------------+
-  | Index | Attribute         | Values                          |
-  +=======+===================+=================================+
-  | 0     | :attr:`tm_year`   | (for example, 1993)             |
-  +-------+-------------------+---------------------------------+
-  | 1     | :attr:`tm_mon`    | range [1, 12]                   |
-  +-------+-------------------+---------------------------------+
-  | 2     | :attr:`tm_mday`   | range [1, 31]                   |
-  +-------+-------------------+---------------------------------+
-  | 3     | :attr:`tm_hour`   | range [0, 23]                   |
-  +-------+-------------------+---------------------------------+
-  | 4     | :attr:`tm_min`    | range [0, 59]                   |
-  +-------+-------------------+---------------------------------+
-  | 5     | :attr:`tm_sec`    | range [0, 61]; see **(1)** in   |
-  |       |                   | :func:`strftime` description    |
-  +-------+-------------------+---------------------------------+
-  | 6     | :attr:`tm_wday`   | range [0, 6], Monday is 0       |
-  +-------+-------------------+---------------------------------+
-  | 7     | :attr:`tm_yday`   | range [1, 366]                  |
-  +-------+-------------------+---------------------------------+
-  | 8     | :attr:`tm_isdst`  | 0, 1 or -1; see below           |
-  +-------+-------------------+---------------------------------+
-
-  Note that unlike the C structure, the month value is a range of [1, 12],
-  not [0, 11].
-  A year value will be handled as described under "Year 2000 (Y2K) issues" above.
-  A ``-1`` argument as the daylight savings flag, passed to :func:`mktime` will
-  usually result in the correct daylight savings state to be filled in.
-
-  When a tuple with an incorrect length is passed to a function expecting a
-  :class:`struct_time`, or having elements of the wrong type, a :exc:`TypeError`
-  is raised.
+  See :class:`struct_time` for a description of these objects.
 
   .. versionchanged:: 2.2
      The time value sequence was changed from a tuple to a :class:`struct_time`, with
@@ -419,13 +390,48 @@ The module defines the following functions and data items:
    documented as supported.
 
 
-.. data:: struct_time
+.. class:: struct_time
 
    The type of the time value sequence returned by :func:`gmtime`,
-   :func:`localtime`, and :func:`strptime`.
+   :func:`localtime`, and :func:`strptime`.  It is an object with a :term:`named
+   tuple` interface: values can be accessed by index and by attribute name.  The
+   following values are present:
+
+   +-------+-------------------+---------------------------------+
+   | Index | Attribute         | Values                          |
+   +=======+===================+=================================+
+   | 0     | :attr:`tm_year`   | (for example, 1993)             |
+   +-------+-------------------+---------------------------------+
+   | 1     | :attr:`tm_mon`    | range [1, 12]                   |
+   +-------+-------------------+---------------------------------+
+   | 2     | :attr:`tm_mday`   | range [1, 31]                   |
+   +-------+-------------------+---------------------------------+
+   | 3     | :attr:`tm_hour`   | range [0, 23]                   |
+   +-------+-------------------+---------------------------------+
+   | 4     | :attr:`tm_min`    | range [0, 59]                   |
+   +-------+-------------------+---------------------------------+
+   | 5     | :attr:`tm_sec`    | range [0, 61]; see **(1)** in   |
+   |       |                   | :func:`strftime` description    |
+   +-------+-------------------+---------------------------------+
+   | 6     | :attr:`tm_wday`   | range [0, 6], Monday is 0       |
+   +-------+-------------------+---------------------------------+
+   | 7     | :attr:`tm_yday`   | range [1, 366]                  |
+   +-------+-------------------+---------------------------------+
+   | 8     | :attr:`tm_isdst`  | 0, 1 or -1; see below           |
+   +-------+-------------------+---------------------------------+
 
    .. versionadded:: 2.2
 
+   Note that unlike the C structure, the month value is a range of [1, 12], not
+   [0, 11].  A year value will be handled as described under :ref:`Year 2000
+   (Y2K) issues <time-y2kissues>` above.  A ``-1`` argument as the daylight
+   savings flag, passed to :func:`mktime` will usually result in the correct
+   daylight savings state to be filled in.
+
+   When a tuple with an incorrect length is passed to a function expecting a
+   :class:`struct_time`, or having elements of the wrong type, a
+   :exc:`TypeError` is raised.
+
 
 .. function:: time()
 

Doc/tutorial/controlflow.rst

@@ -429,7 +429,8 @@ function like this::
    def cheeseshop(kind, *arguments, **keywords):
        print "-- Do you have any", kind, "?"
        print "-- I'm sorry, we're all out of", kind
-       for arg in arguments: print arg
+       for arg in arguments:
+           print arg
        print "-" * 40
        keys = sorted(keywords.keys())
        for kw in keys: