merge with 3.4

birkenfeld · birkenfeld · commit e21a531ef10e · 2014-10-31T10:39:29.000+01:00
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
@@ -429,10 +429,11 @@ API Functions
 
    Function used to deconstruct the argument lists of "old-style" functions ---
    these are functions which use the :const:`METH_OLDARGS` parameter parsing
-   method.  This is not recommended for use in parameter parsing in new code, and
-   most code in the standard interpreter has been modified to no longer use this
-   for that purpose.  It does remain a convenient way to decompose other tuples,
-   however, and may continue to be used for that purpose.
+   method, which has been removed in Python 3.  This is not recommended for use
+   in parameter parsing in new code, and most code in the standard interpreter
+   has been modified to no longer use this for that purpose.  It does remain a
+   convenient way to decompose other tuples, however, and may continue to be
+   used for that purpose.
 
 
 .. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
@@ -867,11 +867,8 @@ reclaim the memory belonging to any objects in a reference cycle, or referenced
 from the objects in the cycle, even though there are no further references to
 the cycle itself.
 
-The cycle detector is able to detect garbage cycles and can reclaim them so long
-as there are no finalizers implemented in Python (:meth:`__del__` methods).
-When there are such finalizers, the detector exposes the cycles through the
-:mod:`gc` module (specifically, the :attr:`~gc.garbage` variable in that module).
-The :mod:`gc` module also exposes a way to run the detector (the
+The cycle detector is able to detect garbage cycles and can reclaim them.
+The :mod:`gc` module exposes a way to run the detector (the
 :func:`~gc.collect` function), as well as configuration
 interfaces and the ability to disable the detector at runtime.  The cycle
 detector is considered an optional component; though it is included by default,
diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst
@@ -148,8 +148,8 @@ A :class:`Cmd` instance has the following methods:
    Hook method executed once when :meth:`cmdloop` is about to return. This method
    is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
 
-Instances of :class:`Cmd` subclasses have some public instance variables:
 
+Instances of :class:`Cmd` subclasses have some public instance variables:
 
 .. attribute:: Cmd.prompt
 
@@ -166,6 +166,13 @@ Instances of :class:`Cmd` subclasses have some public instance variables:
    The last nonempty command prefix seen.
 
 
+.. attribute:: Cmd.cmdqueue
+
+   A list of queued input lines.  The cmdqueue list is checked in
+   :meth:`cmdloop` when new input is needed; if it is nonempty, its elements
+   will be processed in order, as if entered at the prompt.
+
+
 .. attribute:: Cmd.intro
 
    A string to issue as an intro or banner.  May be overridden by giving the
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
@@ -134,7 +134,7 @@ particular functionality, for example::
 
 Several of the ABCs are also useful as mixins that make it easier to develop
 classes supporting container APIs.  For example, to write a class supporting
-the full :class:`Set` API, it only necessary to supply the three underlying
+the full :class:`Set` API, it is only necessary to supply the three underlying
 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
 The ABC supplies the remaining methods such as :meth:`__and__` and
 :meth:`isdisjoint`::
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
@@ -908,7 +908,7 @@ customize a prototype instance:
     >>> janes_account = default_account._replace(owner='Jane')
 
 Enumerated constants can be implemented with named tuples, but it is simpler
-and more efficient to use a simple :class:`~enum.Enum` :
+and more efficient to use a simple :class:`~enum.Enum`:
 
     >>> Status = namedtuple('Status', 'open pending closed')._make(range(3))
     >>> Status.open, Status.pending, Status.closed
@@ -917,6 +917,9 @@ and more efficient to use a simple :class:`~enum.Enum` :
     >>> class Status(Enum):
     ...     open, pending, closed = range(3)
 
+
+.. seealso::
+
     * `Recipe for named tuple abstract base class with a metaclass mix-in
       <http://code.activestate.com/recipes/577629-namedtupleabc-abstract-base-class-mix-in-for-named/>`_
       by Jan Kaliszewski.  Besides providing an :term:`abstract base class` for
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
@@ -1833,7 +1833,7 @@ Utility functions
 .. function:: find_msvcrt()
    :module: ctypes.util
 
-   Windows only: return the filename of the VC runtype library used by Python,
+   Windows only: return the filename of the VC runtime library used by Python,
    and by the extension modules.  If the name of the library cannot be
    determined, ``None`` is returned.
 
@@ -2335,11 +2335,6 @@ other data types containing pointer type fields.
       and so on).  Later assignments to the :attr:`_fields_` class variable will
       raise an AttributeError.
 
-      Structure and union subclass constructors accept both positional and named
-      arguments.  Positional arguments are used to initialize the fields in the
-      same order as they appear in the :attr:`_fields_` definition, named
-      arguments are used to initialize the fields with the corresponding name.
-
       It is possible to defined sub-subclasses of structure types, they inherit
       the fields of the base class plus the :attr:`_fields_` defined in the
       sub-subclass, if any.
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
@@ -34,7 +34,8 @@ class or one of its subclasses, and not from :exc:`BaseException`.  More
 information on defining exceptions is available in the Python Tutorial under
 :ref:`tut-userexceptions`.
 
-When raising (or re-raising) an exception in an :keyword:`except` clause
+When raising (or re-raising) an exception in an :keyword:`except` or
+:keyword:`finally` clause
 :attr:`__context__` is automatically set to the last exception caught; if the
 new exception is not handled the traceback that is eventually displayed will
 include the originating exception(s) and the final exception.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
@@ -211,7 +211,7 @@ are always available.  They are listed here in alphabetical order.
    The optional arguments *flags* and *dont_inherit* control which future
    statements (see :pep:`236`) affect the compilation of *source*.  If neither
    is present (or both are zero) the code is compiled with those future
-   statements that are in effect in the code that is calling compile.  If the
+   statements that are in effect in the code that is calling :func:`compile`.  If the
    *flags* argument is given and *dont_inherit* is not (or is zero) then the
    future statements specified by the *flags* argument are used in addition to
    those that would be used anyway. If *dont_inherit* is a non-zero integer then
@@ -232,6 +232,9 @@ are always available.  They are listed here in alphabetical order.
    This function raises :exc:`SyntaxError` if the compiled source is invalid,
    and :exc:`TypeError` if the source contains null bytes.
 
+   If you want to parse Python code into its AST representation, see
+   :func:`ast.parse`.
+
    .. note::
 
       When compiling a string with multi-line code in ``'single'`` or
@@ -540,7 +543,7 @@ are always available.  They are listed here in alphabetical order.
    effect as calling :func:`str(value) <str>`.
 
    A call to ``format(value, format_spec)`` is translated to
-   ``type(value).__format__(format_spec)`` which bypasses the instance
+   ``type(value).__format__(value, format_spec)`` which bypasses the instance
    dictionary when searching for the value's :meth:`__format__` method.  A
    :exc:`TypeError` exception is raised if the method search reaches
    :mod:`object` and the *format_spec* is non-empty, or if either the
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
@@ -786,17 +786,20 @@ Classes and functions
    :func:`getargspec` or :func:`getfullargspec`.
 
    The first seven arguments are (``args``, ``varargs``, ``varkw``,
-   ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``). The
-   other five arguments are the corresponding optional formatting functions
-   that are called to turn names and values into strings. The last argument
-   is an optional function to format the sequence of arguments. For example::
+   ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``).
 
-    >>> from inspect import formatargspec, getfullargspec
-    >>> def f(a: int, b: float):
-    ...     pass
-    ...
-    >>> formatargspec(*getfullargspec(f))
-    '(a: int, b: float)'
+   The other six arguments are functions that are called to turn argument names,
+   ``*`` argument name, ``**`` argument name, default values, return annotation
+   and individual annotations into strings, respectively.
+
+   For example:
+
+   >>> from inspect import formatargspec, getfullargspec
+   >>> def f(a: int, b: float):
+   ...     pass
+   ...
+   >>> formatargspec(*getfullargspec(f))
+   '(a: int, b: float)'
 
 
 .. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])
diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst
@@ -20,6 +20,13 @@ The :mod:`pydoc` module automatically generates documentation from Python
 modules.  The documentation can be presented as pages of text on the console,
 served to a Web browser, or saved to HTML files.
 
+For modules, classes, functions and methods, the displayed documentation is
+derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object,
+and recursively of its documentable members.  If there is no docstring,
+:mod:`pydoc` tries to obtain a description from the block of comment lines just
+above the definition of the class, function or method in the source file, or at
+the top of the module (see :func:`inspect.getcomments`).
+
 The built-in function :func:`help` invokes the online help system in the
 interactive interpreter, which uses :mod:`pydoc` to generate its documentation
 as text on the console.  The same text documentation can also be viewed from
diff --git a/Doc/library/reprlib.rst b/Doc/library/reprlib.rst
@@ -156,4 +156,3 @@ for file objects could be added::
 
    aRepr = MyRepr()
    print(aRepr.repr(sys.stdin))         # prints '<stdin>'
-
diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst
@@ -127,9 +127,6 @@ The :mod:`runpy` module provides two functions:
    supplied path, and ``__spec__``, ``__cached__``, ``__loader__`` and
    ``__package__`` will all be set to :const:`None`.
 
-   ``__spec__`` will be set to :const:`None` if the supplied path is a
-   direct path to a script (as source or as precompiled bytecode).
-
    If the supplied path is a reference to a valid sys.path entry, then
    ``__spec__`` will be set appropriately for the imported ``__main__``
    module (that is, ``__spec__.name`` will always be ``__main__``).
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
@@ -482,12 +482,17 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
 
    *root_dir* and *base_dir* both default to the current directory.
 
+   If *dry_run* is true, no archive is created, but the operations that would be
+   executed are logged to *logger*.
+
    *owner* and *group* are used when creating a tar archive. By default,
    uses the current owner and group.
 
    *logger* must be an object compatible with :pep:`282`, usually an instance of
    :class:`logging.Logger`.
 
+   The *verbose* argument is currently unused.
+
    .. versionchanged:: 3.5
       Added support for the *xztar* format.
 
@@ -511,14 +516,19 @@ provided.  They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
 
 .. function:: register_archive_format(name, function, [extra_args, [description]])
 
-   Register an archiver for the format *name*. *function* is a callable that
-   will be used to invoke the archiver.
+   Register an archiver for the format *name*.
+
+   *function* is the callable that will be used to unpack archives. The callable
+   will receive the *base_name* of the file to create, followed by the
+   *base_dir* (which defaults to :data:`os.curdir`) to start archiving from.
+   Further arguments are passed as keyword arguments: *owner*, *group*,
+   *dry_run* and *logger* (as passed in :func:`make_archive`).
 
    If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be
    used as extra keywords arguments when the archiver callable is used.
 
    *description* is used by :func:`get_archive_formats` which returns the
-   list of archivers. Defaults to an empty list.
+   list of archivers.  Defaults to an empty string.
 
 
 .. function:: unregister_archive_format(name)
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -269,8 +269,8 @@ the same rule. [2]_ The constructors :func:`int`, :func:`float`, and
 :func:`complex` can be used to produce numbers of a specific type.
 
 All numeric types (except complex) support the following operations, sorted by
-ascending priority (operations in the same box have the same priority; all
-numeric operations have a higher priority than comparison operations):
+ascending priority (all numeric operations have a higher priority than
+comparison operations):
 
 +---------------------+---------------------------------+---------+--------------------+
 | Operation           | Result                          | Notes   | Full documentation |
@@ -404,8 +404,7 @@ The priorities of the binary bitwise operations are all lower than the numeric
 operations and higher than the comparisons; the unary operation ``~`` has the
 same priority as the other unary numeric operations (``+`` and ``-``).
 
-This table lists the bitwise operations sorted in ascending priority
-(operations in the same box have the same priority):
+This table lists the bitwise operations sorted in ascending priority:
 
 +------------+--------------------------------+----------+
 | Operation  | Result                         | Notes    |
@@ -444,7 +443,7 @@ Additional Methods on Integer Types
 -----------------------------------
 
 The int type implements the :class:`numbers.Integral` :term:`abstract base
-class`. In addition, it provides one more method:
+class`. In addition, it provides a few more methods:
 
 .. method:: int.bit_length()
 
@@ -820,10 +819,10 @@ both mutable and immutable. The :class:`collections.abc.Sequence` ABC is
 provided to make it easier to correctly implement these operations on
 custom sequence types.
 
-This table lists the sequence operations sorted in ascending priority
-(operations in the same box have the same priority).  In the table, *s* and *t*
-are sequences of the same type, *n*, *i*, *j* and *k* are integers and *x* is
-an arbitrary object that meets any type and value restrictions imposed by *s*.
+This table lists the sequence operations sorted in ascending priority.  In the
+table, *s* and *t* are sequences of the same type, *n*, *i*, *j* and *k* are
+integers and *x* is an arbitrary object that meets any type and value
+restrictions imposed by *s*.
 
 The ``in`` and ``not in`` operations have the same priorities as the
 comparison operations. The ``+`` (concatenation) and ``*`` (repetition)
@@ -4006,8 +4005,8 @@ before the statement body is executed and exited when the statement ends:
    The exception passed in should never be reraised explicitly - instead, this
    method should return a false value to indicate that the method completed
    successfully and does not want to suppress the raised exception. This allows
-   context management code (such as ``contextlib.nested``) to easily detect whether
-   or not an :meth:`__exit__` method has actually failed.
+   context management code to easily detect whether or not an :meth:`__exit__`
+   method has actually failed.
 
 Python defines several context managers to support easy thread synchronisation,
 prompt closure of files or other objects, and simpler manipulation of the active
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
@@ -24,6 +24,14 @@ structs and the intended conversion to/from Python values.
    or omit implicit pad bytes, use ``standard`` size and alignment instead of
    ``native`` size and alignment: see :ref:`struct-alignment` for details.
 
+Several :mod:`struct` functions (and methods of :class:`Struct`) take a *buffer*
+argument.  This refers to objects that implement the :ref:`bufferobjects` and
+provide either a readable or read-writable buffer.  The most common types used
+for that purpose are :class:`bytes` and :class:`bytearray`, but many other types
+that can be viewed as an array of bytes implement the buffer protocol, so that
+they can be read/filled without additional copying from a :class:`bytes` object.
+
+
 Functions and Exceptions
 ------------------------
 
@@ -47,7 +55,7 @@ The module defines the following exception and functions:
 
    Pack the values *v1*, *v2*, ... according to the format string *fmt* and
    write the packed bytes into the writable buffer *buffer* starting at
-   position *offset*. Note that *offset* is a required argument.
+   position *offset*.  Note that *offset* is a required argument.
 
 
 .. function:: unpack(fmt, buffer)
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
@@ -199,7 +199,7 @@ The module defines the following user-callable items:
          >>> os.path.exists(f.name)
          False
 
-The module uses two global variables that tell it how to construct a
+The module uses a global variable that tell it how to construct a
 temporary name.  They are initialized at the first call to any of the
 functions above.  The caller may change them, but this is discouraged; use
 the appropriate function arguments, instead.
diff --git a/Doc/library/tracemalloc.rst b/Doc/library/tracemalloc.rst
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
diff --git a/Doc/reference/toplevel_components.rst b/Doc/reference/toplevel_components.rst
