diff options
| -rw-r--r-- | Doc/c-api/init.rst | 9 | ||||
| -rw-r--r-- | Doc/library/ftplib.rst | 40 | ||||
| -rw-r--r-- | Doc/library/inspect.rst | 27 | ||||
| -rw-r--r-- | Doc/library/json.rst | 11 | ||||
| -rw-r--r-- | Doc/library/multiprocessing.rst | 18 | ||||
| -rw-r--r-- | Doc/library/pkgutil.rst | 174 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 29 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 9 | ||||
| -rw-r--r-- | Doc/library/time.rst | 93 | ||||
| -rw-r--r-- | Doc/tutorial/controlflow.rst | 6 | ||||
| -rw-r--r-- | Lib/inspect.py | 40 | ||||
| -rw-r--r-- | Lib/json/__init__.py | 24 | ||||
| -rw-r--r-- | Lib/json/decoder.py | 14 | ||||
| -rw-r--r-- | Lib/test/test_minidom.py | 7 | ||||
| -rw-r--r-- | Lib/xml/dom/minidom.py | 9 | ||||
| -rw-r--r-- | Misc/NEWS | 5 |
16 files changed, 347 insertions, 168 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index ae5d028..a176e5a 100644 --- a/Doc/c-api/init.rst +++ b/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. | +------------------------------+--------------------------------------+ diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index 75a8fb1..5545505 100644 --- a/Doc/library/ftplib.rst +++ b/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[, ...]) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index cc88acf..7bb3e71 100644 --- a/Doc/library/inspect.rst +++ b/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 diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 3b203a2..a26001d 100644 --- a/Doc/library/json.rst +++ b/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) diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 9fa2d81..264d432 100644 --- a/Doc/library/multiprocessing.rst +++ b/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 >>>>>>>>>>>>>>>>> diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst index 48d53e3..f9f5e86 100644 --- a/Doc/library/pkgutil.rst +++ b/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. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 7641e63..5693ed5 100644 --- a/Doc/library/stdtypes.rst +++ b/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: diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index bf3fd47..3af5b5f 100644 --- a/Doc/library/sys.rst +++ b/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. diff --git a/Doc/library/time.rst b/Doc/library/time.rst index ceae8fa..b91aa53 100644 --- a/Doc/library/time.rst +++ b/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() diff --git a/Doc/tutorial/controlflow.rst b/Doc/tutorial/controlflow.rst index bd88ad6..e33a596 100644 --- a/Doc/tutorial/controlflow.rst +++ b/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:: diff --git a/Lib/inspect.py b/Lib/inspect.py index 5c7cfb4..ffe05b7 100644 --- a/Lib/inspect.py +++ b/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: diff --git a/Lib/json/__init__.py b/Lib/json/__init__.py index 5d8cb19..d71c2ce 100644 --- a/Lib/json/__init__.py +++ b/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 diff --git a/Lib/json/decoder.py b/Lib/json/decoder.py index 3e7405b..d606cbd 100644 --- a/Lib/json/decoder.py +++ b/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 diff --git a/Lib/test/test_minidom.py b/Lib/test/test_minidom.py index 461ac65..c58d17d 100644 --- a/Lib/test/test_minidom.py +++ b/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) diff --git a/Lib/xml/dom/minidom.py b/Lib/xml/dom/minidom.py index f4f4400..0e62e73 100644 --- a/Lib/xml/dom/minidom.py +++ b/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("&", "&").replace("<", "<") - data = data.replace("\"", """).replace(">", ">") - writer.write(data) + if data: + data = data.replace("&", "&").replace("<", "<"). \ + replace("\"", """).replace(">", ">") + 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), @@ -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. |