Merged revisions 85530,85532-85534,85538-85543,85546-85548 via svnmerge from

svn+ssh://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.
........
  r85532 | georg.brandl | 2010-10-15 18:03:02 +0200 (Fr, 15 Okt 2010) | 1 line

  #7771: reference to documentation of dictview methods and operations.
........
  r85533 | georg.brandl | 2010-10-15 18:07:41 +0200 (Fr, 15 Okt 2010) | 1 line

  #9683: remove broken dead code dealing with nested arguments removed from Py3k, and update the docs and docstrings accordingly.
........
  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.
........
  r85539 | georg.brandl | 2010-10-15 18:42:14 +0200 (Fr, 15 Okt 2010) | 1 line

  Fix issue references.
........
  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.
........
  r85543 | georg.brandl | 2010-10-15 19:03:02 +0200 (Fr, 15 Okt 2010) | 1 line

  #4785: document strict argument of JSONDecoder, plus add object_pairs_hook in the docstrings.
........
  r85546 | georg.brandl | 2010-10-15 19:58:45 +0200 (Fr, 15 Okt 2010) | 1 line

  #5762: fix handling of empty namespace in minidom, which would result in AttributeError on toxml().
........
  r85547 | georg.brandl | 2010-10-15 20:00:35 +0200 (Fr, 15 Okt 2010) | 1 line

  #6098: Refrain from claiming DOM level 3 conformance in minidom.
........
  r85548 | georg.brandl | 2010-10-15 21:46:19 +0200 (Fr, 15 Okt 2010) | 1 line

  #10072: assume a bit less knowledge of the FTP protocol in the ftplib docs.
........

Doc/c-api/init.rst

@@ -908,13 +908,14 @@ Python-level trace functions 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/ftplib.rst

@@ -54,18 +54,21 @@ The module defines the following items:
 
 .. exception:: error_temp
 
-   Exception raised when an error code in the range 400--499 is received.
+   Exception raised when an error code signifying a temporary error (response
+   codes in the range 400--499) is received.
 
 
 .. exception:: error_perm
 
-   Exception raised when an error code in the range 500--599 is received.
+   Exception raised when an error code signifying a permanent error (response
+   codes in the range 500--599) is received.
 
 
 .. exception:: error_proto
 
-   Exception raised when a reply is received from the server that does not begin
-   with a digit in the range 1--5.
+   Exception raised when a reply is received from the server that does not fit
+   the response specifications of the File Transfer Protocol, i.e. begin with a
+   digit in the range 1--5.
 
 
 .. data:: all_errors
@@ -158,9 +161,9 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
 .. method:: FTP.voidcmd(cmd)
 
-   Send a simple command string to the server and handle the response. Return
-   nothing if a response code in the range 200--299 is received. Raise an exception
-   otherwise.
+   Send a simple command string to the server and handle the response.  Return
+   nothing if a response code corresponding to success (codes in the range
+   200--299) is received.  Raise :exc:`error_reply` otherwise.
 
 
 .. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)
@@ -177,12 +180,15 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
 .. method:: FTP.retrlines(cmd, callback=None)
 
-   Retrieve a file or directory listing in ASCII transfer mode.  *cmd*
-   should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
-   command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
-   ``'LIST'``).  The *callback* function is called for each line with a
-   string argument containing the line with the trailing CRLF stripped.
-   The default *callback* prints the line to ``sys.stdout``.
+   Retrieve a file or directory listing in ASCII transfer mode.  *cmd* should be
+   an appropriate ``RETR`` command (see :meth:`retrbinary`) or a command such as
+   ``LIST``, ``NLST`` or ``MLSD`` (usually just the string ``'LIST'``).
+   ``LIST`` retrieves a list of files and information about those files.
+   ``NLST`` retrieves a list of file names.  On some servers, ``MLSD`` retrieves
+   a machine readable list of files and information about those files.  The
+   *callback* function is called for each line with a string argument containing
+   the line with the trailing CRLF stripped.  The default *callback* prints the
+   line to ``sys.stdout``.
 
 
 .. method:: FTP.set_pasv(boolean)
@@ -240,10 +246,10 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
 .. method:: FTP.nlst(argument[, ...])
 
-   Return a list of files as returned by the ``NLST`` command.  The optional
-   *argument* is a directory to list (default is the current server directory).
-   Multiple arguments can be used to pass non-standard options to the ``NLST``
-   command.
+   Return a list of file names as returned by the ``NLST`` command.  The
+   optional *argument* is a directory to list (default is the current server
+   directory).  Multiple arguments can be used to pass non-standard options to
+   the ``NLST`` command.
 
 
 .. method:: FTP.dir(argument[, ...])

Doc/library/inspect.rst

@@ -204,18 +204,19 @@ attributes:
 
 .. 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)
@@ -245,13 +246,14 @@ attributes:
 
 .. 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.
@@ -259,8 +261,9 @@ attributes:
 
 .. 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, for example, is true of ``int.__add__``.  An object passing this test
    has a :attr:`__get__` attribute but not a :attr:`__set__` attribute, but
@@ -422,19 +425,19 @@ Classes and functions
 
    Get information about arguments passed into a particular frame.  A
    :term:`named tuple` ``ArgInfo(args, varargs, keywords, locals)`` is
-   returned. *args* is a list of the argument names (it may contain nested
-   lists). *varargs* and *varkw* are the names of the ``*`` and ``**`` arguments
-   or ``None``. *locals* is the locals dictionary of the given frame.
+   returned. *args* is a list of the argument names.  *varargs* and *varkw* are
+   the names of the ``*`` and ``**`` arguments or ``None``.  *locals* is the
+   locals dictionary of the given frame.
 
 
-.. function:: formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])
+.. function:: formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue])
 
    Format a pretty argument spec from the four values returned by
    :func:`getargspec`.  The format\* arguments are the corresponding optional
    formatting functions that are called to turn names and values into strings.
 
 
-.. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue, join])
+.. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])
 
    Format a pretty argument spec from the four values returned by
    :func:`getargvalues`.  The format\* arguments are the corresponding optional

Doc/library/json.rst

@@ -149,7 +149,7 @@ Basic Usage
 
    To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
    :meth:`default` method to serialize additional types), specify it with the
-   *cls* kwarg.
+   *cls* kwarg; otherwise :class:`JSONEncoder` is used.
 
 
 .. function:: dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, **kw)
@@ -195,8 +195,8 @@ Basic Usage
    are encountered.
 
    To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
-   kwarg.  Additional keyword arguments will be passed to the constructor of the
-   class.
+   kwarg; otherwise :class:`JSONDecoder` is used.  Additional keyword arguments
+   will be passed to the constructor of the class.
 
 
 .. function:: loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)
@@ -275,6 +275,11 @@ Encoders and decoders
    ``'false'``.  This can be used to raise an exception if invalid JSON numbers
    are encountered.
 
+   If *strict* is ``False`` (``True`` is the default), then control characters
+   will be allowed inside strings.  Control characters in this context are
+   those with character codes in the 0-31 range, including ``'\t'`` (tab),
+   ``'\n'``, ``'\r'`` and ``'\0'``.
+
 
    .. method:: decode(s)
 

Doc/library/multiprocessing.rst

@@ -1288,6 +1288,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,40 +3,166 @@
 ============================================
 
 .. module:: pkgutil
-   :synopsis: Utilities to support extension of packages.
+   :synopsis: Utilities for the import system.
 
-
-This module provides functions to manipulate packages:
+This module provides utilities for the import system, in particular package
+support.
 
 
 .. 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 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 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)
 
@@ -48,14 +174,14 @@ This module provides functions to manipulate packages:
    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/stdtypes.rst

@@ -2038,28 +2038,11 @@ support membership tests:
 
 
 Keys views are set-like since their entries are unique and hashable.  If all
-values are hashable, so that (key, value) pairs are unique and hashable, then
-the items view is also set-like.  (Values views are not treated as set-like
-since the entries are generally not unique.)  Then these set operations are
-available ("other" refers either to another view or a set):
-
-.. describe:: dictview & other
-
-   Return the intersection of the dictview and the other object as a new set.
-
-.. describe:: dictview | other
-
-   Return the union of the dictview and the other object as a new set.
-
-.. describe:: dictview - other
-
-   Return the difference between the dictview and the other object (all elements
-   in *dictview* that aren't in *other*) as a new set.
-
-.. describe:: dictview ^ other
-
-   Return the symmetric difference (all elements either in *dictview* or
-   *other*, but not in both) of the dictview and the other object as a new set.
+values are hashable, so that ``(key, value)`` pairs are unique and hashable,
+then the items view is also set-like.  (Values views are not treated as set-like
+since the entries are generally not unique.)  For set-like views, all of the
+operations defined for the abstract base class :class:`collections.Set` are
+available (for example, ``==``, ``<``, or ``^``).
 
 
 An example of dictionary view usage::
@@ -2090,6 +2073,8 @@ An example of dictionary view usage::
    >>> # set operations
    >>> keys & {'eggs', 'bacon', 'salad'}
    {'bacon'}
+   >>> keys ^ {'sausage', 'juice'}
+   {'juice', 'eggs', 'bacon', 'spam'}
 
 
 .. _typememoryview:

Doc/library/sys.rst

@@ -746,8 +746,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
@@ -759,10 +760,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

@@ -16,21 +16,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
@@ -47,16 +49,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
@@ -81,37 +83,7 @@ An explanation of some terminology and conventions is in order.
   :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.
 
 * Use the following functions to convert between time representations:
 
@@ -388,10 +360,45 @@ 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           |
+   +-------+-------------------+---------------------------------+
+
+   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

@@ -458,10 +458,12 @@ 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: print(kw, ":", keywords[kw])
+       for kw in keys:
+           print(kw, ":", keywords[kw])
 
 It could be called like this::
 

Lib/inspect.py

@@ -737,9 +737,9 @@ def getargs(co):
     """Get information about the arguments accepted by a code object.
 
     Three things are returned: (args, varargs, varkw), where
-    'args' is the list of argument names, possibly containing nested
-    lists. Keyword-only arguments are appended. 'varargs' and 'varkw'
-    are the names of the * and ** arguments or None."""
+    'args' is the list of argument names. Keyword-only arguments are
+    appended. 'varargs' and 'varkw' are the names of the * and **
+    arguments or None."""
     args, varargs, kwonlyargs, varkw = _getfullargs(co)
     return Arguments(args + kwonlyargs, varargs, varkw)
 
@@ -747,9 +747,8 @@ def _getfullargs(co):
     """Get information about the arguments accepted by a code object.
 
     Four things are returned: (args, varargs, kwonlyargs, varkw), where
-    'args' and 'kwonlyargs' are lists of argument names (with 'args'
-    possibly containing nested lists), and 'varargs' and 'varkw' are the
-    names of the * and ** arguments or None."""
+    'args' and 'kwonlyargs' are lists of argument names, and 'varargs'
+    and 'varkw' are the names of the * and ** arguments or None."""
 
     if not iscode(co):
         raise TypeError('{!r} is not a code object'.format(co))
@@ -778,7 +777,7 @@ def getargspec(func):
     """Get the names and default values of a function's arguments.
 
     A tuple of four things is returned: (args, varargs, varkw, defaults).
-    'args' is a list of the argument names (it may contain nested lists).
+    'args' is a list of the argument names.
     'args' will include keyword-only argument names.
     'varargs' and 'varkw' are the names of the * and ** arguments or None.
     'defaults' is an n-tuple of the default values of the last n arguments.
@@ -803,7 +802,7 @@ def getfullargspec(func):
 
     A tuple of seven things is returned:
     (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults annotations).
-    'args' is a list of the argument names (it may contain nested lists).
+    'args' is a list of the argument names.
     'varargs' and 'varkw' are the names of the * and ** arguments or None.
     'defaults' is an n-tuple of the default values of the last n arguments.
     'kwonlyargs' is a list of keyword-only argument names.
@@ -827,25 +826,12 @@ def getargvalues(frame):
     """Get information about arguments passed into a particular frame.
 
     A tuple of four things is returned: (args, varargs, varkw, locals).
-    'args' is a list of the argument names (it may contain nested lists).
+    'args' is a list of the argument names.
     'varargs' and 'varkw' are the names of the * and ** arguments or None.
     'locals' is the locals dictionary of the given frame."""
     args, varargs, varkw = getargs(frame.f_code)
     return ArgInfo(args, varargs, varkw, frame.f_locals)
 
-def joinseq(seq):
-    if len(seq) == 1:
-        return '(' + seq[0] + ',)'
-    else:
-        return '(' + ', '.join(seq) + ')'
-
-def strseq(object, convert, join=joinseq):
-    """Recursively walk a sequence, stringifying each element."""
-    if type(object) in (list, tuple):
-        return join(map(lambda o, c=convert, j=join: strseq(o, c, j), object))
-    else:
-        return convert(object)
-
 def formatannotation(annotation, base_module=None):
     if isinstance(annotation, type):
         if annotation.__module__ in ('builtins', base_module):
@@ -866,8 +852,7 @@ def formatargspec(args, varargs=None, varkw=None, defaults=None,
                   formatvarkw=lambda name: '**' + name,
                   formatvalue=lambda value: '=' + repr(value),
                   formatreturns=lambda text: ' -> ' + text,
-                  formatannotation=formatannotation,
-                  join=joinseq):
+                  formatannotation=formatannotation):
     """Format an argument spec from the values returned by getargspec
     or getfullargspec.
 
@@ -885,7 +870,7 @@ def formatargspec(args, varargs=None, varkw=None, defaults=None,
     if defaults:
         firstdefault = len(args) - len(defaults)
     for i, arg in enumerate(args):
-        spec = strseq(arg, formatargandannotation, join)
+        spec = formatargandannotation(arg)
         if defaults and i >= firstdefault:
             spec = spec + formatvalue(defaults[i - firstdefault])
         specs.append(spec)
@@ -911,8 +896,7 @@ def formatargvalues(args, varargs, varkw, locals,
                     formatarg=str,
                     formatvarargs=lambda name: '*' + name,
                     formatvarkw=lambda name: '**' + name,
-                    formatvalue=lambda value: '=' + repr(value),
-                    join=joinseq):
+                    formatvalue=lambda value: '=' + repr(value)):
     """Format an argument spec from the 4 values returned by getargvalues.
 
     The first four arguments are (args, varargs, varkw, locals).  The
@@ -924,7 +908,7 @@ def formatargvalues(args, varargs, varkw, locals,
         return formatarg(name) + formatvalue(locals[name])
     specs = []
     for i in range(len(args)):
-        specs.append(strseq(args[i], convert, join))
+        specs.append(convert(args[i]))
     if varargs:
         specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
     if varkw:

Lib/json/__init__.py

@@ -155,7 +155,7 @@ def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
 
     To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
     ``.default()`` method to serialize additional types), specify it with
-    the ``cls`` kwarg.
+    the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
 
     """
     # cached encoder
@@ -213,7 +213,7 @@ def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
 
     To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
     ``.default()`` method to serialize additional types), specify it with
-    the ``cls`` kwarg.
+    the ``cls`` kwarg; otherwise ``JSONEncoder`` is used.
 
     """
     # cached encoder
@@ -244,8 +244,16 @@ def load(fp, cls=None, object_hook=None, parse_float=None,
     ``object_hook`` will be used instead of the ``dict``. This feature
     can be used to implement custom decoders (e.g. JSON-RPC class hinting).
 
+    ``object_pairs_hook`` is an optional function that will be called with the
+    result of any object literal decoded with an ordered list of pairs.  The
+    return value of ``object_pairs_hook`` will be used instead of the ``dict``.
+    This feature can be used to implement custom decoders that rely on the
+    order that the key and value pairs are decoded (for example,
+    collections.OrderedDict will remember the order of insertion). If
+    ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority.
+
     To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
-    kwarg.
+    kwarg; otherwise ``JSONDecoder`` is used.
 
     """
     return loads(fp.read(),
@@ -264,6 +272,14 @@ def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
     ``object_hook`` will be used instead of the ``dict``. This feature
     can be used to implement custom decoders (e.g. JSON-RPC class hinting).
 
+    ``object_pairs_hook`` is an optional function that will be called with the
+    result of any object literal decoded with an ordered list of pairs.  The
+    return value of ``object_pairs_hook`` will be used instead of the ``dict``.
+    This feature can be used to implement custom decoders that rely on the
+    order that the key and value pairs are decoded (for example,
+    collections.OrderedDict will remember the order of insertion). If
+    ``object_hook`` is also defined, the ``object_pairs_hook`` takes priority.
+
     ``parse_float``, if specified, will be called with the string
     of every JSON float to be decoded. By default this is equivalent to
     float(num_str). This can be used to use another datatype or parser
@@ -280,7 +296,7 @@ def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
     are encountered.
 
     To use a custom ``JSONDecoder`` subclass, specify it with the ``cls``
-    kwarg.
+    kwarg; otherwise ``JSONDecoder`` is used.
 
     """
     if (cls is None and object_hook is None and

Lib/json/decoder.py

@@ -289,6 +289,15 @@ class JSONDecoder(object):
         place of the given ``dict``.  This can be used to provide custom
         deserializations (e.g. to support JSON-RPC class hinting).
 
+        ``object_pairs_hook``, if specified will be called with the result of
+        every JSON object decoded with an ordered list of pairs.  The return
+        value of ``object_pairs_hook`` will be used instead of the ``dict``.
+        This feature can be used to implement custom decoders that rely on the
+        order that the key and value pairs are decoded (for example,
+        collections.OrderedDict will remember the order of insertion). If
+        ``object_hook`` is also defined, the ``object_pairs_hook`` takes
+        priority.
+
         ``parse_float``, if specified, will be called with the string
         of every JSON float to be decoded. By default this is equivalent to
         float(num_str). This can be used to use another datatype or parser
@@ -304,6 +313,11 @@ class JSONDecoder(object):
         This can be used to raise an exception if invalid JSON numbers
         are encountered.
 
+        If ``strict`` is false (true is the default), then control
+        characters will be allowed inside strings.  Control characters in
+        this context are those with character codes in the 0-31 range,
+        including ``'\\t'`` (tab), ``'\\n'``, ``'\\r'`` and ``'\\0'``.
+
         """
         self.object_hook = object_hook
         self.parse_float = parse_float or float

Lib/test/test_minidom.py

@@ -1479,6 +1479,13 @@ class MinidomTest(unittest.TestCase):
         doc.appendChild(doc.createComment("foo--bar"))
         self.assertRaises(ValueError, doc.toxml)
 
+    def testEmptyXMLNSValue(self):
+        doc = parseString("<element xmlns=''>\n"
+                          "<foo/>\n</element>")
+        doc2 = parseString(doc.toxml())
+        self.confirm(doc2.namespaceURI == xml.dom.EMPTY_NAMESPACE)
+
+
 def test_main():
     run_unittest(MinidomTest)
 

Lib/xml/dom/minidom.py

@@ -293,9 +293,10 @@ def _in_document(node):
 
 def _write_data(writer, data):
     "Writes datachars to writer."
-    data = data.replace("&", "&amp;").replace("<", "&lt;")
-    data = data.replace("\"", "&quot;").replace(">", "&gt;")
-    writer.write(data)
+    if data:
+        data = data.replace("&", "&amp;").replace("<", "&lt;"). \
+                    replace("\"", "&quot;").replace(">", "&gt;")
+        writer.write(data)
 
 def _get_elements_by_tagName_helper(parent, name, rc):
     for node in parent.childNodes:
@@ -1358,11 +1359,9 @@ class Notation(Identified, Childless, Node):
 class DOMImplementation(DOMImplementationLS):
     _features = [("core", "1.0"),
                  ("core", "2.0"),
-                 ("core", "3.0"),
                  ("core", None),
                  ("xml", "1.0"),
                  ("xml", "2.0"),
-                 ("xml", "3.0"),
                  ("xml", None),
                  ("ls-load", "3.0"),
                  ("ls-load", None),

Misc/NEWS

@@ -18,6 +18,11 @@ Library
 
 - Issue #10459: Update CJK character names to Unicode 5.1.
 
+- Issue #6098: Don't claim DOM level 3 conformance in minidom.
+
+- Issue #5762: Fix AttributeError raised by ``xml.dom.minidom`` when an empty
+  XML namespace attribute is encountered.
+
 - Issue #1710703: Write structures for an empty ZIP archive when a ZipFile is
   created in modes 'a' or 'w' and then closed without adding any files. Raise
   BadZipfile (rather than IOError) when opening small non-ZIP files.