mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-01-22 08:25:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
........
This commit is contained in:
Georg Brandl 2010-11-26 08:42:45 +00:00
parent aba9796c5e
commit c524cff3d3
16 changed files with 347 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Doc/c-api/init.rst
View File

@ -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. |
+------------------------------+--------------------------------------+

40
Doc/library/ftplib.rst
View File

@ -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[, ...])

27
Doc/library/inspect.rst
View File

@ -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

11
Doc/library/json.rst
View File

@ -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)

18
Doc/library/multiprocessing.rst
View File

@ -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
>>>>>>>>>>>>>>>>>

174
Doc/library/pkgutil.rst
View File

@ -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.

29
Doc/library/stdtypes.rst
View File

@ -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:

9
Doc/library/sys.rst
View File

@ -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.

93
Doc/library/time.rst
View File

@ -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()

6
Doc/tutorial/controlflow.rst
View File

@ -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::

40
Lib/inspect.py
View File

@ -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:

24
Lib/json/__init__.py
View File

@ -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

14
Lib/json/decoder.py
View File

@ -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

7
Lib/test/test_minidom.py
View File

@ -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)

9
Lib/xml/dom/minidom.py
View File

@ -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),

5
Misc/NEWS
View File

@ -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.