Merge from 3.2 . Replace the term members with correct and appropriate terminology. Initial patch by Adam Woodbeck.

77 files changed, 5318 insertions, 640 deletions

diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst
index 369e9cd01e..e7e7504c42 100644
--- a/Doc/library/_thread.rst
+++ b/Doc/library/_thread.rst
@@ -35,6 +35,9 @@ It defines the following constants and functions:
 
    Raised on thread-specific errors.
 
+   .. versionchanged:: 3.3
+      This is now a synonym of the built-in :exc:`RuntimeError`.
+
 
 .. data:: LockType
 
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
index 1048b24c08..2776dbf9b6 100644
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -18,7 +18,7 @@ regarding a type hierarchy for numbers based on ABCs.)
 
 The :mod:`collections` module has some concrete classes that derive from
 ABCs; these can, of course, be further derived. In addition the
-:mod:`collections` module has some ABCs that can be used to test whether
+:mod:`collections.abc` submodule has some ABCs that can be used to test whether
 a class or instance provides a particular interface, for example, is it
 hashable or a mapping.
 
@@ -55,6 +55,9 @@ This module provides the following class:
         assert issubclass(tuple, MyABC)
         assert isinstance((), MyABC)
 
+      .. versionchanged:: 3.3
+         Returns the registered subclass, to allow usage as a class decorator.
+
    You can also override this method in an abstract base class:
 
    .. method:: __subclasshook__(subclass)
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 61e1786b01..a2bceae15c 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -362,16 +362,16 @@ formatter_class
 ^^^^^^^^^^^^^^^
 
 :class:`ArgumentParser` objects allow the help formatting to be customized by
-specifying an alternate formatting class.  Currently, there are three such
+specifying an alternate formatting class.  Currently, there are four such
 classes:
 
 .. class:: RawDescriptionHelpFormatter
            RawTextHelpFormatter
            ArgumentDefaultsHelpFormatter
+           MetavarTypeHelpFormatter
 
-The first two allow more control over how textual descriptions are displayed,
-while the last automatically adds information about argument default values.
-
+:class:`RawDescriptionHelpFormatter` and :class:`RawTextHelpFormatter` give
+more control over how textual descriptions are displayed.
 By default, :class:`ArgumentParser` objects line-wrap the description_ and
 epilog_ texts in command-line help messages::
 
@@ -395,7 +395,7 @@ epilog_ texts in command-line help messages::
    likewise for this epilog whose whitespace will be cleaned up and whose words
    will be wrapped across a couple lines
 
-Passing :class:`~argparse.RawDescriptionHelpFormatter` as ``formatter_class=``
+Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=``
 indicates that description_ and epilog_ are already correctly formatted and
 should not be line-wrapped::
 
@@ -421,11 +421,11 @@ should not be line-wrapped::
    optional arguments:
     -h, --help  show this help message and exit
 
-:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text
+:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
 including argument descriptions.
 
-The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`,
-will add information about the default value of each of the arguments::
+:class:`ArgumentDefaultsHelpFormatter` automatically adds information about
+default values to each of the argument help messages::
 
    >>> parser = argparse.ArgumentParser(
    ...     prog='PROG',
@@ -442,6 +442,25 @@ will add information about the default value of each of the arguments::
     -h, --help  show this help message and exit
     --foo FOO   FOO! (default: 42)
 
+:class:`MetavarTypeHelpFormatter` uses the name of the type_ argument for each
+argument as as the display name for its values (rather than using the dest_
+as the regular formatter does)::
+
+   >>> parser = argparse.ArgumentParser(
+   ...     prog='PROG',
+   ...     formatter_class=argparse.MetavarTypeHelpFormatter)
+   >>> parser.add_argument('--foo', type=int)
+   >>> parser.add_argument('bar', type=float)
+   >>> parser.print_help()
+   usage: PROG [-h] [--foo int] float
+
+   positional arguments:
+     float
+
+   optional arguments:
+     -h, --help  show this help message and exit
+     --foo int
+
 
 conflict_handler
 ^^^^^^^^^^^^^^^^
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index e2c0b6d17d..85081be399 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -96,8 +96,8 @@ Node classes
 Abstract Grammar
 ----------------
 
-The module defines a string constant ``__version__`` which is the decimal
-Subversion revision number of the file shown below.
+The module defines a string constant ``__version__`` which is the Mercurial
+revision of the file shown below.
 
 The abstract grammar is currently defined as follows:
 
diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst
index 619b7bb639..5411c308d2 100644
--- a/Doc/library/asyncore.rst
+++ b/Doc/library/asyncore.rst
@@ -184,12 +184,14 @@ any that have been added to the map during asynchronous service) is closed.
    Most of these are nearly identical to their socket partners.
 
 
-   .. method:: create_socket(family, type)
+   .. method:: create_socket(family=socket.AF_INET, type=socket.SOCK_STREAM)
 
       This is identical to the creation of a normal socket, and will use the
       same options for creation.  Refer to the :mod:`socket` documentation for
       information on creating sockets.
 
+  .. versionchanged:: 3.3 family and type arguments can be omitted.
+
 
    .. method:: connect(address)
 
@@ -280,7 +282,7 @@ implement its socket handling::
 
        def __init__(self, host, path):
            asyncore.dispatcher.__init__(self)
-           self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
+           self.create_socket()
            self.connect( (host, 80) )
            self.buffer = bytes('GET %s HTTP/1.0\r\nHost: %s\r\n\r\n' %
                                (path, host), 'ascii')
@@ -327,7 +329,7 @@ connections and dispatches the incoming connections to a handler::
 
         def __init__(self, host, port):
             asyncore.dispatcher.__init__(self)
-            self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.create_socket()
             self.set_reuse_addr()
             self.bind((host, port))
             self.listen(5)
diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index cc1051bf74..db99eecbbb 100644
--- a/Doc/library/atexit.rst
+++ b/Doc/library/atexit.rst
@@ -62,7 +62,8 @@ automatically when the program terminates without relying on the application
 making an explicit call into this module at termination. ::
 
    try:
-       _count = int(open("/tmp/counter").read())
+       with open("/tmp/counter") as infile:
+           _count = int(infile.read())
    except IOError:
        _count = 0
 
@@ -71,7 +72,8 @@ making an explicit call into this module at termination. ::
        _count = _count + n
 
    def savecounter():
-       open("/tmp/counter", "w").write("%d" % _count)
+       with open("/tmp/counter", "w") as outfile:
+           outfile.write("%d" % _count)
 
    import atexit
    atexit.register(savecounter)
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index d9a2bad756..87f2cf32c2 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -1,189 +1,172 @@
-:mod:`bz2` --- Compression compatible with :program:`bzip2`
-===========================================================
+:mod:`bz2` --- Support for :program:`bzip2` compression
+=======================================================
 
 .. module:: bz2
-   :synopsis: Interface to compression and decompression routines
-              compatible with bzip2.
+   :synopsis: Interfaces for bzip2 compression and decompression.
 .. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
+.. moduleauthor:: Nadeem Vawda <nadeem.vawda@gmail.com>
 .. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
+.. sectionauthor:: Nadeem Vawda <nadeem.vawda@gmail.com>
 
 
-This module provides a comprehensive interface for the bz2 compression library.
-It implements a complete file interface, one-shot (de)compression functions, and
-types for sequential (de)compression.
+This module provides a comprehensive interface for compressing and
+decompressing data using the bzip2 compression algorithm.
 
-For other archive formats, see the :mod:`gzip`, :mod:`zipfile`, and
+For related file formats, see the :mod:`gzip`, :mod:`zipfile`, and
 :mod:`tarfile` modules.
 
-Here is a summary of the features offered by the bz2 module:
+The :mod:`bz2` module contains:
 
-* :class:`BZ2File` class implements a complete file interface, including
-  :meth:`~BZ2File.readline`, :meth:`~BZ2File.readlines`,
-  :meth:`~BZ2File.writelines`, :meth:`~BZ2File.seek`, etc;
+* The :class:`BZ2File` class for reading and writing compressed files.
+* The :class:`BZ2Compressor` and :class:`BZ2Decompressor` classes for
+  incremental (de)compression.
+* The :func:`compress` and :func:`decompress` functions for one-shot
+  (de)compression.
 
-* :class:`BZ2File` class implements emulated :meth:`~BZ2File.seek` support;
-
-* :class:`BZ2File` class implements universal newline support;
-
-* :class:`BZ2File` class offers an optimized line iteration using a readahead
-  algorithm;
-
-* Sequential (de)compression supported by :class:`BZ2Compressor` and
-  :class:`BZ2Decompressor` classes;
-
-* One-shot (de)compression supported by :func:`compress` and :func:`decompress`
-  functions;
-
-* Thread safety uses individual locking mechanism.
+All of the classes in this module may safely be accessed from multiple threads.
 
 
 (De)compression of files
 ------------------------
 
-Handling of compressed files is offered by the :class:`BZ2File` class.
-
-
-.. class:: BZ2File(filename, mode='r', buffering=0, compresslevel=9)
-
-   Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
-   or writing. When opened for writing, the file will be created if it doesn't
-   exist, and truncated otherwise. If *buffering* is given, ``0`` means
-   unbuffered, and larger numbers specify the buffer size; the default is
-   ``0``. If *compresslevel* is given, it must be a number between ``1`` and
-   ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input
-   with universal newline support. Any line ending in the input file will be
-   seen as a ``'\n'`` in Python.  Also, a file so opened gains the attribute
-   :attr:`newlines`; the value for this attribute is one of ``None`` (no newline
-   read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the
-   newline types seen. Universal newlines are available only when
-   reading. Instances support iteration in the same way as normal :class:`file`
-   instances.
+.. class:: BZ2File(filename=None, mode='r', buffering=None, compresslevel=9, fileobj=None)
 
-   :class:`BZ2File` supports the :keyword:`with` statement.
+   Open a bzip2-compressed file.
 
-   .. versionchanged:: 3.1
-      Support for the :keyword:`with` statement was added.
+   The :class:`BZ2File` can wrap an existing :term:`file object` (given by
+   *fileobj*), or operate directly on a named file (named by *filename*).
+   Exactly one of these two parameters should be provided.
 
+   The *mode* argument can be either ``'r'`` for reading (default), ``'w'`` for
+   overwriting, or ``'a'`` for appending. If *fileobj* is provided, a mode of
+   ``'w'`` does not truncate the file, and is instead equivalent to ``'a'``.
 
-   .. method:: close()
+   The *buffering* argument is ignored. Its use is deprecated.
 
-      Close the file. Sets data attribute :attr:`closed` to true. A closed file
-      cannot be used for further I/O operations. :meth:`close` may be called
-      more than once without error.
+   If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be a number between
+   ``1`` and ``9`` specifying the level of compression: ``1`` produces the
+   least compression, and ``9`` (default) produces the most compression.
 
+   If *mode* is ``'r'``, the input file may be the concatenation of multiple
+   compressed streams.
 
-   .. method:: read([size])
+   :class:`BZ2File` provides all of the members specified by the
+   :class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
+   Iteration and the :keyword:`with` statement are supported.
 
-      Read at most *size* uncompressed bytes, returned as a byte string. If the
-      *size* argument is negative or omitted, read until EOF is reached.
+   :class:`BZ2File` also provides the following method:
 
+   .. method:: peek([n])
 
-   .. method:: readline([size])
+      Return buffered data without advancing the file position. At least one
+      byte of data will be returned (unless at EOF). The exact number of bytes
+      returned is unspecified.
 
-      Return the next line from the file, as a byte string, retaining newline.
-      A non-negative *size* argument limits the maximum number of bytes to
-      return (an incomplete line may be returned then). Return an empty byte
-      string at EOF.
+      .. versionadded:: 3.3
 
+   .. versionchanged:: 3.1
+      Support for the :keyword:`with` statement was added.
 
-   .. method:: readlines([size])
-
-      Return a list of lines read. The optional *size* argument, if given, is an
-      approximate bound on the total number of bytes in the lines returned.
+   .. versionchanged:: 3.3
+      The :meth:`fileno`, :meth:`readable`, :meth:`seekable`, :meth:`writable`,
+      :meth:`read1` and :meth:`readinto` methods were added.
 
+   .. versionchanged:: 3.3
+      The *fileobj* argument to the constructor was added.
 
-   .. method:: seek(offset[, whence])
+   .. versionchanged:: 3.3
+      The ``'a'`` (append) mode was added, along with support for reading
+      multi-stream files.
 
-      Move to new file position. Argument *offset* is a byte count. Optional
-      argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start
-      of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or
-      ``1`` (move relative to current position; offset can be positive or
-      negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file;
-      offset is usually negative, although many platforms allow seeking beyond
-      the end of a file).
 
-      Note that seeking of bz2 files is emulated, and depending on the
-      parameters the operation may be extremely slow.
+Incremental (de)compression
+---------------------------
 
+.. class:: BZ2Compressor(compresslevel=9)
 
-   .. method:: tell()
+   Create a new compressor object. This object may be used to compress data
+   incrementally. For one-shot compression, use the :func:`compress` function
+   instead.
 
-      Return the current file position, an integer.
+   *compresslevel*, if given, must be a number between ``1`` and ``9``. The
+   default is ``9``.
 
+   .. method:: compress(data)
 
-   .. method:: write(data)
+      Provide data to the compressor object. Returns a chunk of compressed data
+      if possible, or an empty byte string otherwise.
 
-      Write the byte string *data* to file. Note that due to buffering,
-      :meth:`close` may be needed before the file on disk reflects the data
-      written.
+      When you have finished providing data to the compressor, call the
+      :meth:`flush` method to finish the compression process.
 
 
-   .. method:: writelines(sequence_of_byte_strings)
+   .. method:: flush()
 
-      Write the sequence of byte strings to the file. Note that newlines are not
-      added. The sequence can be any iterable object producing byte strings.
-      This is equivalent to calling write() for each byte string.
+      Finish the compression process. Returns the compressed data left in
+      internal buffers.
 
+      The compressor object may not be used after this method has been called.
 
-Sequential (de)compression
---------------------------
 
-Sequential compression and decompression is done using the classes
-:class:`BZ2Compressor` and :class:`BZ2Decompressor`.
+.. class:: BZ2Decompressor()
 
+   Create a new decompressor object. This object may be used to decompress data
+   incrementally. For one-shot compression, use the :func:`decompress` function
+   instead.
 
-.. class:: BZ2Compressor(compresslevel=9)
+   .. note::
+      This class does not transparently handle inputs containing multiple
+      compressed streams, unlike :func:`decompress` and :class:`BZ2File`. If
+      you need to decompress a multi-stream input with :class:`BZ2Decompressor`,
+      you must use a new decompressor for each stream.
 
-   Create a new compressor object. This object may be used to compress data
-   sequentially. If you want to compress data in one shot, use the
-   :func:`compress` function instead. The *compresslevel* parameter, if given,
-   must be a number between ``1`` and ``9``; the default is ``9``.
+   .. method:: decompress(data)
 
-   .. method:: compress(data)
+      Provide data to the decompressor object. Returns a chunk of decompressed
+      data if possible, or an empty byte string otherwise.
 
-      Provide more data to the compressor object. It will return chunks of
-      compressed data whenever possible. When you've finished providing data to
-      compress, call the :meth:`flush` method to finish the compression process,
-      and return what is left in internal buffers.
+      Attempting to decompress data after the end of the current stream is
+      reached raises an :exc:`EOFError`. If any data is found after the end of
+      the stream, it is ignored and saved in the :attr:`unused_data` attribute.
 
 
-   .. method:: flush()
+   .. attribute:: eof
 
-      Finish the compression process and return what is left in internal
-      buffers. You must not use the compressor object after calling this method.
+      True if the end-of-stream marker has been reached.
 
+      .. versionadded:: 3.3
 
-.. class:: BZ2Decompressor()
 
-   Create a new decompressor object. This object may be used to decompress data
-   sequentially. If you want to decompress data in one shot, use the
-   :func:`decompress` function instead.
+   .. attribute:: unused_data
 
-   .. method:: decompress(data)
+      Data found after the end of the compressed stream.
 
-      Provide more data to the decompressor object. It will return chunks of
-      decompressed data whenever possible. If you try to decompress data after
-      the end of stream is found, :exc:`EOFError` will be raised. If any data
-      was found after the end of stream, it'll be ignored and saved in
-      :attr:`unused_data` attribute.
+      If this attribute is accessed before the end of the stream has been
+      reached, its value will be ``b''``.
 
 
 One-shot (de)compression
 ------------------------
 
-One-shot compression and decompression is provided through the :func:`compress`
-and :func:`decompress` functions.
+.. function:: compress(data, compresslevel=9)
 
+   Compress *data*.
 
-.. function:: compress(data, compresslevel=9)
+   *compresslevel*, if given, must be a number between ``1`` and ``9``. The
+   default is ``9``.
 
-   Compress *data* in one shot. If you want to compress data sequentially, use
-   an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter,
-   if given, must be a number between ``1`` and ``9``; the default is ``9``.
+   For incremental compression, use a :class:`BZ2Compressor` instead.
 
 
 .. function:: decompress(data)
 
-   Decompress *data* in one shot. If you want to decompress data sequentially,
-   use an instance of :class:`BZ2Decompressor` instead.
+   Decompress *data*.
+
+   If *data* is the concatenation of multiple compressed streams, decompress
+   all of the streams.
+
+   For incremental decompression, use a :class:`BZ2Decompressor` instead.
+
+   .. versionchanged:: 3.3
+      Support for multi-stream inputs was added.
 
diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst
index e9a049fd8a..d45c0e781e 100644
--- a/Doc/library/cmd.rst
+++ b/Doc/library/cmd.rst
@@ -282,8 +282,8 @@ immediate playback::
         def do_playback(self, arg):
             'Playback commands from a file:  PLAYBACK rose.cmd'
             self.close()
-            cmds = open(arg).read().splitlines()
-            self.cmdqueue.extend(cmds)
+            with open(arg) as f:
+                self.cmdqueue.extend(f.read().splitlines())
         def precmd(self, line):
             line = line.lower()
             if self.file and 'playback' not in line:
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 922bcf488a..90bd0dd0f8 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -458,7 +458,8 @@ define in order to be compatible with the Python codec registry.
 
    .. method:: reset()
 
-      Reset the encoder to the initial state.
+      Reset the encoder to the initial state. The output is discarded: call
+      ``.encode('', final=True)`` to reset the encoder and to get the output.
 
 
 .. method:: IncrementalEncoder.getstate()
@@ -904,6 +905,15 @@ is meant to be exhaustive. Notice that spelling alternatives that only differ in
 case or use a hyphen instead of an underscore are also valid aliases; therefore,
 e.g. ``'utf-8'`` is a valid alias for the ``'utf_8'`` codec.
 
+.. impl-detail::
+
+   Some common encodings can bypass the codecs lookup machinery to
+   improve performance.  These optimization opportunities are only
+   recognized by CPython for a limited set of aliases: utf-8, utf8,
+   latin-1, latin1, iso-8859-1, mbcs (Windows only), ascii, utf-16,
+   and utf-32.  Using alternative spellings for these encodings may
+   result in slower execution.
+
 Many of the character sets support the same languages. They vary in individual
 characters (e.g. whether the EURO SIGN is supported or not), and in the
 assignment of characters to code positions. For the European languages in
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
new file mode 100644
index 0000000000..dbd89ae209
--- /dev/null
+++ b/Doc/library/collections.abc.rst
@@ -0,0 +1,181 @@
+:mod:`collections.abc` --- Abstract Base Classes for Containers
+===============================================================
+
+.. module:: collections.abc
+   :synopsis: Abstract base classes for containers
+.. moduleauthor:: Raymond Hettinger <python at rcn.com>
+.. sectionauthor:: Raymond Hettinger <python at rcn.com>
+
+.. testsetup:: *
+
+   from collections import *
+   import itertools
+   __name__ = '<doctest>'
+
+**Source code:** :source:`Lib/collections/abc.py`
+
+--------------
+
+This module provides :term:`abstract base classes <abstract base class>` that
+can be used to test whether a class provides a particular interface; for
+example, whether it is hashable or whether it is a mapping.
+
+.. versionchanged:: 3.3
+   Formerly, this module was part of the :mod:`collections` module.
+
+.. _collections-abstract-base-classes:
+
+Collections Abstract Base Classes
+---------------------------------
+
+The collections module offers the following :term:`ABCs <abstract base class>`:
+
+=========================  =====================  ======================  ====================================================
+ABC                        Inherits from          Abstract Methods        Mixin Methods
+=========================  =====================  ======================  ====================================================
+:class:`Container`                                ``__contains__``
+:class:`Hashable`                                 ``__hash__``
+:class:`Iterable`                                 ``__iter__``
+:class:`Iterator`          :class:`Iterable`      ``__next__``            ``__iter__``
+:class:`Sized`                                    ``__len__``
+:class:`Callable`                                 ``__call__``
+
+:class:`Sequence`          :class:`Sized`,        ``__getitem__``         ``__contains__``, ``__iter__``, ``__reversed__``,
+                           :class:`Iterable`,                             ``index``, and ``count``
+                           :class:`Container`
+
+:class:`MutableSequence`   :class:`Sequence`      ``__setitem__``,        Inherited :class:`Sequence` methods and
+                                                  ``__delitem__``,        ``append``, ``reverse``, ``extend``, ``pop``,
+                                                  ``insert``              ``remove``, ``clear``, and ``__iadd__``
+
+:class:`Set`               :class:`Sized`,                                ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
+                           :class:`Iterable`,                             ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
+                           :class:`Container`                             ``__sub__``, ``__xor__``, and ``isdisjoint``
+
+:class:`MutableSet`        :class:`Set`           ``add``,                Inherited :class:`Set` methods and
+                                                  ``discard``             ``clear``, ``pop``, ``remove``, ``__ior__``,
+                                                                          ``__iand__``, ``__ixor__``, and ``__isub__``
+
+:class:`Mapping`           :class:`Sized`,        ``__getitem__``         ``__contains__``, ``keys``, ``items``, ``values``,
+                           :class:`Iterable`,                             ``get``, ``__eq__``, and ``__ne__``
+                           :class:`Container`
+
+:class:`MutableMapping`    :class:`Mapping`       ``__setitem__``,        Inherited :class:`Mapping` methods and
+                                                  ``__delitem__``         ``pop``, ``popitem``, ``clear``, ``update``,
+                                                                          and ``setdefault``
+
+
+:class:`MappingView`       :class:`Sized`                                 ``__len__``
+:class:`ItemsView`         :class:`MappingView`,                          ``__contains__``,
+                           :class:`Set`                                   ``__iter__``
+:class:`KeysView`          :class:`MappingView`,                          ``__contains__``,
+                           :class:`Set`                                   ``__iter__``
+:class:`ValuesView`        :class:`MappingView`                           ``__contains__``, ``__iter__``
+=========================  =====================  ======================  ====================================================
+
+
+.. class:: Container
+           Hashable
+           Sized
+           Callable
+
+   ABCs for classes that provide respectively the methods :meth:`__contains__`,
+   :meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.
+
+.. class:: Iterable
+
+   ABC for classes that provide the :meth:`__iter__` method.
+   See also the definition of :term:`iterable`.
+
+.. class:: Iterator
+
+   ABC for classes that provide the :meth:`__iter__` and :meth:`next` methods.
+   See also the definition of :term:`iterator`.
+
+.. class:: Sequence
+           MutableSequence
+
+   ABCs for read-only and mutable :term:`sequences <sequence>`.
+
+.. class:: Set
+           MutableSet
+
+   ABCs for read-only and mutable sets.
+
+.. class:: Mapping
+           MutableMapping
+
+   ABCs for read-only and mutable :term:`mappings <mapping>`.
+
+.. class:: MappingView
+           ItemsView
+           KeysView
+           ValuesView
+
+   ABCs for mapping, items, keys, and values :term:`views <view>`.
+
+
+These ABCs allow us to ask classes or instances if they provide
+particular functionality, for example::
+
+    size = None
+    if isinstance(myvar, collections.Sized):
+        size = len(myvar)
+
+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
+abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
+The ABC supplies the remaining methods such as :meth:`__and__` and
+:meth:`isdisjoint` ::
+
+    class ListBasedSet(collections.Set):
+         ''' Alternate set implementation favoring space over speed
+             and not requiring the set elements to be hashable. '''
+         def __init__(self, iterable):
+             self.elements = lst = []
+             for value in iterable:
+                 if value not in lst:
+                     lst.append(value)
+         def __iter__(self):
+             return iter(self.elements)
+         def __contains__(self, value):
+             return value in self.elements
+         def __len__(self):
+             return len(self.elements)
+
+    s1 = ListBasedSet('abcdef')
+    s2 = ListBasedSet('defghi')
+    overlap = s1 & s2            # The __and__() method is supported automatically
+
+Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
+
+(1)
+   Since some set operations create new sets, the default mixin methods need
+   a way to create new instances from an iterable. The class constructor is
+   assumed to have a signature in the form ``ClassName(iterable)``.
+   That assumption is factored-out to an internal classmethod called
+   :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
+   If the :class:`Set` mixin is being used in a class with a different
+   constructor signature, you will need to override :meth:`_from_iterable`
+   with a classmethod that can construct new instances from
+   an iterable argument.
+
+(2)
+   To override the comparisons (presumably for speed, as the
+   semantics are fixed), redefine :meth:`__le__` and
+   then the other operations will automatically follow suit.
+
+(3)
+   The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
+   for the set; however, :meth:`__hash__` is not defined because not all sets
+   are hashable or immutable.  To add set hashabilty using mixins,
+   inherit from both :meth:`Set` and :meth:`Hashable`, then define
+   ``__hash__ = Set._hash``.
+
+.. seealso::
+
+   * `OrderedSet recipe <http://code.activestate.com/recipes/576694/>`_ for an
+     example built on :class:`MutableSet`.
+
+   * For more about ABCs, see the :mod:`abc` module and :pep:`3119`.
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 4975f74770..f344b5a955 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -13,7 +13,7 @@
    import itertools
    __name__ = '<doctest>'
 
-**Source code:** :source:`Lib/collections.py` and :source:`Lib/_abcoll.py`
+**Source code:** :source:`Lib/collections/__init__.py`
 
 --------------
 
@@ -24,6 +24,7 @@ Python's general purpose built-in containers, :class:`dict`, :class:`list`,
 =====================   ====================================================================
 :func:`namedtuple`      factory function for creating tuple subclasses with named fields
 :class:`deque`          list-like container with fast appends and pops on either end
+:class:`ChainMap`       dict-like class for creating a single view of multiple mappings
 :class:`Counter`        dict subclass for counting hashable objects
 :class:`OrderedDict`    dict subclass that remembers the order entries were added
 :class:`defaultdict`    dict subclass that calls a factory function to supply missing values
@@ -32,12 +33,125 @@ Python's general purpose built-in containers, :class:`dict`, :class:`list`,
 :class:`UserString`     wrapper around string objects for easier string subclassing
 =====================   ====================================================================
 
-In addition to the concrete container classes, the collections module provides
-:ref:`abstract base classes <collections-abstract-base-classes>` that can be
-used to test whether a class provides a particular interface, for example,
-whether it is hashable or a mapping.
+.. versionchanged:: 3.3
+   Moved :ref:`collections-abstract-base-classes` to the :mod:`collections.abc` module.
+   For backwards compatibility, they continue to be visible in this module
+   as well.
 
 
+:class:`ChainMap` objects
+-------------------------
+
+A :class:`ChainMap` class is provided for quickly linking a number of mappings
+so they can be treated as a single unit.  It is often much faster than creating
+a new dictionary and running multiple :meth:`~dict.update` calls.
+
+The class can be used to simulate nested scopes and is useful in templating.
+
+.. class:: ChainMap(*maps)
+
+   A :class:`ChainMap` groups multiple dicts or other mappings together to
+   create a single, updateable view.  If no *maps* are specified, a single empty
+   dictionary is provided so that a new chain always has at least one mapping.
+
+   The underlying mappings are stored in a list.  That list is public and can
+   accessed or updated using the *maps* attribute.  There is no other state.
+
+   Lookups search the underlying mappings successively until a key is found.  In
+   contrast, writes, updates, and deletions only operate on the first mapping.
+
+   A :class:`ChainMap` incorporates the underlying mappings by reference.  So, if
+   one of the underlying mappings gets updated, those changes will be reflected
+   in :class:`ChainMap`.
+
+   All of the usual dictionary methods are supported.  In addition, there is a
+   *maps* attribute, a method for creating new subcontexts, and a property for
+   accessing all but the first mapping:
+
+   .. attribute:: maps
+
+      A user updateable list of mappings.  The list is ordered from
+      first-searched to last-searched.  It is the only stored state and can
+      modified to change which mappings are searched.  The list should
+      always contain at least one mapping.
+
+   .. method:: new_child()
+
+      Returns a new :class:`ChainMap` containing a new :class:`dict` followed by
+      all of the maps in the current instance.  A call to ``d.new_child()`` is
+      equivalent to: ``ChainMap({}, *d.maps)``.  This method is used for
+      creating subcontexts that can be updated without altering values in any
+      of the parent mappings.
+
+   .. method:: parents()
+
+      Returns a new :class:`ChainMap` containing all of the maps in the current
+      instance except the first one.  This is useful for skipping the first map
+      in the search.  The use-cases are similar to those for the
+      :keyword:`nonlocal` keyword used in :term:`nested scopes <nested scope>`.
+      The use-cases also parallel those for the builtin :func:`super` function.
+      A reference to  ``d.parents`` is equivalent to: ``ChainMap(*d.maps[1:])``.
+
+  .. versionadded:: 3.3
+
+  Example of simulating Python's internal lookup chain::
+
+     import builtins
+     pylookup = ChainMap(locals(), globals(), vars(builtins))
+
+  Example of letting user specified values take precedence over environment
+  variables which in turn take precedence over default values::
+
+     import os, argparse
+     defaults = {'color': 'red', 'user': guest}
+     parser = argparse.ArgumentParser()
+     parser.add_argument('-u', '--user')
+     parser.add_argument('-c', '--color')
+     user_specified = vars(parser.parse_args())
+     combined = ChainMap(user_specified, os.environ, defaults)
+
+  Example patterns for using the :class:`ChainMap` class to simulate nested
+  contexts::
+
+    c = ChainMap()          Create root context
+    d = c.new_child()       Create nested child context
+    e = c.new_child()       Child of c, independent from d
+    e.maps[0]               Current context dictionary -- like Python's locals()
+    e.maps[-1]              Root context -- like Python's globals()
+    e.parents               Enclosing context chain -- like Python's nonlocals
+
+    d['x']                  Get first key in the chain of contexts
+    d['x'] = 1              Set value in current context
+    del['x']                Delete from current context
+    list(d)                 All nested values
+    k in d                  Check all nested values
+    len(d)                  Number of nested values
+    d.items()               All nested items
+    dict(d)                 Flatten into a regular dictionary
+
+  .. seealso::
+
+     * The `MultiContext class
+       <http://svn.enthought.com/svn/enthought/CodeTools/trunk/enthought/contexts/multi_context.py>`_
+       in the Enthought `CodeTools package
+       <https://github.com/enthought/codetools>`_ has options to support
+       writing to any mapping in the chain.
+
+     * Django's `Context class
+       <http://code.djangoproject.com/browser/django/trunk/django/template/context.py>`_
+       for templating is a read-only chain of mappings.  It also features
+       pushing and popping of contexts similar to the
+       :meth:`~collections.ChainMap.new_child` method and the
+       :meth:`~collections.ChainMap.parents` property.
+
+     * The `Nested Contexts recipe
+       <http://code.activestate.com/recipes/577434/>`_ has options to control
+       whether writes and other mutations apply only to the first mapping or to
+       any mapping in the chain.
+
+     * A `greatly simplified read-only version of Chainmap
+       <http://code.activestate.com/recipes/305268/>`_.
+
 :class:`Counter` objects
 ------------------------
 
@@ -399,7 +513,8 @@ in Unix::
 
    def tail(filename, n=10):
        'Return the last n lines of a file'
-       return deque(open(filename), n)
+       with open(filename) as f:
+           return deque(f, n)
 
 Another approach to using deques is to maintain a sequence of recently
 added elements by appending to the right and popping to the left::
@@ -546,7 +661,7 @@ Setting the :attr:`default_factory` to :class:`set` makes the
    ...     d[k].add(v)
    ...
    >>> list(d.items())
-   [('blue', set([2, 4])), ('red', set([1, 3]))]
+   [('blue', {2, 4}), ('red', {1, 3})]
 
 
 :func:`namedtuple` Factory Function for Tuples with Named Fields
@@ -579,7 +694,9 @@ they add the ability to access fields by name instead of position index.
    converted to ``['abc', '_1', 'ghi', '_3']``, eliminating the keyword
    ``def`` and the duplicate fieldname ``abc``.
 
-   If *verbose* is true, the class definition is printed just before being built.
+   If *verbose* is true, the class definition is printed after it is
+   built.  This option is outdated; instead, it is simpler to print the
+   :attr:`_source` attribute.
 
    Named tuple instances do not have per-instance dictionaries, so they are
    lightweight and require no more memory than regular tuples.
@@ -593,53 +710,6 @@ they add the ability to access fields by name instead of position index.
 
    >>> # Basic example
    >>> Point = namedtuple('Point', ['x', 'y'])
-   >>> p = Point(x=10, y=11)
-
-   >>> # Example using the verbose option to print the class definition
-   >>> Point = namedtuple('Point', 'x y', verbose=True)
-   class Point(tuple):
-           'Point(x, y)'
-   <BLANKLINE>
-           __slots__ = ()
-   <BLANKLINE>
-           _fields = ('x', 'y')
-   <BLANKLINE>
-           def __new__(_cls, x, y):
-               'Create a new instance of Point(x, y)'
-               return _tuple.__new__(_cls, (x, y))
-   <BLANKLINE>
-           @classmethod
-           def _make(cls, iterable, new=tuple.__new__, len=len):
-               'Make a new Point object from a sequence or iterable'
-               result = new(cls, iterable)
-               if len(result) != 2:
-                   raise TypeError('Expected 2 arguments, got %d' % len(result))
-               return result
-   <BLANKLINE>
-           def __repr__(self):
-               'Return a nicely formatted representation string'
-               return self.__class__.__name__ + '(x=%r, y=%r)' % self
-   <BLANKLINE>
-           def _asdict(self):
-               'Return a new OrderedDict which maps field names to their values'
-               return OrderedDict(zip(self._fields, self))
-   <BLANKLINE>
-           __dict__ = property(_asdict)
-   <BLANKLINE>
-           def _replace(_self, **kwds):
-               'Return a new Point object replacing specified fields with new values'
-               result = _self._make(map(kwds.pop, ('x', 'y'), _self))
-               if kwds:
-                   raise ValueError('Got unexpected field names: %r' % list(kwds.keys()))
-               return result
-   <BLANKLINE>
-           def __getnewargs__(self):
-               'Return self as a plain tuple.   Used by copy and pickle.'
-               return tuple(self)
-   <BLANKLINE>
-           x = _property(_itemgetter(0), doc='Alias for field number 0')
-           y = _property(_itemgetter(1), doc='Alias for field number 1')
-
    >>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
    >>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
    33
@@ -668,7 +738,7 @@ by the :mod:`csv` or :mod:`sqlite3` modules::
        print(emp.name, emp.title)
 
 In addition to the methods inherited from tuples, named tuples support
-three additional methods and one attribute.  To prevent conflicts with
+three additional methods and two attributes.  To prevent conflicts with
 field names, the method and attribute names start with an underscore.
 
 .. classmethod:: somenamedtuple._make(iterable)
@@ -706,6 +776,15 @@ field names, the method and attribute names start with an underscore.
       >>> for partnum, record in inventory.items():
       ...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
 
+.. attribute:: somenamedtuple._source
+
+   A string with the pure Python source code used to create the named
+   tuple class.  The source makes the named tuple self-documenting.
+   It can be printed, executed using :func:`exec`, or saved to a file
+   and imported.
+
+   .. versionadded:: 3.3
+
 .. attribute:: somenamedtuple._fields
 
    Tuple of strings listing the field names.  Useful for introspection
@@ -754,7 +833,6 @@ a fixed-width print format:
 The subclass shown above sets ``__slots__`` to an empty tuple.  This helps
 keep memory requirements low by preventing the creation of instance dictionaries.
 
-
 Subclassing is not useful for adding new, stored fields.  Instead, simply
 create a new named tuple type from the :attr:`_fields` attribute:
 
@@ -766,6 +844,7 @@ customize a prototype instance:
     >>> Account = namedtuple('Account', 'owner balance transaction_count')
     >>> default_account = Account('<owner name>', 0.0, 0)
     >>> johns_account = default_account._replace(owner='John')
+    >>> 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 declaration:
@@ -984,160 +1063,3 @@ attribute.
    be an instance of :class:`bytes`, :class:`str`, :class:`UserString` (or a
    subclass) or an arbitrary sequence which can be converted into a string using
    the built-in :func:`str` function.
-
-.. _collections-abstract-base-classes:
-
-ABCs - abstract base classes
-----------------------------
-
-The collections module offers the following :term:`ABCs <abstract base class>`:
-
-=========================  =====================  ======================  ====================================================
-ABC                        Inherits from          Abstract Methods        Mixin Methods
-=========================  =====================  ======================  ====================================================
-:class:`Container`                                ``__contains__``
-:class:`Hashable`                                 ``__hash__``
-:class:`Iterable`                                 ``__iter__``
-:class:`Iterator`          :class:`Iterable`      ``__next__``            ``__iter__``
-:class:`Sized`                                    ``__len__``
-:class:`Callable`                                 ``__call__``
-
-:class:`Sequence`          :class:`Sized`,        ``__getitem__``         ``__contains__``, ``__iter__``, ``__reversed__``,
-                           :class:`Iterable`,                             ``index``, and ``count``
-                           :class:`Container`
-
-:class:`MutableSequence`   :class:`Sequence`      ``__setitem__``,        Inherited :class:`Sequence` methods and
-                                                  ``__delitem__``,        ``append``, ``reverse``, ``extend``, ``pop``,
-                                                  ``insert``              ``remove``, and ``__iadd__``
-
-:class:`Set`               :class:`Sized`,                                ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
-                           :class:`Iterable`,                             ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
-                           :class:`Container`                             ``__sub__``, ``__xor__``, and ``isdisjoint``
-
-:class:`MutableSet`        :class:`Set`           ``add``,                Inherited :class:`Set` methods and
-                                                  ``discard``             ``clear``, ``pop``, ``remove``, ``__ior__``,
-                                                                          ``__iand__``, ``__ixor__``, and ``__isub__``
-
-:class:`Mapping`           :class:`Sized`,        ``__getitem__``         ``__contains__``, ``keys``, ``items``, ``values``,
-                           :class:`Iterable`,                             ``get``, ``__eq__``, and ``__ne__``
-                           :class:`Container`
-
-:class:`MutableMapping`    :class:`Mapping`       ``__setitem__``,        Inherited :class:`Mapping` methods and
-                                                  ``__delitem__``         ``pop``, ``popitem``, ``clear``, ``update``,
-                                                                          and ``setdefault``
-
-
-:class:`MappingView`       :class:`Sized`                                 ``__len__``
-:class:`ItemsView`         :class:`MappingView`,                          ``__contains__``,
-                           :class:`Set`                                   ``__iter__``
-:class:`KeysView`          :class:`MappingView`,                          ``__contains__``,
-                           :class:`Set`                                   ``__iter__``
-:class:`ValuesView`        :class:`MappingView`                           ``__contains__``, ``__iter__``
-=========================  =====================  ======================  ====================================================
-
-
-.. class:: Container
-           Hashable
-           Sized
-           Callable
-
-   ABCs for classes that provide respectively the methods :meth:`__contains__`,
-   :meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.
-
-.. class:: Iterable
-
-   ABC for classes that provide the :meth:`__iter__` method.
-   See also the definition of :term:`iterable`.
-
-.. class:: Iterator
-
-   ABC for classes that provide the :meth:`__iter__` and :meth:`next` methods.
-   See also the definition of :term:`iterator`.
-
-.. class:: Sequence
-           MutableSequence
-
-   ABCs for read-only and mutable :term:`sequences <sequence>`.
-
-.. class:: Set
-           MutableSet
-
-   ABCs for read-only and mutable sets.
-
-.. class:: Mapping
-           MutableMapping
-
-   ABCs for read-only and mutable :term:`mappings <mapping>`.
-
-.. class:: MappingView
-           ItemsView
-           KeysView
-           ValuesView
-
-   ABCs for mapping, items, keys, and values :term:`views <view>`.
-
-
-These ABCs allow us to ask classes or instances if they provide
-particular functionality, for example::
-
-    size = None
-    if isinstance(myvar, collections.Sized):
-        size = len(myvar)
-
-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
-abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
-The ABC supplies the remaining methods such as :meth:`__and__` and
-:meth:`isdisjoint` ::
-
-    class ListBasedSet(collections.Set):
-         ''' Alternate set implementation favoring space over speed
-             and not requiring the set elements to be hashable. '''
-         def __init__(self, iterable):
-             self.elements = lst = []
-             for value in iterable:
-                 if value not in lst:
-                     lst.append(value)
-         def __iter__(self):
-             return iter(self.elements)
-         def __contains__(self, value):
-             return value in self.elements
-         def __len__(self):
-             return len(self.elements)
-
-    s1 = ListBasedSet('abcdef')
-    s2 = ListBasedSet('defghi')
-    overlap = s1 & s2            # The __and__() method is supported automatically
-
-Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
-
-(1)
-   Since some set operations create new sets, the default mixin methods need
-   a way to create new instances from an iterable. The class constructor is
-   assumed to have a signature in the form ``ClassName(iterable)``.
-   That assumption is factored-out to an internal classmethod called
-   :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
-   If the :class:`Set` mixin is being used in a class with a different
-   constructor signature, you will need to override :meth:`_from_iterable`
-   with a classmethod that can construct new instances from
-   an iterable argument.
-
-(2)
-   To override the comparisons (presumably for speed, as the
-   semantics are fixed), redefine :meth:`__le__` and
-   then the other operations will automatically follow suit.
-
-(3)
-   The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
-   for the set; however, :meth:`__hash__` is not defined because not all sets
-   are hashable or immutable.  To add set hashabilty using mixins,
-   inherit from both :meth:`Set` and :meth:`Hashable`, then define
-   ``__hash__ = Set._hash``.
-
-.. seealso::
-
-   * `OrderedSet recipe <http://code.activestate.com/recipes/576694/>`_ for an
-     example built on :class:`MutableSet`.
-
-   * For more about ABCs, see the :mod:`abc` module and :pep:`3119`.
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index e5d13f37f3..3bd4531506 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -169,6 +169,12 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
    of at most *max_workers* processes.  If *max_workers* is ``None`` or not
    given, it will default to the number of processors on the machine.
 
+   .. versionchanged:: 3.3
+      When one of the worker processes terminates abruptly, a
+      :exc:`BrokenProcessPool` error is now raised.  Previously, behaviour
+      was undefined but operations on the executor or its futures would often
+      freeze or deadlock.
+
 
 .. _processpoolexecutor-example:
 
@@ -369,3 +375,16 @@ Module Functions
    :pep:`3148` -- futures - execute computations asynchronously
       The proposal which described this feature for inclusion in the Python
       standard library.
+
+
+Exception classes
+-----------------
+
+.. exception:: BrokenProcessPool
+
+   Derived from :exc:`RuntimeError`, this exception class is raised when
+   one of the workers of a :class:`ProcessPoolExecutor` has terminated
+   in a non-clean fashion (for example, if it was killed from the outside).
+
+   .. versionadded:: 3.3
+
diff --git a/Doc/library/crypt.rst b/Doc/library/crypt.rst
index 0be571eb51..1ba2ed3427 100644
--- a/Doc/library/crypt.rst
+++ b/Doc/library/crypt.rst
@@ -15,9 +15,9 @@
 
 This module implements an interface to the :manpage:`crypt(3)` routine, which is
 a one-way hash function based upon a modified DES algorithm; see the Unix man
-page for further details.  Possible uses include allowing Python scripts to
-accept typed passwords from the user, or attempting to crack Unix passwords with
-a dictionary.
+page for further details.  Possible uses include storing hashed passwords
+so you can check passwords without storing the actual password, or attempting
+to crack Unix passwords with a dictionary.
 
 .. index:: single: crypt(3)
 
@@ -26,15 +26,74 @@ the :manpage:`crypt(3)` routine in the running system.  Therefore, any
 extensions available on the current implementation will also  be available on
 this module.
 
+Hashing Methods
+---------------
 
-.. function:: crypt(word, salt)
+.. versionadded:: 3.3
+
+The :mod:`crypt` module defines the list of hashing methods (not all methods
+are available on all platforms):
+
+.. data:: METHOD_SHA512
+
+   A Modular Crypt Format method with 16 character salt and 86 character
+   hash.  This is the strongest method.
+
+.. data:: METHOD_SHA256
+
+   Another Modular Crypt Format method with 16 character salt and 43
+   character hash.
+
+.. data:: METHOD_MD5
+
+   Another Modular Crypt Format method with 8 character salt and 22
+   character hash.
+
+.. data:: METHOD_CRYPT
+
+   The traditional method with a 2 character salt and 13 characters of
+   hash.  This is the weakest method.
+
+
+Module Attributes
+-----------------
+
+.. versionadded:: 3.3
+
+.. attribute:: methods
+
+   A list of available password hashing algorithms, as
+   ``crypt.METHOD_*`` objects.  This list is sorted from strongest to
+   weakest, and is guaranteed to have at least ``crypt.METHOD_CRYPT``.
+
+
+Module Functions
+----------------
+
+The :mod:`crypt` module defines the following functions:
+
+.. function:: crypt(word, salt=None)
 
    *word* will usually be a user's password as typed at a prompt or  in a graphical
-   interface.  *salt* is usually a random two-character string which will be used
-   to perturb the DES algorithm in one of 4096 ways.  The characters in *salt* must
-   be in the set ``[./a-zA-Z0-9]``.  Returns the hashed password as a string, which
-   will be composed of characters from the same alphabet as the salt (the first two
-   characters represent the salt itself).
+   interface.  The optional *salt* is either a string as returned from
+   :func:`mksalt`, one of the ``crypt.METHOD_*`` values (though not all
+   may be available on all platforms), or a full encrypted password
+   including salt, as returned by this function.  If *salt* is not
+   provided, the strongest method will be used (as returned by
+   :func:`methods`.
+
+   Checking a password is usually done by passing the plain-text password
+   as *word* and the full results of a previous :func:`crypt` call,
+   which should be the same as the results of this call.
+
+   *salt* (either a random 2 or 16 character string, possibly prefixed with
+   ``$digit$`` to indicate the method) which will be used to perturb the
+   encryption algorithm.  The characters in *salt* must be in the set
+   ``[./a-zA-Z0-9]``, with the exception of Modular Crypt Format which
+   prefixes a ``$digit$``.
+
+   Returns the hashed password as a string, which will be composed of
+   characters from the same alphabet as the salt.
 
    .. index:: single: crypt(3)
 
@@ -42,18 +101,48 @@ this module.
    different sizes in the *salt*, it is recommended to use  the full crypted
    password as salt when checking for a password.
 
+   .. versionchanged:: 3.3
+      Accept ``crypt.METHOD_*`` values in addition to strings for *salt*.
+
+
+.. function:: mksalt(method=None)
+
+   Return a randomly generated salt of the specified method.  If no
+   *method* is given, the strongest method available as returned by
+   :func:`methods` is used.
+
+   The return value is a string either of 2 characters in length for
+   ``crypt.METHOD_CRYPT``, or 19 characters starting with ``$digit$`` and
+   16 random characters from the set ``[./a-zA-Z0-9]``, suitable for
+   passing as the *salt* argument to :func:`crypt`.
+
+   .. versionadded:: 3.3
+
+Examples
+--------
+
 A simple example illustrating typical use::
 
-   import crypt, getpass, pwd
+   import pwd
+   import crypt
+   import getpass
 
    def login():
-       username = input('Python login:')
+       username = input('Python login: ')
        cryptedpasswd = pwd.getpwnam(username)[1]
        if cryptedpasswd:
            if cryptedpasswd == 'x' or cryptedpasswd == '*':
-               raise "Sorry, currently no support for shadow passwords"
+               raise ValueError('no support for shadow passwords')
            cleartext = getpass.getpass()
            return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
        else:
-           return 1
+           return True
+
+To generate a hash of a password using the strongest available method and
+check it against the original::
+
+   import crypt
 
+   hashed = crypt.crypt(plaintext)
+   if hashed != crypt.crypt(plaintext, hashed):
+      raise ValueError("hashed version doesn't validate against original")
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index edbe7263df..ec0dfccfab 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -11,15 +11,15 @@
    pair: data; tabular
 
 The so-called CSV (Comma Separated Values) format is the most common import and
-export format for spreadsheets and databases.  There is no "CSV standard", so
-the format is operationally defined by the many applications which read and
-write it.  The lack of a standard means that subtle differences often exist in
-the data produced and consumed by different applications.  These differences can
-make it annoying to process CSV files from multiple sources.  Still, while the
-delimiters and quoting characters vary, the overall format is similar enough
-that it is possible to write a single module which can efficiently manipulate
-such data, hiding the details of reading and writing the data from the
-programmer.
+export format for spreadsheets and databases.  CSV format was used for many
+years prior to attempts to describe the format in a standardized way in
+:rfc:`4180`.  The lack of a well-defined standard means that subtle differences
+often exist in the data produced and consumed by different applications.  These
+differences can make it annoying to process CSV files from multiple sources.
+Still, while the delimiters and quoting characters vary, the overall format is
+similar enough that it is possible to write a single module which can
+efficiently manipulate such data, hiding the details of reading and writing the
+data from the programmer.
 
 The :mod:`csv` module implements classes to read and write tabular data in CSV
 format.  It allows programmers to say, "write this data in the format preferred
diff --git a/Doc/library/datatypes.rst b/Doc/library/datatypes.rst
index 6b4a71a3ad..8e33c1ff4e 100644
--- a/Doc/library/datatypes.rst
+++ b/Doc/library/datatypes.rst
@@ -21,6 +21,7 @@ The following modules are documented in this chapter:
    datetime.rst
    calendar.rst
    collections.rst
+   collections.abc.rst
    heapq.rst
    bisect.rst
    array.rst
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index b5b6cef3fb..c8e22f1655 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -721,6 +721,22 @@ Other constructors, all class methods:
    It's common for this to be restricted to years in 1970 through 2038. See also
    :meth:`fromtimestamp`.
 
+   On the POSIX compliant platforms, ``utcfromtimestamp(timestamp)``
+   is equivalent to the following expression::
+
+     datetime(1970, 1, 1) + timedelta(seconds=timestamp)
+
+   There is no method to obtain the timestamp from a :class:`datetime`
+   instance, but POSIX timestamp corresponding to a :class:`datetime`
+   instance ``dt`` can be easily calculated as follows.  For a naive
+   ``dt``::
+
+      timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
+
+   And for an aware ``dt``::
+
+      timestamp = (dt - datetime(1970, 1, 1, tzinfo=timezone.utc)) / timedelta(seconds=1)
+
 
 .. classmethod:: datetime.fromordinal(ordinal)
 
@@ -1562,11 +1578,12 @@ only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
 :class:`timezone` Objects
 --------------------------
 
-A :class:`timezone` object represents a timezone that is defined by a
-fixed offset from UTC.  Note that objects of this class cannot be used
-to represent timezone information in the locations where different
-offsets are used in different days of the year or where historical
-changes have been made to civil time.
+The :class:`timezone` class is a subclass of :class:`tzinfo`, each
+instance of which represents a timezone defined by a fixed offset from
+UTC.  Note that objects of this class cannot be used to represent
+timezone information in the locations where different offsets are used
+in different days of the year or where historical changes have been
+made to civil time.
 
 
 .. class:: timezone(offset[, name])
@@ -1735,8 +1752,7 @@ format codes.
 |           | decimal number [00,99].        |       |
 +-----------+--------------------------------+-------+
 | ``%Y``    | Year with century as a decimal | \(5)  |
-|           | number [0001,9999] (strptime), |       |
-|           | [1000,9999] (strftime).        |       |
+|           | number [0001,9999].            |       |
 +-----------+--------------------------------+-------+
 | ``%z``    | UTC offset in the form +HHMM   | \(6)  |
 |           | or -HHMM (empty string if the  |       |
@@ -1770,10 +1786,7 @@ Notes:
    calculations when the day of the week and the year are specified.
 
 (5)
-   For technical reasons, :meth:`strftime` method does not support
-   dates before year 1000: ``t.strftime(format)`` will raise a
-   :exc:`ValueError` when ``t.year < 1000`` even if ``format`` does
-   not contain ``%Y`` directive.  The :meth:`strptime` method can
+   The :meth:`strptime` method can
    parse years in the full [1, 9999] range, but years < 1000 must be
    zero-filled to 4-digit width.
 
@@ -1781,6 +1794,10 @@ Notes:
       In previous versions, :meth:`strftime` method was restricted to
       years >= 1900.
 
+   .. versionchanged:: 3.3
+      In version 3.2, :meth:`strftime` method was restricted to
+      years >= 1000.
+
 (6)
    For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
    ``%z`` is replaced with the string ``'-0330'``.
diff --git a/Doc/library/debug.rst b/Doc/library/debug.rst
index b2ee4fa098..c69fb1c846 100644
--- a/Doc/library/debug.rst
+++ b/Doc/library/debug.rst
@@ -10,7 +10,8 @@ allowing you to identify bottlenecks in your programs.
 .. toctree::
 
    bdb.rst
+   faulthandler.rst
    pdb.rst
    profile.rst
    timeit.rst
-   trace.rst
\ No newline at end of file
+   trace.rst
diff --git a/Doc/library/depgraph-output.png b/Doc/library/depgraph-output.png
new file mode 100644
index 0000000000..960bb1b563
--- /dev/null
+++ b/Doc/library/depgraph-output.png
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index bdc37b3e0a..836e240b83 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -752,8 +752,8 @@ It is also contained in the Python source distribution, as
        # we're passing these as arguments to the diff function
        fromdate = time.ctime(os.stat(fromfile).st_mtime)
        todate = time.ctime(os.stat(tofile).st_mtime)
-       fromlines = open(fromfile, 'U').readlines()
-       tolines = open(tofile, 'U').readlines()
+       with open(fromlines) as fromf, open(tofile) as tof:
+           fromlines, tolines = list(fromf), list(tof)
 
        if options.u:
            diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile,
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
index 238b79dac2..53a69aecd7 100644
--- a/Doc/library/distutils.rst
+++ b/Doc/library/distutils.rst
@@ -12,18 +12,26 @@ additional modules into a Python installation.  The new modules may be either
 100%-pure Python, or may be extension modules written in C, or may be
 collections of Python packages which include modules coded in both Python and C.
 
-This package is discussed in two separate chapters:
+.. deprecated:: 3.3
+   :mod:`packaging` replaces Distutils.  See :ref:`packaging-index` and
+   :ref:`packaging-install-index`.
 
 
+User documentation and API reference are provided in another document:
+
 .. seealso::
 
    :ref:`distutils-index`
       The manual for developers and packagers of Python modules.  This describes
       how to prepare :mod:`distutils`\ -based packages so that they may be
-      easily installed into an existing Python installation.
+      easily installed into an existing Python installation.  If also contains
+      instructions for end-users wanting to install a distutils-based package,
+      :ref:`install-index`.
+
+
+.. trick to silence a Sphinx warning
 
-   :ref:`install-index`
-      An "administrators" manual which includes information on installing
-      modules into an existing Python installation.  You do not need to be a
-      Python programmer to read this manual.
+.. toctree::
+   :hidden:
 
+   ../distutils/index
diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst
index 85b32fe7fe..847d7e4a0f 100644
--- a/Doc/library/email.generator.rst
+++ b/Doc/library/email.generator.rst
@@ -32,7 +32,8 @@ Here are the public methods of the :class:`Generator` class, imported from the
 :mod:`email.generator` module:
 
 
-.. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78)
+.. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78, *, \
+                     policy=policy.default)
 
    The constructor for the :class:`Generator` class takes a :term:`file-like object`
    called *outfp* for an argument.  *outfp* must support the :meth:`write` method
@@ -53,10 +54,16 @@ Here are the public methods of the :class:`Generator` class, imported from the
    :class:`~email.header.Header` class.  Set to zero to disable header wrapping.
    The default is 78, as recommended (but not required) by :rfc:`2822`.
 
+   The *policy* keyword specifies a :mod:`~email.policy` object that controls a
+   number of aspects of the generator's operation.  The default policy
+   maintains backward compatibility.
+
+   .. versionchanged:: 3.3 Added the *policy* keyword.
+
    The other public :class:`Generator` methods are:
 
 
-   .. method:: flatten(msg, unixfrom=False, linesep='\\n')
+   .. method:: flatten(msg, unixfrom=False, linesep=None)
 
       Print the textual representation of the message object structure rooted at
       *msg* to the output file specified when the :class:`Generator` instance
@@ -72,12 +79,13 @@ Here are the public methods of the :class:`Generator` class, imported from the
       Note that for subparts, no envelope header is ever printed.
 
       Optional *linesep* specifies the line separator character used to
-      terminate lines in the output.  It defaults to ``\n`` because that is
-      the most useful value for Python application code (other library packages
-      expect ``\n`` separated lines).  ``linesep=\r\n`` can be used to
-      generate output with RFC-compliant line separators.
+      terminate lines in the output.  If specified it overrides the value
+      specified by the ``Generator``\'s ``policy``.
 
-      Messages parsed with a Bytes parser that have a
+      Because strings cannot represent non-ASCII bytes, ``Generator`` ignores
+      the value of the :attr:`~email.policy.Policy.must_be_7bit`
+      :mod:`~email.policy` setting and operates as if it were set ``True``.
+      This means that messages parsed with a Bytes parser that have a
       :mailheader:`Content-Transfer-Encoding` of 8bit will be converted to a
       use a 7bit Content-Transfer-Encoding.  Non-ASCII bytes in the headers
       will be :rfc:`2047` encoded with a charset of `unknown-8bit`.
@@ -103,7 +111,8 @@ As a convenience, see the :class:`~email.message.Message` methods
 formatted string representation of a message object.  For more detail, see
 :mod:`email.message`.
 
-.. class:: BytesGenerator(outfp, mangle_from_=True, maxheaderlen=78)
+.. class:: BytesGenerator(outfp, mangle_from_=True, maxheaderlen=78, *, \
+                          policy=policy.default)
 
    The constructor for the :class:`BytesGenerator` class takes a binary
    :term:`file-like object` called *outfp* for an argument.  *outfp* must
@@ -125,19 +134,31 @@ formatted string representation of a message object.  For more detail, see
    wrapping.  The default is 78, as recommended (but not required) by
    :rfc:`2822`.
 
+   The *policy* keyword specifies a :mod:`~email.policy` object that controls a
+   number of aspects of the generator's operation.  The default policy
+   maintains backward compatibility.
+
+   .. versionchanged:: 3.3 Added the *policy* keyword.
+
    The other public :class:`BytesGenerator` methods are:
 
 
-   .. method:: flatten(msg, unixfrom=False, linesep='\n')
+   .. method:: flatten(msg, unixfrom=False, linesep=None)
 
       Print the textual representation of the message object structure rooted
       at *msg* to the output file specified when the :class:`BytesGenerator`
       instance was created.  Subparts are visited depth-first and the resulting
-      text will be properly MIME encoded.  If the input that created the *msg*
-      contained bytes with the high bit set and those bytes have not been
-      modified, they will be copied faithfully to the output, even if doing so
-      is not strictly RFC compliant.  (To produce strictly RFC compliant
-      output, use the :class:`Generator` class.)
+      text will be properly MIME encoded.  If the :mod:`~email.policy` option
+      :attr:`~email.policy.Policy.must_be_7bit` is ``False`` (the default),
+      then any bytes with the high bit set in the original parsed message that
+      have not been modified will be copied faithfully to the output.  If
+      ``must_be_7bit`` is true, the bytes will be converted as needed using an
+      ASCII content-transfer-encoding.  In particular, RFC-invalid non-ASCII
+      bytes in headers will be encoded using the MIME ``unknown-8bit``
+      character set, thus rendering them RFC-compliant.
+
+      .. XXX: There should be a complementary option that just does the RFC
+         compliance transformation but leaves CTE 8bit parts alone.
 
       Messages parsed with a Bytes parser that have a
       :mailheader:`Content-Transfer-Encoding` of 8bit will be reconstructed
@@ -152,10 +173,8 @@ formatted string representation of a message object.  For more detail, see
       Note that for subparts, no envelope header is ever printed.
 
       Optional *linesep* specifies the line separator character used to
-      terminate lines in the output.  It defaults to ``\n`` because that is
-      the most useful value for Python application code (other library packages
-      expect ``\n`` separated lines).  ``linesep=\r\n`` can be used to
-      generate output with RFC-compliant line separators.
+      terminate lines in the output.  If specified it overrides the value
+      specified by the ``Generator``\ 's ``policy``.
 
    .. method:: clone(fp)
 
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index 77a0b698d1..e70b429b42 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -58,12 +58,18 @@ list of defects that it can find.
 Here is the API for the :class:`FeedParser`:
 
 
-.. class:: FeedParser(_factory=email.message.Message)
+.. class:: FeedParser(_factory=email.message.Message, *, policy=policy.default)
 
    Create a :class:`FeedParser` instance.  Optional *_factory* is a no-argument
    callable that will be called whenever a new message object is needed.  It
    defaults to the :class:`email.message.Message` class.
 
+   The *policy* keyword specifies a :mod:`~email.policy` object that controls a
+   number of aspects of the parser's operation.  The default policy maintains
+   backward compatibility.
+
+   .. versionchanged:: 3.3 Added the *policy* keyword.
+
    .. method:: feed(data)
 
       Feed the :class:`FeedParser` some more data.  *data* should be a string
@@ -94,15 +100,17 @@ Parser class API
 The :class:`Parser` class, imported from the :mod:`email.parser` module,
 provides an API that can be used to parse a message when the complete contents
 of the message are available in a string or file.  The :mod:`email.parser`
-module also provides a second class, called :class:`HeaderParser` which can be
-used if you're only interested in the headers of the message.
-:class:`HeaderParser` can be much faster in these situations, since it does not
-attempt to parse the message body, instead setting the payload to the raw body
-as a string. :class:`HeaderParser` has the same API as the :class:`Parser`
-class.
+module also provides header-only parsers, called :class:`HeaderParser` and
+:class:`BytesHeaderParser`, which can be used if you're only interested in the
+headers of the message.  :class:`HeaderParser` and :class:`BytesHeaderParser`
+can be much faster in these situations, since they do not attempt to parse the
+message body, instead setting the payload to the raw body as a string.  They
+have the same API as the :class:`Parser` and :class:`BytesParser` classes.
 
+.. versionadded:: 3.3 BytesHeaderParser
 
-.. class:: Parser(_class=email.message.Message, strict=None)
+
+.. class:: Parser(_class=email.message.Message, *, policy=policy.default)
 
    The constructor for the :class:`Parser` class takes an optional argument
    *_class*.  This must be a callable factory (such as a function or a class), and
@@ -110,13 +118,13 @@ class.
    :class:`~email.message.Message` (see :mod:`email.message`).  The factory will
    be called without arguments.
 
-   The optional *strict* flag is ignored.
+   The *policy* keyword specifies a :mod:`~email.policy` object that controls a
+   number of aspects of the parser's operation.  The default policy maintains
+   backward compatibility.
 
-   .. deprecated:: 2.4
-      Because the :class:`Parser` class is a backward compatible API wrapper
-      around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is
-      effectively non-strict.  You should simply stop passing a *strict* flag to
-      the :class:`Parser` constructor.
+   .. versionchanged:: 3.3
+      Removed the *strict* argument that was deprecated in 2.4.  Added the
+      *policy* keyword.
 
    The other public :class:`Parser` methods are:
 
@@ -147,12 +155,18 @@ class.
       the entire contents of the file.
 
 
-.. class:: BytesParser(_class=email.message.Message, strict=None)
+.. class:: BytesParser(_class=email.message.Message, *, policy=policy.default)
 
    This class is exactly parallel to :class:`Parser`, but handles bytes input.
    The *_class* and *strict* arguments are interpreted in the same way as for
-   the :class:`Parser` constructor.  *strict* is supported only to make porting
-   code easier; it is deprecated.
+   the :class:`Parser` constructor.
+
+   The *policy* keyword specifies a :mod:`~email.policy` object that
+   controls a number of aspects of the parser's operation.  The default
+   policy maintains backward compatibility.
+
+   .. versionchanged:: 3.3
+      Removed the *strict* argument.  Added the *policy* keyword.
 
    .. method:: parse(fp, headeronly=False)
 
@@ -190,34 +204,48 @@ in the top-level :mod:`email` package namespace.
 
 .. currentmodule:: email
 
-.. function:: message_from_string(s, _class=email.message.Message, strict=None)
+.. function:: message_from_string(s, _class=email.message.Message, *, \
+                                  policy=policy.default)
 
    Return a message object structure from a string.  This is exactly equivalent to
-   ``Parser().parsestr(s)``.  Optional *_class* and *strict* are interpreted as
+   ``Parser().parsestr(s)``.  *_class* and *policy* are interpreted as
    with the :class:`Parser` class constructor.
 
-.. function:: message_from_bytes(s, _class=email.message.Message, strict=None)
+   .. versionchanged:: 3.3
+      Removed the *strict* argument.  Added the *policy* keyword.
+
+.. function:: message_from_bytes(s, _class=email.message.Message, *, \
+                                 policy=policy.default)
 
    Return a message object structure from a byte string.  This is exactly
    equivalent to ``BytesParser().parsebytes(s)``.  Optional *_class* and
    *strict* are interpreted as with the :class:`Parser` class constructor.
 
    .. versionadded:: 3.2
+   .. versionchanged:: 3.3
+      Removed the *strict* argument.  Added the *policy* keyword.
 
-.. function:: message_from_file(fp, _class=email.message.Message, strict=None)
+.. function:: message_from_file(fp, _class=email.message.Message, *, \
+                                policy=policy.default)
 
    Return a message object structure tree from an open :term:`file object`.
-   This is exactly equivalent to ``Parser().parse(fp)``.  Optional *_class*
-   and *strict* are interpreted as with the :class:`Parser` class constructor.
+   This is exactly equivalent to ``Parser().parse(fp)``.  *_class*
+   and *policy* are interpreted as with the :class:`Parser` class constructor.
+
+   .. versionchanged::
+      Removed the *strict* argument.  Added the *policy* keyword.
 
-.. function:: message_from_binary_file(fp, _class=email.message.Message, strict=None)
+.. function:: message_from_binary_file(fp, _class=email.message.Message, *, \
+                                       policy=policy.default)
 
    Return a message object structure tree from an open binary :term:`file
    object`.  This is exactly equivalent to ``BytesParser().parse(fp)``.
-   Optional *_class* and *strict* are interpreted as with the :class:`Parser`
+   *_class* and *policy* are interpreted as with the :class:`Parser`
    class constructor.
 
    .. versionadded:: 3.2
+   .. versionchanged:: 3.3
+      Removed the *strict* argument.  Added the *policy* keyword.
 
 Here's an example of how you might use this at an interactive Python prompt::
 
diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst
new file mode 100644
index 0000000000..157f692267
--- /dev/null
+++ b/Doc/library/email.policy.rst
@@ -0,0 +1,182 @@
+:mod:`email`: Policy Objects
+----------------------------
+
+.. module:: email.policy
+   :synopsis: Controlling the parsing and generating of messages
+
+.. versionadded: 3.3
+
+
+The :mod:`email` package's prime focus is the handling of email messages as
+described by the various email and MIME RFCs.  However, the general format of
+email messages (a block of header fields each consisting of a name followed by
+a colon followed by a value, the whole block followed by a blank line and an
+arbitrary 'body'), is a format that has found utility outside of the realm of
+email.  Some of these uses conform fairly closely to the main RFCs, some do
+not.  And even when working with email, there are times when it is desirable to
+break strict compliance with the RFCs.
+
+Policy objects give the email package the flexibility to handle all these
+disparate use cases.
+
+A :class:`Policy` object encapsulates a set of attributes and methods that
+control the behavior of various components of the email package during use.
+:class:`Policy` instances can be passed to various classes and methods in the
+email package to alter the default behavior.  The settable values and their
+defaults are described below.  The :mod:`policy` module also provides some
+pre-created :class:`Policy` instances.  In addition to a :const:`default`
+instance, there are instances tailored for certain applications.  For example
+there is an :const:`SMTP` :class:`Policy` with defaults appropriate for
+generating output to be sent to an SMTP server.  These are listed `below
+<Policy Instances>`.
+
+In general an application will only need to deal with setting the policy at the
+input and output boundaries.  Once parsed, a message is represented by a
+:class:`~email.message.Message` object, which is designed to be independent of
+the format that the message has "on the wire" when it is received, transmitted,
+or displayed.  Thus, a :class:`Policy` can be specified when parsing a message
+to create a :class:`~email.message.Message`, and again when turning the
+:class:`~email.message.Message` into some other representation.  While often a
+program will use the same :class:`Policy` for both input and output, the two
+can be different.
+
+As an example, the following code could be used to read an email message from a
+file on disk and pass it to the system ``sendmail`` program on a Unix system::
+
+   >>> from email import msg_from_binary_file
+   >>> from email.generator import BytesGenerator
+   >>> import email.policy
+   >>> from subprocess import Popen, PIPE
+   >>> with open('mymsg.txt', 'b') as f:
+   ...     Msg = msg_from_binary_file(f, policy=email.policy.mbox)
+   >>> p = Popen(['sendmail', msg['To'][0].address], stdin=PIPE)
+   >>> g = BytesGenerator(p.stdin, policy=email.policy.SMTP)
+   >>> g.flatten(msg)
+   >>> p.stdin.close()
+   >>> rc = p.wait()
+
+Some email package methods accept a *policy* keyword argument, allowing the
+policy to be overridden for that method.  For example, the following code uses
+the :meth:`email.message.Message.as_string` method of the *msg* object from the
+previous example and re-write it to a file using the native line separators for
+the platform on which it is running::
+
+   >>> import os
+   >>> mypolicy = email.policy.Policy(linesep=os.linesep)
+   >>> with open('converted.txt', 'wb') as f:
+   ...     f.write(msg.as_string(policy=mypolicy))
+
+Policy instances are immutable, but they can be cloned, accepting the same
+keyword arguments as the class constructor and returning a new :class:`Policy`
+instance that is a copy of the original but with the specified attributes
+values changed.  For example, the following creates an SMTP policy that will
+raise any defects detected as errors::
+
+   >>> strict_SMTP = email.policy.SMTP.clone(raise_on_defect=True)
+
+Policy objects can also be combined using the addition operator, producing a
+policy object whose settings are a combination of the non-default values of the
+summed objects::
+
+   >>> strict_SMTP = email.policy.SMTP + email.policy.strict
+
+This operation is not commutative; that is, the order in which the objects are
+added matters.  To illustrate::
+
+   >>> Policy = email.policy.Policy
+   >>> apolicy = Policy(max_line_length=100) + Policy(max_line_length=80)
+   >>> apolicy.max_line_length
+   80
+   >>> apolicy = Policy(max_line_length=80) + Policy(max_line_length=100)
+   >>> apolicy.max_line_length
+   100
+
+
+.. class:: Policy(**kw)
+
+   The valid constructor keyword arguments are any of the attributes listed
+   below.
+
+   .. attribute:: max_line_length
+
+      The maximum length of any line in the serialized output, not counting the
+      end of line character(s).  Default is 78, per :rfc:`5322`.  A value of
+      ``0`` or :const:`None` indicates that no line wrapping should be
+      done at all.
+
+   .. attribute:: linesep
+
+      The string to be used to terminate lines in serialized output.  The
+      default is ``\n`` because that's the internal end-of-line discipline used
+      by Python, though ``\r\n`` is required by the RFCs.  See `Policy
+      Instances`_ for policies that use an RFC conformant linesep.  Setting it
+      to :attr:`os.linesep` may also be useful.
+
+   .. attribute:: must_be_7bit
+
+      If ``True``, data output by a bytes generator is limited to ASCII
+      characters.  If :const:`False` (the default), then bytes with the high
+      bit set are preserved and/or allowed in certain contexts (for example,
+      where possible a content transfer encoding of ``8bit`` will be used).
+      String generators act as if ``must_be_7bit`` is ``True`` regardless of
+      the policy in effect, since a string cannot represent non-ASCII bytes.
+
+   .. attribute:: raise_on_defect
+
+      If :const:`True`, any defects encountered will be raised as errors.  If
+      :const:`False` (the default), defects will be passed to the
+      :meth:`register_defect` method.
+
+   :mod:`Policy` object also have the following methods:
+
+   .. method:: handle_defect(obj, defect)
+
+      *obj* is the object on which to register the defect.  *defect* should be
+      an instance of a  subclass of :class:`~email.errors.Defect`.
+      If :attr:`raise_on_defect`
+      is ``True`` the defect is raised as an exception.  Otherwise *obj* and
+      *defect* are passed to :meth:`register_defect`.  This method is intended
+      to be called by parsers when they encounter defects, and will not be
+      called by code that uses the email library unless that code is
+      implementing an alternate parser.
+
+   .. method:: register_defect(obj, defect)
+
+      *obj* is the object on which to register the defect.  *defect* should be
+      a subclass of :class:`~email.errors.Defect`.  This method is part of the
+      public API so that custom ``Policy`` subclasses can implement alternate
+      handling of defects.  The default implementation calls the ``append``
+      method of the ``defects`` attribute of *obj*.
+
+   .. method:: clone(obj, *kw)
+
+      Return a new :class:`Policy` instance whose attributes have the same
+      values as the current instance, except where those attributes are
+      given new values by the keyword arguments.
+
+
+Policy Instances
+^^^^^^^^^^^^^^^^
+
+The following instances of :class:`Policy` provide defaults suitable for
+specific common application domains.
+
+.. data:: default
+
+   An instance of :class:`Policy` with all defaults unchanged.
+
+.. data:: SMTP
+
+   Output serialized from a message will conform to the email and SMTP
+   RFCs.  The only changed attribute is :attr:`linesep`, which is set to
+   ``\r\n``.
+
+.. data:: HTTP
+
+   Suitable for use when serializing headers for use in HTTP traffic.
+   :attr:`linesep` is set to ``\r\n``, and :attr:`max_line_length` is set to
+   :const:`None` (unlimited).
+
+.. data:: strict
+
+   :attr:`raise_on_defect` is set to :const:`True`.
diff --git a/Doc/library/email.rst b/Doc/library/email.rst
index 4530b9506e..fc206f4db2 100644
--- a/Doc/library/email.rst
+++ b/Doc/library/email.rst
@@ -51,6 +51,7 @@ Contents of the :mod:`email` package documentation:
    email.message.rst
    email.parser.rst
    email.generator.rst
+   email.policy.rst
    email.mime.rst
    email.header.rst
    email.charset.rst
diff --git a/Doc/library/email.util.rst b/Doc/library/email.util.rst
index f7b777a01d..4d96857c83 100644
--- a/Doc/library/email.util.rst
+++ b/Doc/library/email.util.rst
@@ -29,13 +29,20 @@ There are several useful utilities provided in the :mod:`email.utils` module:
    fails, in which case a 2-tuple of ``('', '')`` is returned.
 
 
-.. function:: formataddr(pair)
+.. function:: formataddr(pair, charset='utf-8')
 
    The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname,
    email_address)`` and returns the string value suitable for a :mailheader:`To` or
    :mailheader:`Cc` header.  If the first element of *pair* is false, then the
    second element is returned unmodified.
 
+   Optional *charset* is the character set that will be used in the :rfc:`2047`
+   encoding of the ``realname`` if the ``realname`` contains non-ASCII
+   characters.  Can be an instance of :class:`str` or a
+   :class:`~email.charset.Charset`.  Defaults to ``utf-8``.
+
+   .. versionchanged: 3.3 added the *charset* option
+
 
 .. function:: getaddresses(fieldvalues)
 
diff --git a/Doc/library/faulthandler.rst b/Doc/library/faulthandler.rst
new file mode 100644
index 0000000000..3e75c60a6f
--- /dev/null
+++ b/Doc/library/faulthandler.rst
@@ -0,0 +1,136 @@
+:mod:`faulthandler` --- Dump the Python traceback
+=================================================
+
+.. module:: faulthandler
+   :synopsis: Dump the Python traceback.
+
+This module contains functions to dump Python tracebacks explicitly, on a fault,
+after a timeout, or on a user signal. Call :func:`faulthandler.enable` to
+install fault handlers for the :const:`SIGSEGV`, :const:`SIGFPE`,
+:const:`SIGABRT`, :const:`SIGBUS`, and :const:`SIGILL` signals. You can also
+enable them at startup by setting the :envvar:`PYTHONFAULTHANDLER` environment
+variable or by using :option:`-X` ``faulthandler`` command line option.
+
+The fault handler is compatible with system fault handlers like Apport or the
+Windows fault handler. The module uses an alternative stack for signal handlers
+if the :c:func:`sigaltstack` function is available. This allows it to dump the
+traceback even on a stack overflow.
+
+The fault handler is called on catastrophic cases and therefore can only use
+signal-safe functions (e.g. it cannot allocate memory on the heap). Because of
+this limitation traceback dumping is minimal compared to normal Python
+tracebacks:
+
+* Only ASCII is supported. The ``backslashreplace`` error handler is used on
+  encoding.
+* Each string is limited to 100 characters.
+* Only the filename, the function name and the line number are
+  displayed. (no source code)
+* It is limited to 100 frames and 100 threads.
+
+By default, the Python traceback is written to :data:`sys.stderr`. To see
+tracebacks, applications must be run in the terminal. A log file can
+alternatively be passed to :func:`faulthandler.enable`.
+
+The module is implemented in C, so tracebacks can be dumped on a crash or when
+Python is deadlocked.
+
+.. versionadded:: 3.3
+
+
+Dump the traceback
+------------------
+
+.. function:: dump_traceback(file=sys.stderr, all_threads=True)
+
+   Dump the tracebacks of all threads into *file*. If *all_threads* is
+   ``False``, dump only the current thread.
+
+
+Fault handler state
+-------------------
+
+.. function:: enable(file=sys.stderr, all_threads=True)
+
+   Enable the fault handler: install handlers for the :const:`SIGSEGV`,
+   :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and :const:`SIGILL`
+   signals to dump the Python traceback. If *all_threads* is ``True``,
+   produce tracebacks for every running thread. Otherwise, dump only the current
+   thread.
+
+.. function:: disable()
+
+   Disable the fault handler: uninstall the signal handlers installed by
+   :func:`enable`.
+
+.. function:: is_enabled()
+
+   Check if the fault handler is enabled.
+
+
+Dump the tracebacks after a timeout
+-----------------------------------
+
+.. function:: dump_tracebacks_later(timeout, repeat=False, file=sys.stderr, exit=False)
+
+   Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or
+   every *timeout* seconds if *repeat* is ``True``.  If *exit* is ``True``, call
+   :c:func:`_exit` with status=1 after dumping the tracebacks.  (Note
+   :c:func:`_exit` exits the process immediately, which means it doesn't do any
+   cleanup like flushing file buffers.) If the function is called twice, the new
+   call replaces previous parameters and resets the timeout. The timer has a
+   sub-second resolution.
+
+   This function is implemented using a watchdog thread and therefore is not
+   available if Python is compiled with threads disabled.
+
+.. function:: cancel_dump_tracebacks_later()
+
+   Cancel the last call to :func:`dump_tracebacks_later`.
+
+
+Dump the traceback on a user signal
+-----------------------------------
+
+.. function:: register(signum, file=sys.stderr, all_threads=True)
+
+   Register a user signal: install a handler for the *signum* signal to dump
+   the traceback of all threads, or of the current thread if *all_threads* is
+   ``False``, into *file*.
+
+   Not available on Windows.
+
+.. function:: unregister(signum)
+
+   Unregister a user signal: uninstall the handler of the *signum* signal
+   installed by :func:`register`. Return ``True`` if the signal was registered,
+   ``False`` otherwise.
+
+   Not available on Windows.
+
+
+File descriptor issue
+---------------------
+
+:func:`enable`, :func:`dump_tracebacks_later` and :func:`register` keep the
+file descriptor of their *file* argument. If the file is closed and its file
+descriptor is reused by a new file, or if :func:`os.dup2` is used to replace
+the file descriptor, the traceback will be written into a different file. Call
+these functions again each time that the file is replaced.
+
+
+Example
+-------
+
+Example of a segmentation fault on Linux: ::
+
+    $ python -q -X faulthandler
+    >>> import ctypes
+    >>> ctypes.string_at(0)
+    Fatal Python error: Segmentation fault
+
+    Current thread 0x00007fb899f39700:
+      File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
+      File "<stdin>", line 1 in <module>
+    Segmentation fault
+
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index 5bbef4f233..087e200424 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -40,7 +40,7 @@ Here's a sample session using the :mod:`ftplib` module::
 
 The module defines the following items:
 
-.. class:: FTP(host='', user='', passwd='', acct=''[, timeout])
+.. class:: FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None)
 
    Return a new instance of the :class:`FTP` class.  When *host* is given, the
    method call ``connect(host)`` is made.  When *user* is given, additionally
@@ -48,7 +48,8 @@ The module defines the following items:
    *acct* default to the empty string when not given).  The optional *timeout*
    parameter specifies a timeout in seconds for blocking operations like the
    connection attempt (if is not specified, the global default timeout setting
-   will be used).
+   will be used). *source_address* is a 2-tuple ``(host, port)`` for the socket
+   to bind to as its source address before connecting.
 
    :class:`FTP` class supports the :keyword:`with` statement. Here is a sample
    on how using it:
@@ -68,8 +69,11 @@ The module defines the following items:
    .. versionchanged:: 3.2
       Support for the :keyword:`with` statement was added.
 
+   .. versionchanged:: 3.3
+      *source_address* parameter was added.
 
-.. class:: FTP_TLS(host='', user='', passwd='', acct='', [keyfile[, certfile[, context[, timeout]]]])
+
+.. class:: FTP_TLS(host='', user='', passwd='', acct='', keyfile=None, certfile=None, context=None, timeout=None, source_address=None)
 
    A :class:`FTP` subclass which adds TLS support to FTP as described in
    :rfc:`4217`.
@@ -80,10 +84,15 @@ The module defines the following items:
    private key and certificate chain file name for the SSL connection.
    *context* parameter is a :class:`ssl.SSLContext` object which allows
    bundling SSL configuration options, certificates and private keys into a
-   single (potentially long-lived) structure.
+   single (potentially long-lived) structure. *source_address* is a 2-tuple
+   ``(host, port)`` for the socket to bind to as its source address before
+   connecting.
 
    .. versionadded:: 3.2
 
+   .. versionchanged:: 3.3
+      *source_address* parameter was added.
+
    Here's a sample session using the :class:`FTP_TLS` class:
 
    >>> from ftplib import FTP_TLS
@@ -174,7 +183,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    debugging output, logging each line sent and received on the control connection.
 
 
-.. method:: FTP.connect(host='', port=0[, timeout])
+.. method:: FTP.connect(host='', port=0, timeout=None, source_address=None)
 
    Connect to the given host and port.  The default port number is ``21``, as
    specified by the FTP protocol specification.  It is rarely needed to specify a
@@ -182,10 +191,14 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    instance; it should not be called at all if a host was given when the instance
    was created.  All other methods can only be used after a connection has been
    made.
-
    The optional *timeout* parameter specifies a timeout in seconds for the
    connection attempt. If no *timeout* is passed, the global default timeout
    setting will be used.
+   *source_address* is a 2-tuple ``(host, port)`` for the socket to bind to as
+   its source address before connecting.
+
+   .. versionchanged:: 3.3
+      *source_address* parameter was added.
 
 
 .. method:: FTP.getwelcome()
@@ -241,13 +254,12 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
 
    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`` or ``NLST`` (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``.
+   ``NLST`` retrieves a list of file names.
+   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)
@@ -307,6 +319,20 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    in :meth:`transfercmd`.
 
 
+.. method:: FTP.mlsd(path="", facts=[])
+
+   List a directory in a standardized format by using MLSD command
+   (:rfc:`3659`).  If *path* is omitted the current directory is assumed.
+   *facts* is a list of strings representing the type of information desired
+   (e.g. ``["type", "size", "perm"]``).  Return a generator object yielding a
+   tuple of two elements for every file found in path.  First element is the
+   file name, the second one is a dictionary containing facts about the file
+   name.  Content of this dictionary might be limited by the *facts* argument
+   but server is not guaranteed to return all requested facts.
+
+   .. versionadded:: 3.3
+
+
 .. method:: FTP.nlst(argument[, ...])
 
    Return a list of file names as returned by the ``NLST`` command.  The
@@ -314,6 +340,8 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    directory).  Multiple arguments can be used to pass non-standard options to
    the ``NLST`` command.
 
+   .. deprecated:: 3.3 use :meth:`mlsd` instead.
+
 
 .. method:: FTP.dir(argument[, ...])
 
@@ -324,6 +352,8 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
    as a *callback* function as for :meth:`retrlines`; the default prints to
    ``sys.stdout``.  This method returns ``None``.
 
+   .. deprecated:: 3.3 use :meth:`mlsd` instead.
+
 
 .. method:: FTP.rename(fromname, toname)
 
@@ -396,6 +426,14 @@ FTP_TLS Objects
 
    Set up secure control connection by using TLS or SSL, depending on what specified in :meth:`ssl_version` attribute.
 
+.. method:: FTP_TLS.ccc()
+
+   Revert control channel back to plaintex.  This can be useful to take
+   advantage of firewalls that know how to handle NAT with non-secure FTP
+   without opening fixed ports.
+
+   .. versionadded:: 3.3
+
 .. method:: FTP_TLS.prot_p()
 
    Set up secure data connection.
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
index bcfc4b59c4..b6ab3df022 100644
--- a/Doc/library/getopt.rst
+++ b/Doc/library/getopt.rst
@@ -22,9 +22,6 @@ the special meanings of arguments of the form '``-``' and '``--``').  Long
 options similar to those supported by GNU software may be used as well via an
 optional third argument.
 
-A more convenient, flexible, and powerful alternative is the
-:mod:`optparse` module.
-
 This module provides two functions and an
 exception:
 
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 48a86942fc..a5e08c9d8f 100644
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -72,7 +72,7 @@ The module defines the following items:
 
    :class:`GzipFile` supports the :class:`io.BufferedIOBase` interface,
    including iteration and the :keyword:`with` statement.  Only the
-   :meth:`read1` and :meth:`truncate` methods aren't implemented.
+   :meth:`truncate` method isn't implemented.
 
    :class:`GzipFile` also provides the following method:
 
@@ -94,6 +94,9 @@ The module defines the following items:
    .. versionchanged:: 3.2
       Support for unseekable files was added.
 
+   .. versionchanged:: 3.3
+      The :meth:`io.BufferedIOBase.read1` method is now implemented.
+
 
 .. function:: open(filename, mode='rb', compresslevel=9)
 
diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst
index e3a3a10dd1..b30a661edc 100644
--- a/Doc/library/http.server.rst
+++ b/Doc/library/http.server.rst
@@ -179,19 +179,29 @@ of which this module provides three different variants:
 
    .. method:: send_response(code, message=None)
 
-      Sends a response header and logs the accepted request. The HTTP response
-      line is sent, followed by *Server* and *Date* headers. The values for
-      these two headers are picked up from the :meth:`version_string` and
-      :meth:`date_time_string` methods, respectively.
+      Adds a response header to the headers buffer and logs the accepted
+      request. The HTTP response line is written to the internal buffer,
+      followed by *Server* and *Date* headers. The values for these two headers
+      are picked up from the :meth:`version_string` and
+      :meth:`date_time_string` methods, respectively. If the server does not
+      intend to send any other headers using the :meth:`send_header` method,
+      then :meth:`send_response` should be followed by a :meth:`end_headers`
+      call.
+
+      .. versionchanged:: 3.3
+         Headers are stored to an internal buffer and :meth:`end_headers`
+         needs to be called explicitly.
+
 
    .. method:: send_header(keyword, value)
 
-      Stores the HTTP header to an internal buffer which will be written to the
-      output stream when :meth:`end_headers` method is invoked.
-      *keyword* should specify the header keyword, with *value*
-      specifying its value.
+      Adds the HTTP header to an internal buffer which will be written to the
+      output stream when either :meth:`end_headers` or :meth:`flush_headers` is
+      invoked. *keyword* should specify the header keyword, with *value*
+      specifying its value. Note that, after the send_header calls are done,
+      :meth:`end_headers` MUST BE called in order to complete the operation.
 
-      .. versionchanged:: 3.2 Storing the headers in an internal buffer
+      .. versionchanged:: 3.2 Headers are stored in an internal buffer.
 
 
    .. method:: send_response_only(code, message=None)
@@ -205,10 +215,19 @@ of which this module provides three different variants:
 
    .. method:: end_headers()
 
-      Write the buffered HTTP headers to the output stream and send a blank
-      line, indicating the end of the HTTP headers in the response.
+      Adds a blank line
+      (indicating the end of the HTTP headers in the response)
+      to the headers buffer and calls :meth:`flush_headers()`.
+
+      .. versionchanged:: 3.2
+         The buffered headers are written to the output stream.
+
+   .. method:: flush_headers()
+
+      Finally send the headers to the output stream and flush the internal
+      headers buffer.
 
-      .. versionchanged:: 3.2 Writing the buffered headers to the output stream.
+      .. versionadded:: 3.3
 
    .. method:: log_request(code='-', size='-')
 
diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index 1d92fe5339..592e4b0f4b 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -64,14 +64,21 @@ Three exceptions are defined as attributes of the :class:`IMAP4` class:
 There's also a subclass for secure connections:
 
 
-.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None)
+.. class:: IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None)
 
    This is a subclass derived from :class:`IMAP4` that connects over an SSL
    encrypted socket (to use this class you need a socket module that was compiled
    with SSL support).  If *host* is not specified, ``''`` (the local host) is used.
    If *port* is omitted, the standard IMAP4-over-SSL port (993) is used.  *keyfile*
    and *certfile* are also optional - they can contain a PEM formatted private key
-   and certificate chain file for the SSL connection.
+   and certificate chain file for the SSL connection. *ssl_context* parameter is a
+   :class:`ssl.SSLContext` object which allows bundling SSL configuration
+   options, certificates and private keys into a single (potentially long-lived)
+   structure. Note that the *keyfile*/*certfile* parameters are mutually exclusive with *ssl_context*,
+   a :class:`ValueError` is thrown if *keyfile*/*certfile* is provided along with *ssl_context*.
+
+   .. versionchanged:: 3.3
+      *ssl_context* parameter added.
 
 
 The second subclass allows for connections created by a child process:
diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst
index 757823d9f1..9cdad6ee85 100644
--- a/Doc/library/itertools.rst
+++ b/Doc/library/itertools.rst
@@ -46,7 +46,7 @@ Iterator            Arguments               Results
 ====================    ============================    =================================================   =============================================================
 Iterator                Arguments                       Results                                             Example
 ====================    ============================    =================================================   =============================================================
-:func:`accumulate`      p                               p0, p0+p1, p0+p1+p2, ...                            ``accumulate([1,2,3,4,5]) --> 1 3 6 10 15``
+:func:`accumulate`      p [,func]                       p0, p0+p1, p0+p1+p2, ...                            ``accumulate([1,2,3,4,5]) --> 1 3 6 10 15``
 :func:`chain`           p, q, ...                       p0, p1, ... plast, q0, q1, ...                      ``chain('ABC', 'DEF') --> A B C D E F``
 :func:`compress`        data, selectors                 (d[0] if s[0]), (d[1] if s[1]), ...                 ``compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F``
 :func:`dropwhile`       pred, seq                       seq[n], seq[n+1], starting when pred fails          ``dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1``
@@ -84,23 +84,61 @@ The following module functions all construct and return iterators. Some provide
 streams of infinite length, so they should only be accessed by functions or
 loops that truncate the stream.
 
-.. function:: accumulate(iterable)
+.. function:: accumulate(iterable[, func])
 
     Make an iterator that returns accumulated sums. Elements may be any addable
-    type including :class:`Decimal` or :class:`Fraction`.  Equivalent to::
+    type including :class:`Decimal` or :class:`Fraction`.  If the optional
+    *func* argument is supplied, it should be a function of two arguments
+    and it will be used instead of addition.
 
-        def accumulate(iterable):
+    Equivalent to::
+
+        def accumulate(iterable, func=operator.add):
             'Return running totals'
             # accumulate([1,2,3,4,5]) --> 1 3 6 10 15
+            # accumulate([1,2,3,4,5], operator.mul) --> 1 2 6 24 120
             it = iter(iterable)
             total = next(it)
             yield total
             for element in it:
-                total = total + element
+                total = func(total, element)
                 yield total
 
+    There are a number of uses for the *func* argument.  It can be set to
+    :func:`min` for a running minimum, :func:`max` for a running maximum, or
+    :func:`operator.mul` for a running product.  Amortization tables can be
+    built by accumulating interest and applying payments.  First-order
+    `recurrence relations <http://en.wikipedia.org/wiki/Recurrence_relation>`_
+    can be modeled by supplying the initial value in the iterable and using only
+    the accumulated total in *func* argument::
+
+      >>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
+      >>> list(accumulate(data, operator.mul))     # running product
+      [3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]
+      >>> list(accumulate(data, max))              # running maximum
+      [3, 4, 6, 6, 6, 9, 9, 9, 9, 9]
+
+      # Amortize a 5% loan of 1000 with 4 annual payments of 90
+      >>> cashflows = [1000, -90, -90, -90, -90]
+      >>> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt))
+      [1000, 960.0, 918.0, 873.9000000000001, 827.5950000000001]
+
+      # Chaotic recurrence relation http://en.wikipedia.org/wiki/Logistic_map
+      >>> logistic_map = lambda x, _:  r * x * (1 - x)
+      >>> r = 3.8
+      >>> x0 = 0.4
+      >>> inputs = repeat(x0, 36)     # only the initial value is used
+      >>> [format(x, '.2f') for x in accumulate(inputs, logistic_map)]
+      ['0.40', '0.91', '0.30', '0.81', '0.60', '0.92', '0.29', '0.79', '0.63',
+       '0.88' ,'0.39', '0.90', '0.33', '0.84', '0.52', '0.95', '0.18', '0.57',
+       '0.93', '0.25', '0.71', '0.79', '0.63', '0.88', '0.39', '0.91', '0.32',
+       '0.83', '0.54', '0.95', '0.20', '0.60', '0.91', '0.30', '0.80', '0.60']
+
     .. versionadded:: 3.2
 
+    .. versionchanged:: 3.3
+       Added the optional *func* parameter.
+
 .. function:: chain(*iterables)
 
    Make an iterator that returns elements from the first iterable until it is
diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index 378c07198f..82e396903e 100644
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -452,6 +452,15 @@ supports sending logging messages to a remote or local Unix syslog.
          behaviour) but can be set to ``False`` on a ``SysLogHandler`` instance
          in order for that instance to *not* append the NUL terminator.
 
+      .. versionchanged:: 3.3
+         (See: :issue:`12419`.) In earlier versions, there was no facility for
+         an "ident" or "tag" prefix to identify the source of the message. This
+         can now be specified using a class-level attribute, defaulting to
+         ``""`` to preserve existing behaviour, but which can be overridden on
+         a ``SysLogHandler`` instance in order for that instance to prepend
+         the ident to every message handled. Note that the provided ident must
+         be text, not bytes, and is prepended to the message exactly as is.
+
    .. method:: encodePriority(facility, priority)
 
       Encodes the facility and priority into an integer. You can pass in strings
@@ -853,6 +862,15 @@ possible, while any potentially slow operations (such as sending an email via
       Note that if you don't call this before your application exits, there
       may be some records still left on the queue, which won't be processed.
 
+   .. method:: enqueue_sentinel()
+
+      Writes a sentinel to the queue to tell the listener to quit. This
+      implementation uses ``put_nowait()``.  You may want to override this
+      method if you want to use timeouts or work with custom queue
+      implementations.
+
+      .. versionadded:: 3.3
+
 
 .. seealso::
 
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 20cd57c5ae..68cfa6ed79 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -461,6 +461,19 @@ The useful mapping keys in a :class:`LogRecord` are given in the section on
       want all logging times to be shown in GMT, set the ``converter``
       attribute in the ``Formatter`` class.
 
+      .. versionchanged:: 3.3
+         Previously, the default ISO 8601 format was hard-coded as in this
+         example: ``2010-09-06 22:38:15,292`` where the part before the comma is
+         handled by a strptime format string (``'%Y-%m-%d %H:%M:%S'``), and the
+         part after the comma is a millisecond value. Because strptime does not
+         have a format placeholder for milliseconds, the millisecond value is
+         appended using another format string, ``'%s,%03d'`` – and both of these
+         format strings have been hardcoded into this method. With the change,
+         these strings are defined as class-level attributes which can be
+         overridden at the instance level when desired. The names of the
+         attributes are ``default_time_format`` (for the strptime format string)
+         and ``default_msec_format`` (for appending the millisecond value).
+
    .. method:: formatException(exc_info)
 
       Formats the specified exception information (a standard exception tuple as
@@ -993,12 +1006,27 @@ functions.
    | ``stream``   | Use the specified stream to initialize the  |
    |              | StreamHandler. Note that this argument is   |
    |              | incompatible with 'filename' - if both are  |
-   |              | present, 'stream' is ignored.               |
+   |              | present, a ``ValueError`` is raised.        |
+   +--------------+---------------------------------------------+
+   | ``handlers`` | If specified, this should be an iterable of |
+   |              | already created handlers to add to the root |
+   |              | logger. Any handlers which don't already    |
+   |              | have a formatter set will be assigned the   |
+   |              | default formatter created in this function. |
+   |              | Note that this argument is incompatible     |
+   |              | with 'filename' or 'stream' - if both are   |
+   |              | present, a ``ValueError`` is raised.        |
    +--------------+---------------------------------------------+
 
    .. versionchanged:: 3.2
       The ``style`` argument was added.
 
+   .. versionchanged:: 3.3
+      The ``handlers`` argument was added. Additional checks were added to
+      catch situations where incompatible arguments are specified (e.g.
+      ``handlers`` together with ``stream`` or ``filename``, or ``stream``
+      together with ``filename``).
+
 
 .. function:: shutdown()
 
diff --git a/Doc/library/math.rst b/Doc/library/math.rst
index 98c5b334fc..d68cf1157c 100644
--- a/Doc/library/math.rst
+++ b/Doc/library/math.rst
@@ -184,6 +184,14 @@ Power and logarithmic functions
    result is calculated in a way which is accurate for *x* near zero.
 
 
+.. function:: log2(x)
+
+   Return the base-2 logarithm of *x*. This is usually more accurate than
+   ``log(x, 2)``.
+
+   .. versionadded:: 3.3
+
+
 .. function:: log10(x)
 
    Return the base-10 logarithm of *x*.  This is usually more accurate
diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst
index 7a901c93f7..7708028d97 100644
--- a/Doc/library/mmap.rst
+++ b/Doc/library/mmap.rst
@@ -190,12 +190,16 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
       move will raise a :exc:`TypeError` exception.
 
 
-   .. method:: read(num)
+   .. method:: read([n])
 
-      Return a :class:`bytes` containing up to *num* bytes starting from the
-      current file position; the file position is updated to point after the
-      bytes that were returned.
+      Return a :class:`bytes` containing up to *n* bytes starting from the
+      current file position. If the argument is omitted, *None* or negative,
+      return all bytes from the current file position to the end of the
+      mapping. The file position is updated to point after the bytes that were
+      returned.
 
+      .. versionchanged:: 3.3
+         Argument can be omitted or *None*.
 
    .. method:: read_byte()
 
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 92d5272948..0e220d6c35 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -297,7 +297,7 @@ The :mod:`multiprocessing` package mostly replicates the API of the
 :class:`Process` and exceptions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. class:: Process([group[, target[, name[, args[, kwargs]]]]])
+.. class:: Process([group[, target[, name[, args[, kwargs]]]]], *, daemon=None)
 
    Process objects represent activity that is run in a separate process. The
    :class:`Process` class has equivalents of all the methods of
@@ -312,13 +312,19 @@ The :mod:`multiprocessing` package mostly replicates the API of the
    :sub:`1`,N\ :sub:`2`,...,N\ :sub:`k` is a sequence of integers whose length
    is determined by the *generation* of the process.  *args* is the argument
    tuple for the target invocation.  *kwargs* is a dictionary of keyword
-   arguments for the target invocation.  By default, no arguments are passed to
-   *target*.
+   arguments for the target invocation.  If provided, the keyword-only *daemon* argument
+   sets the process :attr:`daemon` flag to ``True`` or ``False``.  If ``None``
+   (the default), this flag will be inherited from the creating process.
+
+   By default, no arguments are passed to *target*.
 
    If a subclass overrides the constructor, it must make sure it invokes the
    base class constructor (:meth:`Process.__init__`) before doing anything else
    to the process.
 
+   .. versionchanged:: 3.3
+      Added the *daemon* argument.
+
    .. method:: run()
 
       Method representing the process's activity.
@@ -405,6 +411,20 @@ The :mod:`multiprocessing` package mostly replicates the API of the
 
       See :ref:`multiprocessing-auth-keys`.
 
+   .. attribute:: sentinel
+
+      A numeric handle of a system object which will become "ready" when
+      the process ends.
+
+      On Windows, this is an OS handle usable with the ``WaitForSingleObject``
+      and ``WaitForMultipleObjects`` family of API calls.  On Unix, this is
+      a file descriptor usable with primitives from the :mod:`select` module.
+
+      You can use this value if you want to wait on several events at once.
+      Otherwise calling :meth:`join()` is simpler.
+
+      .. versionadded:: 3.3
+
    .. method:: terminate()
 
       Terminate the process.  On Unix this is done using the ``SIGTERM`` signal;
diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst
index ef507e1ff9..19b8cab25a 100644
--- a/Doc/library/nntplib.rst
+++ b/Doc/library/nntplib.rst
@@ -70,10 +70,23 @@ The module itself defines the following classes:
    connecting to an NNTP server on the local machine and intend to call
    reader-specific commands, such as ``group``.  If you get unexpected
    :exc:`NNTPPermanentError`\ s, you might need to set *readermode*.
+   :class:`NNTP` class supports the :keyword:`with` statement to
+   unconditionally consume :exc:`socket.error` exceptions and to close the NNTP
+   connection when done. Here is a sample on how using it:
+
+    >>> from nntplib import NNTP
+    >>> with nntplib.NNTP('news.gmane.org') as n:
+    ...     n.group('gmane.comp.python.committers')
+    ...
+    ('211 1454 1 1454 gmane.comp.python.committers', '1454', '1', '1454', 'gmane.comp.python.committers')
+    >>>
+
 
    .. versionchanged:: 3.2
       *usenetrc* is now False by default.
 
+   .. versionchanged:: 3.3
+      Support for the :keyword:`with` statement was added.
 
 .. class:: NNTP_SSL(host, port=563, user=None, password=None, ssl_context=None, readermode=None, usenetrc=False, [timeout])
 
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index ced4965dda..77a28b4f11 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -219,6 +219,17 @@ process and user.
    Availability: Unix.
 
 
+.. function:: getgrouplist(user, group)
+
+   Return list of group ids that *user* belongs to. If *group* is not in the
+   list, it is included; typically, *group* is specified as the group ID
+   field from the password record for *user*.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: getgroups()
 
    Return list of supplemental group ids associated with the current process.
@@ -286,6 +297,22 @@ process and user.
    .. versionchanged:: 3.2
       Added support for Windows.
 
+.. function:: getpriority(which, who)
+
+   .. index:: single: process; scheduling priority
+
+   Get program scheduling priority. The value *which* is one of
+   :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who*
+   is interpreted relative to *which* (a process identifier for
+   :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a
+   user ID for :const:`PRIO_USER`). A zero value for *who* denotes
+   (respectively) the calling process, the process group of the calling process,
+   or the real user ID of the calling process.
+
+   Availability: Unix
+
+   .. versionadded:: 3.3
+
 .. function:: getresuid()
 
    Return a tuple (ruid, euid, suid) denoting the current process's
@@ -336,6 +363,15 @@ process and user.
 
    .. versionadded:: 3.2
 
+.. data:: PRIO_PROCESS
+          PRIO_PGRP
+          PRIO_USER
+
+   Parameters for :func:`getpriority` and :func:`setpriority` functions.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
 
 .. function:: putenv(key, value)
 
@@ -405,6 +441,25 @@ process and user.
    Availability: Unix.
 
 
+.. function:: setpriority(which, who, priority)
+
+   .. index:: single: process; scheduling priority
+
+   Set program scheduling priority. The value *which* is one of
+   :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who*
+   is interpreted relative to *which* (a process identifier for
+   :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a
+   user ID for :const:`PRIO_USER`). A zero value for *who* denotes
+   (respectively) the calling process, the process group of the calling process,
+   or the real user ID of the calling process.
+   *priority* is a value in the range -20 to 19. The default priority is 0;
+   lower priorities cause more favorable scheduling.
+
+   Availability: Unix
+
+   .. versionadded:: 3.3
+
+
 .. function:: setregid(rgid, egid)
 
    Set the current process's real and effective group ids.
@@ -562,6 +617,21 @@ associated with a :term:`file object` when required.  Note that using the file
 descriptor directly will bypass the file object methods, ignoring aspects such
 as internal buffering of data.
 
+.. data:: AT_SYMLINK_NOFOLLOW
+          AT_EACCESS
+          AT_FDCWD
+          AT_REMOVEDIR
+          AT_SYMLINK_FOLLOW
+          UTIME_NOW
+          UTIME_OMIT
+
+   These parameters are used as flags to the \*at family of functions.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: close(fd)
 
    Close file descriptor *fd*.
@@ -610,6 +680,19 @@ as internal buffering of data.
    Availability: Unix, Windows.
 
 
+.. function:: faccessat(dirfd, path, mode, flags=0)
+
+   Like :func:`access` but if *path* is relative, it is taken as relative to *dirfd*.
+   *flags* is optional and can be constructed by ORing together zero or more
+   of these values: :data:`AT_SYMLINK_NOFOLLOW`, :data:`AT_EACCESS`.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: fchmod(fd, mode)
 
    Change the mode of the file given by *fd* to the numeric *mode*.  See the docs
@@ -618,6 +701,18 @@ as internal buffering of data.
    Availability: Unix.
 
 
+.. function:: fchmodat(dirfd, path, mode, flags=0)
+
+   Like :func:`chmod` but if *path* is relative, it is taken as relative to *dirfd*.
+   *flags* is optional and may be 0 or :data:`AT_SYMLINK_NOFOLLOW`.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: fchown(fd, uid, gid)
 
    Change the owner and group id of the file given by *fd* to the numeric *uid*
@@ -626,6 +721,18 @@ as internal buffering of data.
    Availability: Unix.
 
 
+.. function:: fchownat(dirfd, path, uid, gid, flags=0)
+
+   Like :func:`chown` but if *path* is relative, it is taken as relative to *dirfd*.
+   *flags* is optional and may be 0 or :data:`AT_SYMLINK_NOFOLLOW`.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: fdatasync(fd)
 
    Force write of file with filedescriptor *fd* to disk. Does not force update of
@@ -637,6 +744,27 @@ as internal buffering of data.
       This function is not available on MacOS.
 
 
+.. function:: fdlistdir(fd)
+
+   Like :func:`listdir`, but uses a file descriptor instead and always returns
+   strings.  After execution of this function, *fd* will be closed.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: fexecve(fd, args, env)
+
+   Execute the program specified by a file descriptor *fd* with arguments given
+   by *args* and environment given by *env*, replacing the current process.
+   *args* and *env* are given as in :func:`execve`.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: fpathconf(fd, name)
 
    Return system configuration information relevant to an open file. *name*
@@ -661,6 +789,17 @@ as internal buffering of data.
 
    Availability: Unix, Windows.
 
+.. function:: fstatat(dirfd, path, flags=0)
+
+   Like :func:`stat` but if *path* is relative, it is taken as relative to *dirfd*.
+   *flags* is optional and may be 0 or :data:`AT_SYMLINK_NOFOLLOW`.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
 
 .. function:: fstatvfs(fd)
 
@@ -690,6 +829,57 @@ as internal buffering of data.
    Availability: Unix.
 
 
+.. function:: futimesat(dirfd, path, (atime, mtime))
+              futimesat(dirfd, path, None)
+
+   Like :func:`utime` but if *path* is relative, it is taken as relative to *dirfd*.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: futimens(fd, (atime_sec, atime_nsec), (mtime_sec, mtime_nsec))
+              futimens(fd, None, None)
+
+   Updates the timestamps of a file specified by the file descriptor *fd*, with
+   nanosecond precision.
+   The second form sets *atime* and *mtime* to the current time.
+   If *atime_nsec* or *mtime_nsec* is specified as :data:`UTIME_NOW`, the corresponding
+   timestamp is updated to the current time.
+   If *atime_nsec* or *mtime_nsec* is specified as :data:`UTIME_OMIT`, the corresponding
+   timestamp is not updated.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: UTIME_NOW
+          UTIME_OMIT
+
+   Flags used with :func:`futimens` to specify that the timestamp must be
+   updated either to the current time or not updated at all.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: futimes(fd, (atime, mtime))
+              futimes(fd, None)
+
+   Set the access and modified time of the file specified by the file
+   descriptor *fd* to the given values. If the second form is used, set the
+   access and modified times to the current time.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: isatty(fd)
 
    Return ``True`` if the file descriptor *fd* is open and connected to a
@@ -698,6 +888,44 @@ as internal buffering of data.
    Availability: Unix.
 
 
+.. function:: linkat(srcfd, srcpath, dstfd, dstpath, flags=0)
+
+   Like :func:`link` but if *srcpath* is relative, it is taken as relative to *srcfd*
+   and if *dstpath* is relative, it is taken as relative to *dstfd*.
+   *flags* is optional and may be 0 or :data:`AT_SYMLINK_FOLLOW`.
+   If *srcpath* is relative and *srcfd* is the special value :data:`AT_FDCWD`, then
+   *srcpath* is interpreted relative to the current working directory. This
+   also applies for *dstpath*.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: lockf(fd, cmd, len)
+
+   Apply, test or remove a POSIX lock on an open file descriptor.
+   *fd* is an open file descriptor.
+   *cmd* specifies the command to use - one of :data:`F_LOCK`, :data:`F_TLOCK`,
+   :data:`F_ULOCK` or :data:`F_TEST`.
+   *len* specifies the section of the file to lock.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: F_LOCK
+          F_TLOCK
+          F_ULOCK
+          F_TEST
+
+   Flags that specify what action :func:`lockf` will take.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
 .. function:: lseek(fd, pos, how)
 
    Set the current position of file descriptor *fd* to position *pos*, modified
@@ -717,6 +945,39 @@ as internal buffering of data.
    respectively. Availability: Windows, Unix.
 
 
+.. function:: mkdirat(dirfd, path, mode=0o777)
+
+   Like :func:`mkdir` but if *path* is relative, it is taken as relative to *dirfd*.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: mkfifoat(dirfd, path, mode=0o666)
+
+   Like :func:`mkfifo` but if *path* is relative, it is taken as relative to *dirfd*.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: mknodat(dirfd, path, mode=0o600, device=0)
+
+   Like :func:`mknod` but if *path* is relative, it is taken as relative to *dirfd*.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: open(file, flags[, mode])
 
    Open the file *file* and set various flags according to *flags* and possibly
@@ -739,6 +1000,17 @@ as internal buffering of data.
       wrap a file descriptor in a file object, use :func:`fdopen`.
 
 
+.. function:: openat(dirfd, path, flags, mode=0o777)
+
+   Like :func:`open` but if *path* is relative, it is taken as relative to *dirfd*.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: openpty()
 
    .. index:: module: pty
@@ -758,6 +1030,79 @@ as internal buffering of data.
    Availability: Unix, Windows.
 
 
+.. function:: pipe2(flags)
+
+   Create a pipe with *flags* set atomically.
+   *flags* can be constructed by ORing together one or more of these values:
+   :data:`O_NONBLOCK`, :data:`O_CLOEXEC`.
+   Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
+   respectively.
+
+   Availability: some flavors of Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: posix_fallocate(fd, offset, len)
+
+   Ensures that enough disk space is allocated for the file specified by *fd*
+   starting from *offset* and continuing for *len* bytes.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: posix_fadvise(fd, offset, len, advice)
+
+   Announces an intention to access data in a specific pattern thus allowing
+   the kernel to make optimizations.
+   The advice applies to the region of the file specified by *fd* starting at
+   *offset* and continuing for *len* bytes.
+   *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`,
+   :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
+   :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: POSIX_FADV_NORMAL
+          POSIX_FADV_SEQUENTIAL
+          POSIX_FADV_RANDOM
+          POSIX_FADV_NOREUSE
+          POSIX_FADV_WILLNEED
+          POSIX_FADV_DONTNEED
+
+   Flags that can be used in *advice* in :func:`posix_fadvise` that specify
+   the access pattern that is likely to be used.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: pread(fd, buffersize, offset)
+
+   Read from a file descriptor, *fd*, at a position of *offset*. It will read up
+   to *buffersize* number of bytes. The file offset remains unchanged.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: pwrite(fd, string, offset)
+
+   Write *string* to a file descriptor, *fd*, from *offset*, leaving the file
+   offset unchanged.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: read(fd, n)
 
    Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
@@ -775,6 +1120,93 @@ as internal buffering of data.
       :meth:`~file.readline` methods.
 
 
+.. function:: sendfile(out, in, offset, nbytes)
+              sendfile(out, in, offset, nbytes, headers=None, trailers=None, flags=0)
+
+   Copy *nbytes* bytes from file descriptor *in* to file descriptor *out*
+   starting at *offset*.
+   Return the number of bytes sent. When EOF is reached return 0.
+
+   The first function notation is supported by all platforms that define
+   :func:`sendfile`.
+
+   On Linux, if *offset* is given as ``None``, the bytes are read from the
+   current position of *in* and the position of *in* is updated.
+
+   The second case may be used on Mac OS X and FreeBSD where *headers* and
+   *trailers* are arbitrary sequences of buffers that are written before and
+   after the data from *in* is written. It returns the same as the first case.
+
+   On Mac OS X and FreeBSD, a value of 0 for *nbytes* specifies to send until
+   the end of *in* is reached.
+
+   On Solaris, *out* may be the file descriptor of a regular file or the file
+   descriptor of a socket. On all other platforms, *out* must be the file
+   descriptor of an open socket.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: SF_NODISKIO
+          SF_MNOWAIT
+          SF_SYNC
+
+   Parameters to the :func:`sendfile` function, if the implementation supports
+   them.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: readlinkat(dirfd, path)
+
+   Like :func:`readlink` but if *path* is relative, it is taken as relative to *dirfd*.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: renameat(olddirfd, oldpath, newdirfd, newpath)
+
+   Like :func:`rename` but if *oldpath* is relative, it is taken as relative to
+   *olddirfd* and if *newpath* is relative, it is taken as relative to *newdirfd*.
+   If *oldpath* is relative and *olddirfd* is the special value :data:`AT_FDCWD`, then
+   *oldpath* is interpreted relative to the current working directory. This
+   also applies for *newpath*.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: symlinkat(src, dstfd, dst)
+
+   Like :func:`symlink` but if *dst* is relative, it is taken as relative to *dstfd*.
+   If *dst* is relative and *dstfd* is the special value :data:`AT_FDCWD`, then *dst*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: readv(fd, buffers)
+
+   Read from a file descriptor into a number of writable buffers. *buffers* is
+   an arbitrary sequence of writable buffers. Returns the total number of bytes
+   read.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: tcgetpgrp(fd)
 
    Return the process group associated with the terminal given by *fd* (an open
@@ -800,6 +1232,38 @@ as internal buffering of data.
    Availability: Unix.
 
 
+.. function:: unlinkat(dirfd, path, flags=0)
+
+   Like :func:`unlink` but if *path* is relative, it is taken as relative to *dirfd*.
+   *flags* is optional and may be 0 or :data:`AT_REMOVEDIR`. If :data:`AT_REMOVEDIR` is
+   specified, :func:`unlinkat` behaves like :func:`rmdir`.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: utimensat(dirfd, path, (atime_sec, atime_nsec), (mtime_sec, mtime_nsec), flags)
+              utimensat(dirfd, path, None, None, flags)
+
+   Updates the timestamps of a file with nanosecond precision.
+   The second form sets *atime* and *mtime* to the current time.
+   If *atime_nsec* or *mtime_nsec* is specified as :data:`UTIME_NOW`, the corresponding
+   timestamp is updated to the current time.
+   If *atime_nsec* or *mtime_nsec* is specified as :data:`UTIME_OMIT`, the corresponding
+   timestamp is not updated.
+   If *path* is relative, it is taken as relative to *dirfd*.
+   *flags* is optional and may be 0 or :data:`AT_SYMLINK_NOFOLLOW`.
+   If *path* is relative and *dirfd* is the special value :data:`AT_FDCWD`, then *path*
+   is interpreted relative to the current working directory.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: write(fd, str)
 
    Write the bytestring in *str* to file descriptor *fd*. Return the number of
@@ -816,6 +1280,17 @@ as internal buffering of data.
       :meth:`~file.write` method.
 
 
+.. function:: writev(fd, buffers)
+
+   Write the the contents of *buffers* to file descriptor *fd*, where *buffers*
+   is an arbitrary sequence of buffers.
+   Returns the total number of bytes written.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. _open-constants:
 
 ``open()`` flag constants
@@ -847,6 +1322,7 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window
           O_NOCTTY
           O_SHLOCK
           O_EXLOCK
+          O_CLOEXEC
 
    These constants are only available on Unix.
 
@@ -1110,6 +1586,17 @@ Files and Directories
       Added support for Windows 6.0 (Vista) symbolic links.
 
 
+.. function:: lutimes(path, (atime, mtime))
+              lutimes(path, None)
+
+   Like :func:`utime`, but if *path* is a symbolic link, it is not
+   dereferenced.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: mkfifo(path[, mode])
 
    Create a FIFO (a named pipe) named *path* with numeric mode *mode*.  The
@@ -1454,6 +1941,25 @@ Files and Directories
       Added support for Windows 6.0 (Vista) symbolic links.
 
 
+.. function:: sync()
+
+   Force write of everything to disk.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: truncate(path, length)
+
+   Truncate the file corresponding to *path*, so that it is at most
+   *length* bytes in size.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. function:: unlink(path)
 
    Remove (delete) the file *path*.  This is the same function as
@@ -1825,6 +2331,8 @@ written in Python, such as a mail server's external command delivery program.
    will be set to *sig*. The Windows version of :func:`kill` additionally takes
    process handles to be killed.
 
+   See also :func:`signal.pthread_kill`.
+
    .. versionadded:: 3.2
       Windows support.
 
@@ -2033,6 +2541,58 @@ written in Python, such as a mail server's external command delivery program.
 
    Availability: Unix.
 
+.. function:: waitid(idtype, id, options)
+
+   Wait for the completion of one or more child processes.
+   *idtype* can be :data:`P_PID`, :data:`P_PGID` or :data:`P_ALL`.
+   *id* specifies the pid to wait on.
+   *options* is constructed from the ORing of one or more of :data:`WEXITED`,
+   :data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with
+   :data:`WNOHANG` or :data:`WNOWAIT`. The return value is an object
+   representing the data contained in the :c:type:`siginfo_t` structure, namely:
+   :attr:`si_pid`, :attr:`si_uid`, :attr:`si_signo`, :attr:`si_status`,
+   :attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no
+   children in a waitable state.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+.. data:: P_PID
+          P_PGID
+          P_ALL
+
+   These are the possible values for *idtype* in :func:`waitid`. They affect
+   how *id* is interpreted.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+.. data:: WEXITED
+          WSTOPPED
+          WNOWAIT
+
+   Flags that can be used in *options* in :func:`waitid` that specify what
+   child signal to wait for.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: CLD_EXITED
+          CLD_DUMPED
+          CLD_TRAPPED
+          CLD_CONTINUED
+
+   These are the possible values for :attr:`si_code` in the result returned by
+   :func:`waitid`.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
 
 .. function:: waitpid(pid, options)
 
diff --git a/Doc/library/packaging-misc.rst b/Doc/library/packaging-misc.rst
new file mode 100644
index 0000000000..5e562473e2
--- /dev/null
+++ b/Doc/library/packaging-misc.rst
@@ -0,0 +1,27 @@
+.. temporary file for modules that don't need a dedicated file yet
+
+:mod:`packaging.errors` --- Packaging exceptions
+================================================
+
+.. module:: packaging.errors
+   :synopsis: Packaging exceptions.
+
+
+Provides exceptions used by the Packaging modules.  Note that Packaging modules
+may raise standard exceptions; in particular, SystemExit is usually raised for
+errors that are obviously the end-user's fault (e.g. bad command-line arguments).
+
+This module is safe to use in ``from ... import *`` mode; it only exports
+symbols whose names start with ``Packaging`` and end with ``Error``.
+
+
+:mod:`packaging.manifest` --- The Manifest class
+================================================
+
+.. module:: packaging.manifest
+   :synopsis: The Manifest class, used for poking about the file system and
+              building lists of files.
+
+
+This module provides the :class:`Manifest` class, used for poking about the
+filesystem and building lists of files.
diff --git a/Doc/library/packaging.command.rst b/Doc/library/packaging.command.rst
new file mode 100644
index 0000000000..98835c0756
--- /dev/null
+++ b/Doc/library/packaging.command.rst
@@ -0,0 +1,111 @@
+:mod:`packaging.command` --- Standard Packaging commands
+========================================================
+
+.. module:: packaging.command
+   :synopsis: Standard packaging commands.
+
+
+This subpackage contains one module for each standard Packaging command, such as
+:command:`build`  or :command:`upload`.  Each command is implemented as a
+separate module, with the command name as the name of the module and of the
+class defined therein.
+
+
+
+:mod:`packaging.command.cmd` --- Abstract base class for Packaging commands
+===========================================================================
+
+.. module:: packaging.command.cmd
+   :synopsis: Abstract base class for commands.
+
+
+This module supplies the abstract base class :class:`Command`.  This class is
+subclassed by the modules in the packaging.command subpackage.
+
+
+.. class:: Command(dist)
+
+   Abstract base class for defining command classes, the "worker bees" of the
+   Packaging.  A useful analogy for command classes is to think of them as
+   subroutines with local variables called *options*.  The options are declared
+   in :meth:`initialize_options` and defined (given their final values) in
+   :meth:`finalize_options`, both of which must be defined by every command
+   class.  The distinction between the two is necessary because option values
+   might come from the outside world (command line, config file, ...), and any
+   options dependent on other options must be computed after these outside
+   influences have been processed --- hence :meth:`finalize_options`.  The body
+   of the subroutine, where it does all its work based on the values of its
+   options, is the :meth:`run` method, which must also be implemented by every
+   command class.
+
+   The class constructor takes a single argument *dist*, a
+   :class:`~packaging.dist.Distribution` instance.
+
+
+Creating a new Packaging command
+--------------------------------
+
+This section outlines the steps to create a new Packaging command.
+
+.. XXX the following paragraph is focused on the stdlib; expand it to document
+   how to write and register a command in third-party projects
+
+A new command lives in a module in the :mod:`packaging.command` package. There
+is a sample template in that directory called :file:`command_template`.  Copy
+this file to a new module with the same name as the new command you're
+implementing.  This module should implement a class with the same name as the
+module (and the command).  So, for instance, to create the command
+``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
+:file:`command_template` to :file:`packaging/command/peel_banana.py`, then edit
+it so that it's implementing the class :class:`peel_banana`, a subclass of
+:class:`Command`.  It must define the following methods:
+
+.. method:: Command.initialize_options()
+
+   Set default values for all the options that this command supports.  Note that
+   these defaults may be overridden by other commands, by the setup script, by
+   config files, or by the command line.  Thus, this is not the place to code
+   dependencies between options; generally, :meth:`initialize_options`
+   implementations are just a bunch of ``self.foo = None`` assignments.
+
+
+.. method:: Command.finalize_options()
+
+   Set final values for all the options that this command supports. This is
+   always called as late as possible, i.e. after any option assignments from the
+   command line or from other commands have been done.  Thus, this is the place
+   to to code option dependencies: if *foo* depends on *bar*, then it is safe to
+   set *foo* from *bar* as long as *foo* still has the same value it was
+   assigned in :meth:`initialize_options`.
+
+
+.. method:: Command.run()
+
+   A command's raison d'etre: carry out the action it exists to perform,
+   controlled by the options initialized in :meth:`initialize_options`,
+   customized by other commands, the setup script, the command line, and config
+   files, and finalized in :meth:`finalize_options`.  All terminal output and
+   filesystem interaction should be done by :meth:`run`.
+
+
+Command classes may define this attribute:
+
+
+.. attribute:: Command.sub_commands
+
+   *sub_commands* formalizes the notion of a "family" of commands,
+   e.g. ``install_dist`` as the parent with sub-commands ``install_lib``,
+   ``install_headers``, etc.  The parent of a family of commands defines
+   *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
+   predicate)``, with *command_name* a string and *predicate* a function, a
+   string or ``None``.  *predicate* is a method of the parent command that
+   determines whether the corresponding command is applicable in the current
+   situation.  (E.g. ``install_headers`` is only applicable if we have any C
+   header files to install.)  If *predicate* is ``None``, that command is always
+   applicable.
+
+   *sub_commands* is usually defined at the *end* of a class, because
+   predicates can be methods of the class, so they must already have been
+   defined.  The canonical example is the :command:`install_dist` command.
+
+.. XXX document how to add a custom command to another one's subcommands
diff --git a/Doc/library/packaging.compiler.rst b/Doc/library/packaging.compiler.rst
new file mode 100644
index 0000000000..cf88685144
--- /dev/null
+++ b/Doc/library/packaging.compiler.rst
@@ -0,0 +1,674 @@
+:mod:`packaging.compiler` --- Compiler classes
+==============================================
+
+.. module:: packaging.compiler
+   :synopsis: Compiler classes to build C/C++ extensions or libraries.
+
+
+This subpackage contains an abstract base class representing a compiler and
+concrete implementations for common compilers.  The compiler classes should not
+be instantiated directly, but created using the :func:`new_compiler` factory
+function.  Compiler types provided by Packaging are listed in
+:ref:`packaging-standard-compilers`.
+
+
+Public functions
+----------------
+
+.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
+
+   Factory function to generate an instance of some
+   :class:`~.ccompiler.CCompiler` subclass for the requested platform or
+   compiler type.
+
+   If no argument is given for *plat* and *compiler*, the default compiler type
+   for the platform (:attr:`os.name`) will be used: ``'unix'`` for Unix and
+   Mac OS X, ``'msvc'`` for Windows.
+
+   If *plat* is given, it must be one of ``'posix'``, ``'darwin'`` or ``'nt'``.
+   An invalid value will not raise an exception but use the default compiler
+   type for the current platform.
+
+   .. XXX errors should never pass silently; this behavior is particularly
+      harmful when a compiler type is given as first argument
+
+   If *compiler* is given, *plat* will be ignored, allowing you to get for
+   example a ``'unix'`` compiler object under Windows or an ``'msvc'`` compiler
+   under Unix.  However, not all compiler types can be instantiated on every
+   platform.
+
+
+.. function:: customize_compiler(compiler)
+
+   Do any platform-specific customization of a CCompiler instance.  Mainly
+   needed on Unix to plug in the information that varies across Unices and is
+   stored in CPython's Makefile.
+
+
+.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
+
+   Generate linker options for searching library directories and linking with
+   specific libraries.  *libraries* and *library_dirs* are, respectively, lists
+   of library names (not filenames!) and search directories.  Returns a list of
+   command-line options suitable for use with some compiler (depending on the
+   two format strings passed in).
+
+
+.. function:: gen_preprocess_options(macros, include_dirs)
+
+   Generate C preprocessor options (:option:`-D`, :option:`-U`, :option:`-I`) as
+   used by at least two types of compilers: the typical Unix compiler and Visual
+   C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
+   means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means
+   define (:option:`-D`) macro *name* to *value*.  *include_dirs* is just a list
+   of directory names to be added to the header file search path (:option:`-I`).
+   Returns a list of command-line options suitable for either Unix compilers or
+   Visual C++.
+
+
+.. function:: get_default_compiler(osname, platform)
+
+   Determine the default compiler to use for the given platform.
+
+   *osname* should be one of the standard Python OS names (i.e. the ones
+   returned by ``os.name``) and *platform* the common value returned by
+   ``sys.platform`` for the platform in question.
+
+   The default values are ``os.name`` and ``sys.platform``.
+
+
+.. function:: set_compiler(location)
+
+   Add or change a compiler
+
+
+.. function:: show_compilers()
+
+   Print list of available compilers (used by the :option:`--help-compiler`
+   options to :command:`build`, :command:`build_ext`, :command:`build_clib`).
+
+
+.. _packaging-standard-compilers:
+
+Standard compilers
+------------------
+
+Concrete subclasses of :class:`~.ccompiler.CCompiler` are provided in submodules
+of the :mod:`packaging.compiler` package.  You do not need to import them, using
+:func:`new_compiler` is the public API to use.  This table documents the
+standard compilers; be aware that they can be replaced by other classes on your
+platform.
+
+=============== ======================================================== =======
+name            description                                              notes
+=============== ======================================================== =======
+``'unix'``      typical Unix-style command-line C compiler               [#]_
+``'msvc'``      Microsoft compiler                                       [#]_
+``'bcpp'``      Borland C++ compiler
+``'cygwin'``    Cygwin compiler (Windows port of GCC)
+``'mingw32'``   Mingw32 port of GCC (same as Cygwin in no-Cygwin mode)
+=============== ======================================================== =======
+
+
+.. [#] The Unix compiler class assumes this behavior:
+
+       * macros defined with :option:`-Dname[=value]`
+
+       * macros undefined with :option:`-Uname`
+
+       * include search directories specified with :option:`-Idir`
+
+       * libraries specified with :option:`-llib`
+
+       * library search directories specified with :option:`-Ldir`
+
+       * compile handled by :program:`cc` (or similar) executable with
+         :option:`-c` option: compiles :file:`.c` to :file:`.o`
+
+       * link static library handled by :program:`ar` command (possibly with
+         :program:`ranlib`)
+
+       * link shared library handled by :program:`cc` :option:`-shared`
+
+
+.. [#] On Windows, extension modules typically need to be compiled with the same
+       compiler that was used to compile CPython (for example Microsoft Visual
+       Studio .NET 2003 for CPython 2.4 and 2.5).  The AMD64 and Itanium
+       binaries are created using the Platform SDK.
+
+       Under the hood, there are actually two different subclasses of
+       :class:`~.ccompiler.CCompiler` defined: one is compatible with MSVC 2005
+       and 2008, the other works with older versions.  This should not be a
+       concern for regular use of the functions in this module.
+
+       Packaging will normally choose the right compiler, linker etc. on its
+       own.  To override this choice, the environment variables
+       *DISTUTILS_USE_SDK* and *MSSdk* must be both set.  *MSSdk* indicates that
+       the current environment has been setup by the SDK's ``SetEnv.Cmd``
+       script, or that the environment variables had been registered when the
+       SDK was installed; *DISTUTILS_USE_SDK* indicates that the user has made
+       an explicit choice to override the compiler selection done by Packaging.
+
+       .. TODO document the envvars in Doc/using and the man page
+
+
+:mod:`packaging.compiler.ccompiler` --- CCompiler base class
+============================================================
+
+.. module:: packaging.compiler.ccompiler
+   :synopsis: Abstract CCompiler class.
+
+
+This module provides the abstract base class for the :class:`CCompiler`
+classes.  A :class:`CCompiler` instance can be used for all the compile and
+link steps needed to build a single project. Methods are provided to set
+options for the compiler --- macro definitions, include directories, link path,
+libraries and the like.
+
+.. class:: CCompiler([verbose=0, dry_run=0, force=0])
+
+   The abstract base class :class:`CCompiler` defines the interface that must be
+   implemented by real compiler classes.  The class also has some utility
+   methods used by several compiler classes.
+
+   The basic idea behind a compiler abstraction class is that each instance can
+   be used for all the compile/link steps in building a single project.  Thus,
+   attributes common to all of those compile and link steps --- include
+   directories, macros to define, libraries to link against, etc. --- are
+   attributes of the compiler instance.  To allow for variability in how
+   individual files are treated, most of those attributes may be varied on a
+   per-compilation or per-link basis.
+
+   The constructor for each subclass creates an instance of the Compiler object.
+   Flags are *verbose* (show verbose output), *dry_run* (don't actually execute
+   the steps) and *force* (rebuild everything, regardless of dependencies).  All
+   of these flags default to ``0`` (off). Note that you probably don't want to
+   instantiate :class:`CCompiler` or one of its subclasses directly - use the
+   :func:`packaging.CCompiler.new_compiler` factory function instead.
+
+   The following methods allow you to manually alter compiler options for the
+   instance of the Compiler class.
+
+
+   .. method:: CCompiler.add_include_dir(dir)
+
+      Add *dir* to the list of directories that will be searched for header
+      files.  The compiler is instructed to search directories in the order in
+      which they are supplied by successive calls to :meth:`add_include_dir`.
+
+
+   .. method:: CCompiler.set_include_dirs(dirs)
+
+      Set the list of directories that will be searched to *dirs* (a list of
+      strings). Overrides any preceding calls to :meth:`add_include_dir`;
+      subsequent calls to :meth:`add_include_dir` add to the list passed to
+      :meth:`set_include_dirs`. This does not affect any list of standard
+      include directories that the compiler may search by default.
+
+
+   .. method:: CCompiler.add_library(libname)
+
+      Add *libname* to the list of libraries that will be included in all links
+      driven by this compiler object.  Note that *libname* should *not* be the
+      name of a file containing a library, but the name of the library itself:
+      the actual filename will be inferred by the linker, the compiler, or the
+      compiler class (depending on the platform).
+
+      The linker will be instructed to link against libraries in the order they
+      were supplied to :meth:`add_library` and/or :meth:`set_libraries`.  It is
+      perfectly valid to duplicate library names; the linker will be instructed
+      to link against libraries as many times as they are mentioned.
+
+
+   .. method:: CCompiler.set_libraries(libnames)
+
+      Set the list of libraries to be included in all links driven by this
+      compiler object to *libnames* (a list of strings).  This does not affect
+      any standard system libraries that the linker may include by default.
+
+
+   .. method:: CCompiler.add_library_dir(dir)
+
+      Add *dir* to the list of directories that will be searched for libraries
+      specified to :meth:`add_library` and :meth:`set_libraries`.  The linker
+      will be instructed to search for libraries in the order they are supplied
+      to :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
+
+
+   .. method:: CCompiler.set_library_dirs(dirs)
+
+      Set the list of library search directories to *dirs* (a list of strings).
+      This does not affect any standard library search path that the linker may
+      search by default.
+
+
+   .. method:: CCompiler.add_runtime_library_dir(dir)
+
+      Add *dir* to the list of directories that will be searched for shared
+      libraries at runtime.
+
+
+   .. method:: CCompiler.set_runtime_library_dirs(dirs)
+
+      Set the list of directories to search for shared libraries at runtime to
+      *dirs* (a list of strings).  This does not affect any standard search path
+      that the runtime linker may search by default.
+
+
+   .. method:: CCompiler.define_macro(name[, value=None])
+
+      Define a preprocessor macro for all compilations driven by this compiler
+      object. The optional parameter *value* should be a string; if it is not
+      supplied, then the macro will be defined without an explicit value and the
+      exact outcome depends on the compiler used (XXX true? does ANSI say
+      anything about this?)
+
+
+   .. method:: CCompiler.undefine_macro(name)
+
+      Undefine a preprocessor macro for all compilations driven by this compiler
+      object.  If the same macro is defined by :meth:`define_macro` and
+      undefined by :meth:`undefine_macro` the last call takes precedence
+      (including multiple redefinitions or undefinitions).  If the macro is
+      redefined/undefined on a per-compilation basis (i.e. in the call to
+      :meth:`compile`), then that takes precedence.
+
+
+   .. method:: CCompiler.add_link_object(object)
+
+      Add *object* to the list of object files (or analogues, such as explicitly
+      named library files or the output of "resource compilers") to be included
+      in every link driven by this compiler object.
+
+
+   .. method:: CCompiler.set_link_objects(objects)
+
+      Set the list of object files (or analogues) to be included in every link
+      to *objects*.  This does not affect any standard object files that the
+      linker may include by default (such as system libraries).
+
+   The following methods implement methods for autodetection of compiler
+   options, providing some functionality similar to GNU :program:`autoconf`.
+
+
+   .. method:: CCompiler.detect_language(sources)
+
+      Detect the language of a given file, or list of files. Uses the instance
+      attributes :attr:`language_map` (a dictionary), and :attr:`language_order`
+      (a list) to do the job.
+
+
+   .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
+
+      Search the specified list of directories for a static or shared library file
+      *lib* and return the full path to that file.  If *debug* is true, look for a
+      debugging version (if that makes sense on the current platform).  Return
+      ``None`` if *lib* wasn't found in any of the specified directories.
+
+
+   .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
+
+      Return a boolean indicating whether *funcname* is supported on the current
+      platform.  The optional arguments can be used to augment the compilation
+      environment by providing additional include files and paths and libraries and
+      paths.
+
+
+   .. method:: CCompiler.library_dir_option(dir)
+
+      Return the compiler option to add *dir* to the list of directories searched for
+      libraries.
+
+
+   .. method:: CCompiler.library_option(lib)
+
+      Return the compiler option to add *dir* to the list of libraries linked into the
+      shared library or executable.
+
+
+   .. method:: CCompiler.runtime_library_dir_option(dir)
+
+      Return the compiler option to add *dir* to the list of directories searched for
+      runtime libraries.
+
+
+   .. method:: CCompiler.set_executables(**args)
+
+      Define the executables (and options for them) that will be run to perform the
+      various stages of compilation.  The exact set of executables that may be
+      specified here depends on the compiler class (via the 'executables' class
+      attribute), but most will have:
+
+      +--------------+------------------------------------------+
+      | attribute    | description                              |
+      +==============+==========================================+
+      | *compiler*   | the C/C++ compiler                       |
+      +--------------+------------------------------------------+
+      | *linker_so*  | linker used to create shared objects and |
+      |              | libraries                                |
+      +--------------+------------------------------------------+
+      | *linker_exe* | linker used to create binary executables |
+      +--------------+------------------------------------------+
+      | *archiver*   | static library creator                   |
+      +--------------+------------------------------------------+
+
+      On platforms with a command line (Unix, DOS/Windows), each of these is a string
+      that will be split into executable name and (optional) list of arguments.
+      (Splitting the string is done similarly to how Unix shells operate: words are
+      delimited by spaces, but quotes and backslashes can override this.  See
+      :func:`packaging.util.split_quoted`.)
+
+   The following methods invoke stages in the build process.
+
+
+   .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
+
+      Compile one or more source files. Generates object files (e.g. transforms a
+      :file:`.c` file to a :file:`.o` file.)
+
+      *sources* must be a list of filenames, most likely C/C++ files, but in reality
+      anything that can be handled by a particular compiler and compiler class (e.g.
+      an ``'msvc'`` compiler` can handle resource files in *sources*).  Return a list of
+      object filenames, one per source filename in *sources*.  Depending on the
+      implementation, not all source files will necessarily be compiled, but all
+      corresponding object filenames will be returned.
+
+      If *output_dir* is given, object files will be put under it, while retaining
+      their original path component.  That is, :file:`foo/bar.c` normally compiles to
+      :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
+      it would compile to :file:`build/foo/bar.o`.
+
+      *macros*, if given, must be a list of macro definitions.  A macro definition is
+      either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
+      a macro; if the value is ``None``, the macro is defined without an explicit
+      value.  The 1-tuple case undefines a macro.  Later
+      definitions/redefinitions/undefinitions take precedence.
+
+      *include_dirs*, if given, must be a list of strings, the directories to add to
+      the default include file search path for this compilation only.
+
+      *debug* is a boolean; if true, the compiler will be instructed to output debug
+      symbols in (or alongside) the object file(s).
+
+      *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
+      that have the notion of a command line (e.g. Unix, DOS/Windows), they are most
+      likely lists of strings: extra command-line arguments to prepend/append to the
+      compiler command line.  On other platforms, consult the implementation class
+      documentation.  In any event, they are intended as an escape hatch for those
+      occasions when the abstract compiler framework doesn't cut the mustard.
+
+      *depends*, if given, is a list of filenames that all targets depend on.  If a
+      source file is older than any file in depends, then the source file will be
+      recompiled.  This supports dependency tracking, but only at a coarse
+      granularity.
+
+      Raises :exc:`CompileError` on failure.
+
+
+   .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
+
+      Link a bunch of stuff together to create a static library file. The "bunch of
+      stuff" consists of the list of object files supplied as *objects*, the extra
+      object files supplied to :meth:`add_link_object` and/or
+      :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
+      :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
+
+      *output_libname* should be a library name, not a filename; the filename will be
+      inferred from the library name.  *output_dir* is the directory where the library
+      file will be put. XXX defaults to what?
+
+      *debug* is a boolean; if true, debugging information will be included in the
+      library (note that on most platforms, it is the compile step where this matters:
+      the *debug* flag is included here just for consistency).
+
+      *target_lang* is the target language for which the given objects are being
+      compiled. This allows specific linkage time treatment of certain languages.
+
+      Raises :exc:`LibError` on failure.
+
+
+   .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
+
+      Link a bunch of stuff together to create an executable or shared library file.
+
+      The "bunch of stuff" consists of the list of object files supplied as *objects*.
+      *output_filename* should be a filename.  If *output_dir* is supplied,
+      *output_filename* is relative to it (i.e. *output_filename* can provide
+      directory components if needed).
+
+      *libraries* is a list of libraries to link against.  These are library names,
+      not filenames, since they're translated into filenames in a platform-specific
+      way (e.g. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
+      DOS/Windows).  However, they can include a directory component, which means the
+      linker will look in that specific directory rather than searching all the normal
+      locations.
+
+      *library_dirs*, if supplied, should be a list of directories to search for
+      libraries that were specified as bare library names (i.e. no directory
+      component).  These are on top of the system default and those supplied to
+      :meth:`add_library_dir` and/or :meth:`set_library_dirs`.  *runtime_library_dirs*
+      is a list of directories that will be embedded into the shared library and used
+      to search for other shared libraries that \*it\* depends on at run-time.  (This
+      may only be relevant on Unix.)
+
+      *export_symbols* is a list of symbols that the shared library will export.
+      (This appears to be relevant only on Windows.)
+
+      *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
+      slight distinction that it actually matters on most platforms (as opposed to
+      :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
+      sake).
+
+      *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
+      course that they supply command-line arguments for the particular linker being
+      used).
+
+      *target_lang* is the target language for which the given objects are being
+      compiled. This allows specific linkage time treatment of certain languages.
+
+      Raises :exc:`LinkError` on failure.
+
+
+   .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
+
+      Link an executable.  *output_progname* is the name of the file executable, while
+      *objects* are a list of object filenames to link in. Other arguments are as for
+      the :meth:`link` method.
+
+
+   .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
+
+      Link a shared library. *output_libname* is the name of the output library,
+      while *objects* is a list of object filenames to link in. Other arguments are
+      as for the :meth:`link` method.
+
+
+   .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
+
+      Link a shared object. *output_filename* is the name of the shared object that
+      will be created, while *objects* is a list of object filenames to link in.
+      Other arguments are as for the :meth:`link` method.
+
+
+   .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
+
+      Preprocess a single C/C++ source file, named in *source*. Output will be written
+      to file named *output_file*, or *stdout* if *output_file* not supplied.
+      *macros* is a list of macro definitions as for :meth:`compile`, which will
+      augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
+      *include_dirs* is a list of directory names that will be added to the default
+      list, in the same way as :meth:`add_include_dir`.
+
+      Raises :exc:`PreprocessError` on failure.
+
+   The following utility methods are defined by the :class:`CCompiler` class, for
+   use by the various concrete subclasses.
+
+
+   .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
+
+      Returns the filename of the executable for the given *basename*.  Typically for
+      non-Windows platforms this is the same as the basename, while Windows will get
+      a :file:`.exe` added.
+
+
+   .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
+
+      Returns the filename for the given library name on the current platform. On Unix
+      a library with *lib_type* of ``'static'`` will typically be of the form
+      :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
+      :file:`liblibname.so`.
+
+
+   .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
+
+      Returns the name of the object files for the given source files.
+      *source_filenames* should be a list of filenames.
+
+
+   .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
+
+      Returns the name of a shared object file for the given file name *basename*.
+
+
+   .. method:: CCompiler.execute(func, args[, msg=None, level=1])
+
+      Invokes :func:`packaging.util.execute` This method invokes a Python function
+      *func* with the given arguments *args*, after logging and taking into account
+      the *dry_run* flag. XXX see also.
+
+
+   .. method:: CCompiler.spawn(cmd)
+
+      Invokes :func:`packaging.util.spawn`. This invokes an external process to run
+      the given command. XXX see also.
+
+
+   .. method:: CCompiler.mkpath(name[, mode=511])
+
+      Invokes :func:`packaging.dir_util.mkpath`. This creates a directory and any
+      missing ancestor directories. XXX see also.
+
+
+   .. method:: CCompiler.move_file(src, dst)
+
+      Invokes :meth:`packaging.file_util.move_file`. Renames *src* to *dst*.  XXX see
+      also.
+
+
+:mod:`packaging.compiler.extension` --- The Extension class
+===========================================================
+
+.. module:: packaging.compiler.extension
+   :synopsis: Class used to represent C/C++ extension modules.
+
+
+This module provides the :class:`Extension` class, used to represent C/C++
+extension modules.
+
+.. class:: Extension
+
+   The Extension class describes a single C or C++ extension module.  It accepts
+   the following keyword arguments in its constructor:
+
+   +------------------------+--------------------------------+---------------------------+
+   | argument name          | value                          | type [#]_                 |
+   +========================+================================+===========================+
+   | *name*                 | the full name of the           | string                    |
+   |                        | extension, including any       |                           |
+   |                        | packages --- i.e. *not* a      |                           |
+   |                        | filename or pathname, but      |                           |
+   |                        | Python dotted name             |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *sources*              | list of source filenames,      | string                    |
+   |                        | relative to the distribution   |                           |
+   |                        | root (where the setup script   |                           |
+   |                        | lives), in Unix form (slash-   |                           |
+   |                        | separated) for portability.    |                           |
+   |                        | Source files may be C, C++,    |                           |
+   |                        | SWIG (.i), platform-specific   |                           |
+   |                        | resource files, or whatever    |                           |
+   |                        | else is recognized by the      |                           |
+   |                        | :command:`build_ext` command   |                           |
+   |                        | as source for a Python         |                           |
+   |                        | extension.                     |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *include_dirs*         | list of directories to search  | string                    |
+   |                        | for C/C++ header files (in     |                           |
+   |                        | Unix form for portability)     |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *define_macros*        | list of macros to define; each | (string, string) tuple or |
+   |                        | macro is defined using a       | (name, ``None``)          |
+   |                        | 2-tuple ``(name, value)``,     |                           |
+   |                        | where *value* is               |                           |
+   |                        | either the string to define it |                           |
+   |                        | to or ``None`` to define it    |                           |
+   |                        | without a particular value     |                           |
+   |                        | (equivalent of ``#define FOO`` |                           |
+   |                        | in source or :option:`-DFOO`   |                           |
+   |                        | on Unix C compiler command     |                           |
+   |                        | line)                          |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *undef_macros*         | list of macros to undefine     | string                    |
+   |                        | explicitly                     |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *library_dirs*         | list of directories to search  | string                    |
+   |                        | for C/C++ libraries at link    |                           |
+   |                        | time                           |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *libraries*            | list of library names (not     | string                    |
+   |                        | filenames or paths) to link    |                           |
+   |                        | against                        |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *runtime_library_dirs* | list of directories to search  | string                    |
+   |                        | for C/C++ libraries at run     |                           |
+   |                        | time (for shared extensions,   |                           |
+   |                        | this is when the extension is  |                           |
+   |                        | loaded)                        |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *extra_objects*        | list of extra files to link    | string                    |
+   |                        | with (e.g. object files not    |                           |
+   |                        | implied by 'sources', static   |                           |
+   |                        | library that must be           |                           |
+   |                        | explicitly specified, binary   |                           |
+   |                        | resource files, etc.)          |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *extra_compile_args*   | any extra platform- and        | string                    |
+   |                        | compiler-specific information  |                           |
+   |                        | to use when compiling the      |                           |
+   |                        | source files in 'sources'. For |                           |
+   |                        | platforms and compilers where  |                           |
+   |                        | a command line makes sense,    |                           |
+   |                        | this is typically a list of    |                           |
+   |                        | command-line arguments, but    |                           |
+   |                        | for other platforms it could   |                           |
+   |                        | be anything.                   |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *extra_link_args*      | any extra platform- and        | string                    |
+   |                        | compiler-specific information  |                           |
+   |                        | to use when linking object     |                           |
+   |                        | files together to create the   |                           |
+   |                        | extension (or to create a new  |                           |
+   |                        | static Python interpreter).    |                           |
+   |                        | Similar interpretation as for  |                           |
+   |                        | 'extra_compile_args'.          |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *export_symbols*       | list of symbols to be exported | string                    |
+   |                        | from a shared extension. Not   |                           |
+   |                        | used on all platforms, and not |                           |
+   |                        | generally necessary for Python |                           |
+   |                        | extensions, which typically    |                           |
+   |                        | export exactly one symbol:     |                           |
+   |                        | ``init`` + extension_name.     |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *depends*              | list of files that the         | string                    |
+   |                        | extension depends on           |                           |
+   +------------------------+--------------------------------+---------------------------+
+   | *language*             | extension language (i.e.       | string                    |
+   |                        | ``'c'``, ``'c++'``,            |                           |
+   |                        | ``'objc'``). Will be detected  |                           |
+   |                        | from the source extensions if  |                           |
+   |                        | not provided.                  |                           |
+   +------------------------+--------------------------------+---------------------------+
+
+.. [#] For values documented as lists, the given type is the type of each element.
diff --git a/Doc/library/packaging.database.rst b/Doc/library/packaging.database.rst
new file mode 100644
index 0000000000..2a8c39f92c
--- /dev/null
+++ b/Doc/library/packaging.database.rst
@@ -0,0 +1,324 @@
+:mod:`packaging.database` --- Database of installed distributions
+=================================================================
+
+.. module:: packaging.database
+   :synopsis: Functions to query and manipulate installed distributions.
+
+
+This module provides an implementation of :PEP:`376`.  It was originally
+intended to land in :mod:`pkgutil`, but with the inclusion of Packaging in the
+standard library, it was thought best to include it in a submodule of
+:mod:`packaging`, leaving :mod:`pkgutil` to deal with imports.
+
+Installed Python distributions are represented by instances of
+:class:`Distribution`, or :class:`EggInfoDistribution` for legacy egg formats.
+Most functions also provide an extra argument ``use_egg_info`` to take legacy
+distributions into account.
+
+
+Classes representing installed distributions
+--------------------------------------------
+
+.. class:: Distribution(path)
+
+   Class representing an installed distribution.  It is different from
+   :class:`packaging.dist.Distribution` which holds the list of files, the
+   metadata and options during the run of a Packaging command.
+
+   Instantiate with the *path* to a ``.dist-info`` directory.  Instances can be
+   compared and sorted.  Other available methods are:
+
+   .. XXX describe how comparison works
+
+   .. method:: get_distinfo_file(path, binary=False)
+
+      Return a read-only file object for a file located at
+      :file:`{project-version}.dist-info/path}`.  *path* should be a
+      ``'/'``-separated path relative to the ``.dist-info`` directory or an
+      absolute path; if it is an absolute path and doesn't start with the path
+      to the :file:`.dist-info` directory, a :class:`PackagingError` is raised.
+
+      If *binary* is ``True``, the file is opened in binary mode.
+
+   .. method:: get_resource_path(relative_path)
+
+      .. TODO
+
+   .. method:: list_distinfo_files(local=False)
+
+      Return an iterator over all files located in the :file:`.dist-info`
+      directory.  If *local* is ``True``, each returned path is transformed into
+      a local absolute path, otherwise the raw value found in the :file:`RECORD`
+      file is returned.
+
+   .. method::  list_installed_files(local=False)
+
+      Iterate over the files installed with the distribution and registered in
+      the :file:`RECORD` file and yield a tuple ``(path, md5, size)`` for each
+      line.  If *local* is ``True``, the returned path is transformed into a
+      local absolute path, otherwise the raw value is returned.
+
+      A local absolute path is an absolute path in which occurrences of ``'/'``
+      have been replaced by :data:`os.sep`.
+
+   .. method:: uses(path)
+
+      Check whether *path* was installed by this distribution (i.e. if the path
+      is present in the :file:`RECORD` file).  *path* can be a local absolute
+      path or a relative ``'/'``-separated path.  Returns a boolean.
+
+   Available attributes:
+
+   .. attribute:: metadata
+
+      Instance of :class:`packaging.metadata.Metadata` filled with the contents
+      of the :file:`{project-version}.dist-info/METADATA` file.
+
+   .. attribute:: name
+
+      Shortcut for ``metadata['Name']``.
+
+   .. attribute:: version
+
+      Shortcut for ``metadata['Version']``.
+
+   .. attribute:: requested
+
+      Boolean indicating whether this distribution was requested by the user of
+      automatically installed as a dependency.
+
+
+.. class:: EggInfoDistribution(path)
+
+   Class representing a legacy distribution.  It is compatible with distutils'
+   and setuptools' :file:`.egg-info` and :file:`.egg` files and directories.
+
+   .. FIXME should be named EggDistribution
+
+   Instantiate with the *path* to an egg file or directory.  Instances can be
+   compared and sorted.  Other available methods are:
+
+   .. method:: list_installed_files(local=False)
+
+   .. method:: uses(path)
+
+   Available attributes:
+
+   .. attribute:: metadata
+
+      Instance of :class:`packaging.metadata.Metadata` filled with the contents
+      of the :file:`{project-version}.egg-info/PKG-INFO` or
+      :file:`{project-version}.egg` file.
+
+   .. attribute:: name
+
+      Shortcut for ``metadata['Name']``.
+
+   .. attribute:: version
+
+      Shortcut for ``metadata['Version']``.
+
+
+Functions to work with the database
+-----------------------------------
+
+.. function:: get_distribution(name, use_egg_info=False, paths=None)
+
+   Return an instance of :class:`Distribution` or :class:`EggInfoDistribution`
+   for the first installed distribution matching *name*.  Egg distributions are
+   considered only if *use_egg_info* is true; if both a dist-info and an egg
+   file are found, the dist-info prevails.  The directories to be searched are
+   given in *paths*, which defaults to :data:`sys.path`.  Return ``None`` if no
+   matching distribution is found.
+
+   .. FIXME param should be named use_egg
+
+
+.. function:: get_distributions(use_egg_info=False, paths=None)
+
+   Return an iterator of :class:`Distribution` instances for all installed
+   distributions found in *paths* (defaults to :data:`sys.path`).  If
+   *use_egg_info* is true, also return instances of :class:`EggInfoDistribution`
+   for legacy distributions found.
+
+
+.. function:: get_file_users(path)
+
+   Return an iterator over all distributions using *path*, a local absolute path
+   or a relative ``'/'``-separated path.
+
+   .. XXX does this work with prefixes or full file path only?
+
+
+.. function:: obsoletes_distribution(name, version=None, use_egg_info=False)
+
+   Return an iterator over all distributions that declare they obsolete *name*.
+   *version* is an optional argument to match only specific releases (see
+   :mod:`packaging.version`).  If *use_egg_info* is true, legacy egg
+   distributions will be considered as well.
+
+
+.. function:: provides_distribution(name, version=None, use_egg_info=False)
+
+   Return an iterator over all distributions that declare they provide *name*.
+   *version* is an optional argument to match only specific releases (see
+   :mod:`packaging.version`).  If *use_egg_info* is true, legacy egg
+   distributions will be considered as well.
+
+
+Utility functions
+-----------------
+
+.. function:: distinfo_dirname(name, version)
+
+   Escape *name* and *version* into a filename-safe form and return the
+   directory name built from them, for example
+   :file:`{safename}-{safeversion}.dist-info.`  In *name*, runs of
+   non-alphanumeric characters are replaced with one ``'_'``; in *version*,
+   spaces become dots, and runs of other non-alphanumeric characters (except
+   dots) a replaced by one ``'-'``.
+
+   .. XXX wth spaces in version numbers?
+
+For performance purposes, the list of distributions is being internally
+cached.   Caching is enabled by default, but you can control it with these
+functions:
+
+.. function:: clear_cache()
+
+   Clear the cache.
+
+.. function:: disable_cache()
+
+   Disable the cache, without clearing it.
+
+.. function:: enable_cache()
+
+   Enable the internal cache, without clearing it.
+
+
+Examples
+--------
+
+Print all information about a distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Given a path to a ``.dist-info`` distribution, we shall print out all
+information that can be obtained using functions provided in this module::
+
+   import sys
+   import packaging.database
+
+   path = input()
+   # first create the Distribution instance
+   try:
+       dist = packaging.database.Distribution(path)
+   except IOError:
+       sys.exit('No such distribution')
+
+   print('Information about %r' % dist.name)
+   print()
+
+   print('Files')
+   print('=====')
+   for path, md5, size in dist.list_installed_files():
+       print('* Path: %s' % path)
+       print('  Hash %s, Size: %s bytes' % (md5, size))
+   print()
+
+   print('Metadata')
+   print('========')
+   for key, value in dist.metadata.items():
+       print('%20s: %s' % (key, value))
+   print()
+
+   print('Extra')
+   print('=====')
+   if dist.requested:
+       print('* It was installed by user request')
+   else:
+       print('* It was installed as a dependency')
+
+If we save the script above as ``print_info.py``, we can use it to extract
+information from a :file:`.dist-info` directory.  By typing in the console:
+
+.. code-block:: sh
+
+   $ echo /tmp/choxie/choxie-2.0.0.9.dist-info | python3 print_info.py
+
+we get the following output:
+
+.. code-block:: none
+
+   Information about 'choxie'
+
+   Files
+   =====
+   * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9/truffles.py
+     Hash 5e052db6a478d06bad9ae033e6bc08af, Size: 111 bytes
+   * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9/choxie/chocolate.py
+     Hash ac56bf496d8d1d26f866235b95f31030, Size: 214 bytes
+   * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9/choxie/__init__.py
+     Hash 416aab08dfa846f473129e89a7625bbc, Size: 25 bytes
+   * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9.dist-info/INSTALLER
+     Hash d41d8cd98f00b204e9800998ecf8427e, Size: 0 bytes
+   * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9.dist-info/METADATA
+     Hash 696a209967fef3c8b8f5a7bb10386385, Size: 225 bytes
+   * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9.dist-info/REQUESTED
+     Hash d41d8cd98f00b204e9800998ecf8427e, Size: 0 bytes
+   * Path: ../tmp/distutils2/tests/fake_dists/choxie-2.0.0.9.dist-info/RECORD
+     Hash None, Size: None bytes
+
+   Metadata
+   ========
+       Metadata-Version: 1.2
+                   Name: choxie
+                Version: 2.0.0.9
+               Platform: []
+     Supported-Platform: UNKNOWN
+                Summary: Chocolate with a kick!
+            Description: UNKNOWN
+               Keywords: []
+              Home-page: UNKNOWN
+                 Author: UNKNOWN
+           Author-email: UNKNOWN
+             Maintainer: UNKNOWN
+       Maintainer-email: UNKNOWN
+                License: UNKNOWN
+             Classifier: []
+           Download-URL: UNKNOWN
+         Obsoletes-Dist: ['truffles (<=0.8,>=0.5)', 'truffles (<=0.9,>=0.6)']
+            Project-URL: []
+          Provides-Dist: ['truffles (1.0)']
+          Requires-Dist: ['towel-stuff (0.1)']
+        Requires-Python: UNKNOWN
+      Requires-External: []
+
+  Extra
+  =====
+  * It was installed as a dependency
+
+
+Find out obsoleted distributions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now, we take tackle a different problem, we are interested in finding out
+which distributions have been obsoleted. This can be easily done as follows::
+
+  import packaging.database
+
+  # iterate over all distributions in the system
+  for dist in packaging.database.get_distributions():
+      name, version = dist.name, dist.version
+      # find out which distributions obsolete this name/version combination
+      replacements = packaging.database.obsoletes_distribution(name, version)
+      if replacements:
+          print('%r %s is obsoleted by' % (name, version),
+                ', '.join(repr(r.name) for r in replacements))
+
+This is how the output might look like:
+
+.. code-block:: none
+
+  'strawberry' 0.6 is obsoleted by 'choxie'
+  'grammar' 1.0a4 is obsoleted by 'towel-stuff'
diff --git a/Doc/library/packaging.depgraph.rst b/Doc/library/packaging.depgraph.rst
new file mode 100644
index 0000000000..c384788e9b
--- /dev/null
+++ b/Doc/library/packaging.depgraph.rst
@@ -0,0 +1,199 @@
+:mod:`packaging.depgraph` --- Dependency graph builder
+======================================================
+
+.. module:: packaging.depgraph
+   :synopsis: Graph builder for dependencies between releases.
+
+
+This module provides the means to analyse the dependencies between various
+distributions and to create a graph representing these dependency relationships.
+In this document, "distribution" refers to an instance of
+:class:`packaging.database.Distribution` or
+:class:`packaging.database.EggInfoDistribution`.
+
+.. XXX terminology problem with dist vs. release: dists are installed, but deps
+   use releases
+
+.. XXX explain how to use it with dists not installed: Distribution can only be
+   instantiated with a path, but this module is useful for remote dist too
+
+.. XXX functions should accept and return iterators, not lists
+
+
+The :class:`DependencyGraph` class
+----------------------------------
+
+.. class:: DependencyGraph
+
+   Represent a dependency graph between releases.  The nodes are distribution
+   instances; the edge model dependencies.  An edge from ``a`` to ``b`` means
+   that ``a`` depends on ``b``.
+
+   .. method:: add_distribution(distribution)
+
+      Add *distribution* to the graph.
+
+   .. method:: add_edge(x, y, label=None)
+
+      Add an edge from distribution *x* to distribution *y* with the given
+      *label* (string).
+
+   .. method:: add_missing(distribution, requirement)
+
+      Add a missing *requirement* (string) for the given *distribution*.
+
+   .. method:: repr_node(dist, level=1)
+
+      Print a subgraph starting from *dist*.  *level* gives the depth of the
+      subgraph.
+
+   Direct access to the graph nodes and edges is provided through these
+   attributes:
+
+   .. attribute:: adjacency_list
+
+      Dictionary mapping distributions to a list of ``(other, label)`` tuples
+      where  ``other`` is a distribution and the edge is labeled with ``label``
+      (i.e. the version specifier, if such was provided).
+
+   .. attribute:: reverse_list
+
+      Dictionary mapping distributions to a list of predecessors.  This allows
+      efficient traversal.
+
+   .. attribute:: missing
+
+      Dictionary mapping distributions to a list of requirements that were not
+      provided by any distribution.
+
+
+Auxiliary functions
+-------------------
+
+.. function:: dependent_dists(dists, dist)
+
+   Recursively generate a list of distributions from *dists* that are dependent
+   on *dist*.
+
+   .. XXX what does member mean here: "dist is a member of *dists* for which we
+      are interested"
+
+.. function:: generate_graph(dists)
+
+   Generate a :class:`DependencyGraph` from the given list of distributions.
+
+   .. XXX make this alternate constructor a DepGraph classmethod or rename;
+      'generate' can suggest it creates a file or an image, use 'make'
+
+.. function:: graph_to_dot(graph, f, skip_disconnected=True)
+
+   Write a DOT output for the graph to the file-like object *f*.
+
+   If *skip_disconnected* is true, all distributions that are not dependent on
+   any other distribution are skipped.
+
+   .. XXX why is this not a DepGraph method?
+
+
+Example Usage
+-------------
+
+Depict all dependenciess in the system
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First, we shall generate a graph of all the distributions on the system
+and then create an image out of it using the tools provided by
+`Graphviz <http://www.graphviz.org/>`_::
+
+   from packaging.database import get_distributions
+   from packaging.depgraph import generate_graph
+
+   dists = list(get_distributions())
+   graph = generate_graph(dists)
+
+It would be interesting to print out the missing requirements.  This can be done
+as follows::
+
+   for dist, reqs in graph.missing.items():
+       if reqs:
+           reqs = ' ,'.join(repr(req) for req in reqs)
+           print('Missing dependencies for %r: %s' % (dist.name, reqs))
+
+Example output is:
+
+.. code-block:: none
+
+   Missing dependencies for 'TurboCheetah': 'Cheetah'
+   Missing dependencies for 'TurboGears': 'ConfigObj', 'DecoratorTools', 'RuleDispatch'
+   Missing dependencies for 'jockey': 'PyKDE4.kdecore', 'PyKDE4.kdeui', 'PyQt4.QtCore', 'PyQt4.QtGui'
+   Missing dependencies for 'TurboKid': 'kid'
+   Missing dependencies for 'TurboJson: 'DecoratorTools', 'RuleDispatch'
+
+Now, we proceed with generating a graphical representation of the graph. First
+we write it to a file, and then we generate a PNG image using the
+:program:`dot` command-line tool::
+
+   from packaging.depgraph import graph_to_dot
+   with open('output.dot', 'w') as f:
+      # only show the interesting distributions, skipping the disconnected ones
+      graph_to_dot(graph, f, skip_disconnected=True)
+
+We can create the final picture using:
+
+.. code-block:: sh
+
+   $ dot -Tpng output.dot > output.png
+
+An example result is:
+
+.. figure:: depgraph-output.png
+   :alt: Example PNG output from packaging.depgraph and dot
+
+If you want to include egg distributions as well, then the code requires only
+one change, namely the line::
+
+   dists = list(packaging.database.get_distributions())
+
+has to be replaced with::
+
+   dists = list(packaging.database.get_distributions(use_egg_info=True))
+
+On many platforms, a richer graph is obtained because at the moment most
+distributions are provided in the egg rather than the new standard
+``.dist-info`` format.
+
+.. XXX missing image
+
+   An example of a more involved graph for illustrative reasons can be seen
+   here:
+
+   .. image:: depgraph_big.png
+
+
+List all dependent distributions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We will list all distributions that are dependent on some given distibution.
+This time, egg distributions will be considered as well::
+
+   import sys
+   from packaging.database import get_distribution, get_distributions
+   from packaging.depgraph import dependent_dists
+
+   dists = list(get_distributions(use_egg_info=True))
+   dist = get_distribution('bacon', use_egg_info=True)
+   if dist is None:
+       sys.exit('No such distribution in the system')
+
+   deps = dependent_dists(dists, dist)
+   deps = ', '.join(repr(x.name) for x in deps)
+   print('Distributions depending on %r: %s' % (dist.name, deps))
+
+And this is example output:
+
+.. with the dependency relationships as in the previous section
+   (depgraph_big)
+
+.. code-block:: none
+
+   Distributions depending on 'bacon': 'towel-stuff', 'choxie', 'grammar'
diff --git a/Doc/library/packaging.dist.rst b/Doc/library/packaging.dist.rst
new file mode 100644
index 0000000000..fb05b69c70
--- /dev/null
+++ b/Doc/library/packaging.dist.rst
@@ -0,0 +1,102 @@
+:mod:`packaging.dist` --- The Distribution class
+================================================
+
+.. module:: packaging.dist
+   :synopsis: Core Distribution class.
+
+
+This module provides the :class:`Distribution` class, which represents the
+module distribution being built/packaged/distributed/installed.
+
+.. class:: Distribution(arguments)
+
+   A :class:`Distribution` describes how to build, package, distribute and
+   install a Python project.
+
+   The arguments accepted by the constructor are laid out in the following
+   table.  Some of them will end up in a metadata object, the rest will become
+   data attributes of the :class:`Distribution` instance.
+
+   .. TODO improve constructor to take a Metadata object + named params?
+      (i.e. Distribution(metadata, cmdclass, py_modules, etc)
+   .. TODO also remove obsolete(?) script_name, etc. parameters?  see what
+      py2exe and other tools need
+
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | argument name      | value                          | type                                                        |
+   +====================+================================+=============================================================+
+   | *name*             | The name of the project        | string                                                      |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *version*          | The version number of the      | See :mod:`packaging.version`                                |
+   |                    | release                        |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *summary*          | A single line describing the   | a string                                                    |
+   |                    | project                        |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *description*      | Longer description of the      | a string                                                    |
+   |                    | project                        |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *author*           | The name of the project author | a string                                                    |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *author_email*     | The email address of the       | a string                                                    |
+   |                    | project author                 |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *maintainer*       | The name of the current        | a string                                                    |
+   |                    | maintainer, if different from  |                                                             |
+   |                    | the author                     |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *maintainer_email* | The email address of the       |                                                             |
+   |                    | current maintainer, if         |                                                             |
+   |                    | different from the author      |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *home_page*        | A URL for the proejct          | a URL                                                       |
+   |                    | (homepage)                     |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *download_url*     | A URL to download the project  | a URL                                                       |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *packages*         | A list of Python packages that | a list of strings                                           |
+   |                    | packaging will manipulate      |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *py_modules*       | A list of Python modules that  | a list of strings                                           |
+   |                    | packaging will manipulate      |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *scripts*          | A list of standalone scripts   | a list of strings                                           |
+   |                    | to be built and installed      |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *ext_modules*      | A list of Python extensions to | A list of instances of                                      |
+   |                    | be built                       | :class:`packaging.compiler.extension.Extension`             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *classifiers*      | A list of categories for the   | The list of available                                       |
+   |                    | distribution                   | categorizations is at                                       |
+   |                    |                                | http://pypi.python.org/pypi?:action=list_classifiers.       |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *distclass*        | the :class:`Distribution`      | A subclass of                                               |
+   |                    | class to use                   | :class:`packaging.dist.Distribution`                        |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *script_name*      | The name of the setup.py       | a string                                                    |
+   |                    | script - defaults to           |                                                             |
+   |                    | ``sys.argv[0]``                |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *script_args*      | Arguments to supply to the     | a list of strings                                           |
+   |                    | setup script                   |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *options*          | default options for the setup  | a string                                                    |
+   |                    | script                         |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *license*          | The license for the            | a string; should be used when there is no suitable License  |
+   |                    | distribution                   | classifier, or to specify a classifier                      |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *keywords*         | Descriptive keywords           | a list of strings; used by catalogs                         |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *platforms*        | Platforms compatible with this | a list of strings; should be used when there is no          |
+   |                    | distribution                   | suitable Platform classifier                                |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
+   |                    | :class:`Command` subclasses    |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *data_files*       | A list of data files to        | a list                                                      |
+   |                    | install                        |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
+   | *package_dir*      | A mapping of Python packages   | a dictionary                                                |
+   |                    | to directory names             |                                                             |
+   +--------------------+--------------------------------+-------------------------------------------------------------+
diff --git a/Doc/library/packaging.fancy_getopt.rst b/Doc/library/packaging.fancy_getopt.rst
new file mode 100644
index 0000000000..2c693411c7
--- /dev/null
+++ b/Doc/library/packaging.fancy_getopt.rst
@@ -0,0 +1,75 @@
+:mod:`packaging.fancy_getopt` --- Wrapper around the getopt module
+==================================================================
+
+.. module:: packaging.fancy_getopt
+   :synopsis: Additional getopt functionality.
+
+
+.. warning::
+   This module is deprecated and will be replaced with :mod:`optparse`.
+
+This module provides a wrapper around the standard :mod:`getopt` module that
+provides the following additional features:
+
+* short and long options are tied together
+
+* options have help strings, so :func:`fancy_getopt` could potentially create a
+  complete usage summary
+
+* options set attributes of a passed-in object
+
+* boolean options can have "negative aliases" --- e.g. if :option:`--quiet` is
+  the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
+  command line sets *verbose* to false.
+
+.. function:: fancy_getopt(options, negative_opt, object, args)
+
+   Wrapper function. *options* is a list of ``(long_option, short_option,
+   help_string)`` 3-tuples as described in the constructor for
+   :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
+   to option names, both the key and value should be in the *options* list.
+   *object* is an object which will be used to store values (see the :meth:`getopt`
+   method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
+   ``sys.argv[1:]`` if you pass ``None`` as *args*.
+
+
+.. class:: FancyGetopt([option_table=None])
+
+   The option_table is a list of 3-tuples: ``(long_option, short_option,
+   help_string)``
+
+   If an option takes an argument, its *long_option* should have ``'='`` appended;
+   *short_option* should just be a single character, no ``':'`` in any case.
+   *short_option* should be ``None`` if a *long_option* doesn't have a
+   corresponding *short_option*. All option tuples must have long options.
+
+The :class:`FancyGetopt` class provides the following methods:
+
+
+.. method:: FancyGetopt.getopt([args=None, object=None])
+
+   Parse command-line options in args. Store as attributes on *object*.
+
+   If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``.  If *object* is
+   ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
+   option values there, and returns a tuple ``(args, object)``.  If *object* is
+   supplied, it is modified in place and :func:`getopt` just returns *args*; in
+   both cases, the returned *args* is a modified copy of the passed-in *args* list,
+   which is left untouched.
+
+   .. TODO and args returned are?
+
+
+.. method:: FancyGetopt.get_option_order()
+
+   Returns the list of ``(option, value)`` tuples processed by the previous run of
+   :meth:`getopt`  Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
+   yet.
+
+
+.. method:: FancyGetopt.generate_help([header=None])
+
+   Generate help text (a list of strings, one per suggested line of output) from
+   the option table for this :class:`FancyGetopt` object.
+
+   If supplied, prints the supplied *header* at the top of the help.
diff --git a/Doc/library/packaging.install.rst b/Doc/library/packaging.install.rst
new file mode 100644
index 0000000000..b619a98e2e
--- /dev/null
+++ b/Doc/library/packaging.install.rst
@@ -0,0 +1,112 @@
+:mod:`packaging.install` --- Installation tools
+===============================================
+
+.. module:: packaging.install
+   :synopsis: Download and installation building blocks
+
+
+Packaging provides a set of tools to deal with downloads and installation of
+distributions.  Their role is to download the distribution from indexes, resolve
+the dependencies, and provide a safe way to install distributions.  An operation
+that fails will cleanly roll back, not leave half-installed distributions on the
+system.  Here's the basic process followed:
+
+#. Move all distributions that will be removed to a temporary location.
+
+#. Install all the distributions that will be installed in a temporary location.
+
+#. If the installation fails, move the saved distributions back to their
+   location and delete the installed distributions.
+
+#. Otherwise, move the installed distributions to the right location and delete
+   the temporary locations.
+
+This is a higher-level module built on :mod:`packaging.database` and
+:mod:`packaging.pypi`.
+
+
+Public functions
+----------------
+
+.. function:: get_infos(requirements, index=None, installed=None, \
+                        prefer_final=True)
+
+   Return information about what's going to be installed and upgraded.
+   *requirements* is a string string containing the requirements for this
+   project, for example ``'FooBar 1.1'`` or ``'BarBaz (<1.2)'``.
+
+   .. XXX are requirements comma-separated?
+
+   If you want to use another index than the main PyPI, give its URI as *index*
+   argument.
+
+   *installed* is a list of already installed distributions used to find
+   satisfied dependencies, obsoleted distributions and eventual conflicts.
+
+   By default, alpha, beta and candidate versions are not picked up.  Set
+   *prefer_final* to false to accept them too.
+
+   The results are returned in a dictionary containing all the information
+   needed to perform installation of the requirements with the
+   :func:`install_from_infos` function:
+
+   >>> get_install_info("FooBar (<=1.2)")
+   {'install': [<FooBar 1.1>], 'remove': [], 'conflict': []}
+
+   .. TODO should return tuple or named tuple, not dict
+   .. TODO use "predicate" or "requirement" consistently in version and here
+   .. FIXME "info" cannot be plural in English, s/infos/info/
+
+
+.. function:: install(project)
+
+
+.. function:: install_dists(dists, path, paths=None)
+
+   Safely install all distributions provided in *dists* into *path*.  *paths* is
+   a list of paths where already-installed distributions will be looked for to
+   find satisfied dependencies and conflicts (default: :data:`sys.path`).
+   Returns a list of installed dists.
+
+   .. FIXME dists are instances of what?
+
+
+.. function:: install_from_infos(install_path=None, install=[], remove=[], \
+                                 conflicts=[], paths=None)
+
+   Safely install and remove given distributions.  This function is designed to
+   work with the return value of :func:`get_infos`: *install*, *remove* and
+   *conflicts* should be list of distributions returned by :func:`get_infos`.
+   If *install* is not empty, *install_path* must be given to specify the path
+   where the distributions should be installed.  *paths* is a list of paths
+   where already-installed distributions will be looked for (default:
+   :data:`sys.path`).
+
+   This function is a very basic installer; if *conflicts* is not empty, the
+   system will be in a conflicting state after the function completes.  It is a
+   building block for more sophisticated installers with conflict resolution
+   systems.
+
+   .. TODO document typical value for install_path
+   .. TODO document integration with default schemes, esp. user site-packages
+
+
+.. function:: install_local_project(path)
+
+   Install a distribution from a source directory, which must contain either a
+   Packaging-compliant :file:`setup.cfg` file or a legacy Distutils
+   :file:`setup.py` script (in which case Distutils will be used under the hood
+   to perform the installation).
+
+
+.. function::  remove(project_name, paths=None, auto_confirm=True)
+
+   Remove one distribution from the system.
+
+   .. FIXME this is the only function using "project" instead of dist/release
+
+..
+   Example usage
+   --------------
+
+   Get the scheme of what's gonna be installed if we install "foobar":
diff --git a/Doc/library/packaging.metadata.rst b/Doc/library/packaging.metadata.rst
new file mode 100644
index 0000000000..332d69df4f
--- /dev/null
+++ b/Doc/library/packaging.metadata.rst
@@ -0,0 +1,122 @@
+:mod:`packaging.metadata` --- Metadata handling
+===============================================
+
+.. module:: packaging.metadata
+   :synopsis: Class holding the metadata of a release.
+
+
+.. TODO use sphinx-autogen to generate basic doc from the docstrings
+
+.. class:: Metadata
+
+   This class can read and write metadata files complying with any of the
+   defined versions: 1.0 (:PEP:`241`), 1.1 (:PEP:`314`) and 1.2 (:PEP:`345`).  It
+   implements methods to parse Metadata files and write them, and a mapping
+   interface to its contents.
+
+   The :PEP:`345` implementation supports the micro-language for the environment
+   markers, and displays warnings when versions that are supposed to be
+   :PEP:`386`-compliant are violating the specification.
+
+
+Reading metadata
+----------------
+
+The :class:`Metadata` class can be instantiated
+with the path of the metadata file, and provides a dict-like interface to the
+values::
+
+   >>> from packaging.metadata import Metadata
+   >>> metadata = Metadata('PKG-INFO')
+   >>> metadata.keys()[:5]
+   ('Metadata-Version', 'Name', 'Version', 'Platform', 'Supported-Platform')
+   >>> metadata['Name']
+   'CLVault'
+   >>> metadata['Version']
+   '0.5'
+   >>> metadata['Requires-Dist']
+   ["pywin32; sys.platform == 'win32'", "Sphinx"]
+
+
+The fields that support environment markers can be automatically ignored if
+the object is instantiated using the ``platform_dependent`` option.
+:class:`Metadata` will interpret in this case
+the markers and will automatically remove the fields that are not compliant
+with the running environment. Here's an example under Mac OS X. The win32
+dependency we saw earlier is ignored::
+
+   >>> from packaging.metadata import Metadata
+   >>> metadata = Metadata('PKG-INFO', platform_dependent=True)
+   >>> metadata['Requires-Dist']
+   ['Sphinx']
+
+
+If you want to provide your own execution context, let's say to test the
+metadata under a particular environment that is not the current environment,
+you can provide your own values in the ``execution_context`` option, which
+is the dict that may contain one or more keys of the context the micro-language
+expects.
+
+Here's an example, simulating a win32 environment::
+
+   >>> from packaging.metadata import Metadata
+   >>> context = {'sys.platform': 'win32'}
+   >>> metadata = Metadata('PKG-INFO', platform_dependent=True,
+   ...                     execution_context=context)
+   ...
+   >>> metadata['Requires-Dist'] = ["pywin32; sys.platform == 'win32'",
+   ...                              "Sphinx"]
+   ...
+   >>> metadata['Requires-Dist']
+   ['pywin32', 'Sphinx']
+
+
+Writing metadata
+----------------
+
+Writing metadata can be done using the ``write`` method::
+
+   >>> metadata.write('/to/my/PKG-INFO')
+
+The class will pick the best version for the metadata, depending on the values
+provided. If all the values provided exist in all versions, the class will
+use :attr:`PKG_INFO_PREFERRED_VERSION`.  It is set by default to 1.0, the most
+widespread version.
+
+
+Conflict checking and best version
+----------------------------------
+
+Some fields in :PEP:`345` have to comply with the version number specification
+defined in :PEP:`386`.  When they don't comply, a warning is emitted::
+
+   >>> from packaging.metadata import Metadata
+   >>> metadata = Metadata()
+   >>> metadata['Requires-Dist'] = ['Funky (Groovie)']
+   "Funky (Groovie)" is not a valid predicate
+   >>> metadata['Requires-Dist'] = ['Funky (1.2)']
+
+See also :mod:`packaging.version`.
+
+
+.. TODO talk about check()
+
+
+:mod:`packaging.markers` --- Environment markers
+================================================
+
+.. module:: packaging.markers
+   :synopsis: Micro-language for environment markers
+
+
+This is an implementation of environment markers `as defined in PEP 345
+<http://www.python.org/dev/peps/pep-0345/#environment-markers>`_.  It is used
+for some metadata fields.
+
+.. function:: interpret(marker, execution_context=None)
+
+   Interpret a marker and return a boolean result depending on the environment.
+   Example:
+
+      >>> interpret("python_version > '1.0'")
+      True
diff --git a/Doc/library/packaging.pypi.dist.rst b/Doc/library/packaging.pypi.dist.rst
new file mode 100644
index 0000000000..aaaaab7fb8
--- /dev/null
+++ b/Doc/library/packaging.pypi.dist.rst
@@ -0,0 +1,114 @@
+:mod:`packaging.pypi.dist` --- Classes representing query results
+=================================================================
+
+.. module:: packaging.pypi.dist
+   :synopsis: Classes representing the results of queries to indexes.
+
+
+Information coming from the indexes is held in instances of the classes defined
+in this module.
+
+Keep in mind that each project (eg. FooBar) can have several releases
+(eg. 1.1, 1.2, 1.3), and each of these releases can be provided in multiple
+distributions (eg. a source distribution, a binary one, etc).
+
+
+ReleaseInfo
+-----------
+
+Each release has a project name, version, metadata, and related distributions.
+
+This information is stored in :class:`ReleaseInfo`
+objects.
+
+.. class:: ReleaseInfo
+
+
+DistInfo
+---------
+
+:class:`DistInfo` is a simple class that contains
+information related to distributions; mainly the URLs where distributions
+can be found.
+
+.. class:: DistInfo
+
+
+ReleasesList
+------------
+
+The :mod:`~packaging.pypi.dist` module provides a class which works
+with lists of :class:`ReleaseInfo` classes;
+used to filter and order results.
+
+.. class:: ReleasesList
+
+
+Example usage
+-------------
+
+Build a list of releases and order them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assuming we have a list of releases::
+
+   >>> from packaging.pypi.dist import ReleasesList, ReleaseInfo
+   >>> fb10 = ReleaseInfo("FooBar", "1.0")
+   >>> fb11 = ReleaseInfo("FooBar", "1.1")
+   >>> fb11a = ReleaseInfo("FooBar", "1.1a1")
+   >>> ReleasesList("FooBar", [fb11, fb11a, fb10])
+   >>> releases.sort_releases()
+   >>> releases.get_versions()
+   ['1.1', '1.1a1', '1.0']
+   >>> releases.add_release("1.2a1")
+   >>> releases.get_versions()
+   ['1.1', '1.1a1', '1.0', '1.2a1']
+   >>> releases.sort_releases()
+   ['1.2a1', '1.1', '1.1a1', '1.0']
+   >>> releases.sort_releases(prefer_final=True)
+   >>> releases.get_versions()
+   ['1.1', '1.0', '1.2a1', '1.1a1']
+
+
+Add distribution related information to releases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It's easy to add distribution information to releases::
+
+   >>> from packaging.pypi.dist import ReleasesList, ReleaseInfo
+   >>> r = ReleaseInfo("FooBar", "1.0")
+   >>> r.add_distribution("sdist", url="http://example.org/foobar-1.0.tar.gz")
+   >>> r.dists
+   {'sdist': FooBar 1.0 sdist}
+   >>> r['sdist'].url
+   {'url': 'http://example.org/foobar-1.0.tar.gz', 'hashname': None, 'hashval':
+   None, 'is_external': True}
+
+
+Getting attributes from the dist objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To abstract querying information returned from the indexes, attributes and
+release information can be retrieved directly from dist objects.
+
+For instance, if you have a release instance that does not contain the metadata
+attribute, it can be fetched by using the "fetch_metadata" method::
+
+   >>> r = Release("FooBar", "1.1")
+   >>> print r.metadata
+   None # metadata field is actually set to "None"
+   >>> r.fetch_metadata()
+   <Metadata for FooBar 1.1>
+
+.. XXX add proper roles to these constructs
+
+
+It's possible to retrieve a project's releases (`fetch_releases`),
+metadata (`fetch_metadata`) and distributions (`fetch_distributions`) using
+a similar work flow.
+
+.. XXX what is possible?
+
+Internally, this is possible because while retrieving information about
+projects, releases or distributions, a reference to the client used is
+stored which can be accessed using the objects `_index` attribute.
diff --git a/Doc/library/packaging.pypi.rst b/Doc/library/packaging.pypi.rst
new file mode 100644
index 0000000000..14602cefc1
--- /dev/null
+++ b/Doc/library/packaging.pypi.rst
@@ -0,0 +1,74 @@
+:mod:`packaging.pypi` --- Interface to projects indexes
+=======================================================
+
+.. module:: packaging.pypi
+   :synopsis: Low-level and high-level APIs to query projects indexes.
+
+
+Packaging queries PyPI to get information about projects or download them.  The
+low-level facilities used internally are also part of the public API designed to
+be used by other tools.
+
+The :mod:`packaging.pypi` package provides those facilities, which can be
+used to access information about Python projects registered at indexes, the
+main one being PyPI, located ad http://pypi.python.org/.
+
+There is two ways to retrieve data from these indexes: a screen-scraping
+interface called the "simple API", and XML-RPC.  The first one uses HTML pages
+located under http://pypi.python.org/simple/, the second one makes XML-RPC
+requests to http://pypi.python.org/pypi/.  All functions and classes also work
+with other indexes such as mirrors, which typically implement only the simple
+interface.
+
+Packaging provides a class that wraps both APIs to provide full query and
+download functionality: :class:`packaging.pypi.client.ClientWrapper`.  If you
+want more control, you can use the underlying classes
+:class:`packaging.pypi.simple.Crawler` and :class:`packaging.pypi.xmlrpc.Client`
+to connect to one specific interface.
+
+
+:mod:`packaging.pypi.client` --- High-level query API
+=====================================================
+
+.. module:: packaging.pypi.client
+   :synopsis: Wrapper around :mod;`packaging.pypi.xmlrpc` and
+              :mod:`packaging.pypi.simple` to query indexes.
+
+
+This module provides a high-level API to query indexes and search
+for releases and distributions. The aim of this module is to choose the best
+way to query the API automatically, either using XML-RPC or the simple index,
+with a preference toward the latter.
+
+.. class:: ClientWrapper
+
+   Instances of this class will use the simple interface or XML-RPC requests to
+   query indexes and return :class:`packaging.pypi.dist.ReleaseInfo` and
+   :class:`packaging.pypi.dist.ReleasesList` objects.
+
+   .. method:: find_projects
+
+   .. method:: get_release
+
+   .. method:: get_releases
+
+
+:mod:`packaging.pypi.base` --- Base class for index crawlers
+============================================================
+
+.. module:: packaging.pypi.base
+   :synopsis: Base class used to implement crawlers.
+
+
+.. class:: BaseClient(prefer_final, prefer_source)
+
+   Base class containing common methods for the index crawlers or clients.  One
+   method is currently defined:
+
+   .. method:: download_distribution(requirements, temp_path=None, \
+                                     prefer_source=None, prefer_final=None)
+
+      Download a distribution from the last release according to the
+      requirements.  If *temp_path* is provided, download to this path,
+      otherwise, create a temporary directory for the download.  If a release is
+      found, the full path to the downloaded file is returned.
diff --git a/Doc/library/packaging.pypi.simple.rst b/Doc/library/packaging.pypi.simple.rst
new file mode 100644
index 0000000000..92b3270f10
--- /dev/null
+++ b/Doc/library/packaging.pypi.simple.rst
@@ -0,0 +1,218 @@
+:mod:`packaging.pypi.simple` --- Crawler using the PyPI "simple" interface
+==========================================================================
+
+.. module:: packaging.pypi.simple
+   :synopsis: Crawler using the screen-scraping "simple" interface to fetch info
+              and distributions.
+
+
+The class provided by :mod:`packaging.pypi.simple` can access project indexes
+and provide useful information about distributions.  PyPI, other indexes and
+local indexes are supported.
+
+You should use this module to search distributions by name and versions, process
+index external pages and download distributions.  It is not suited for things
+that will end up in too long index processing (like "finding all distributions
+with a specific version, no matter the name"); use :mod:`packaging.pypi.xmlrpc`
+for that.
+
+
+API
+---
+
+.. class:: Crawler(index_url=DEFAULT_SIMPLE_INDEX_URL, \
+                   prefer_final=False, prefer_source=True, \
+                   hosts=('*',), follow_externals=False, \
+                   mirrors_url=None, mirrors=None, timeout=15, \
+                   mirrors_max_tries=0, verbose=False)
+
+      *index_url* is the address of the index to use for requests.
+
+      The first two parameters control the query results.  *prefer_final*
+      indicates whether a final version (not alpha, beta or candidate) is to be
+      prefered over a newer but non-final version (for example, whether to pick
+      up 1.0 over 2.0a3).  It is used only for queries that don't give a version
+      argument.  Likewise, *prefer_source* tells whether to prefer a source
+      distribution over a binary one, if no distribution argument was prodived.
+
+      Other parameters are related to external links (that is links that go
+      outside the simple index): *hosts* is a list of hosts allowed to be
+      processed if *follow_externals* is true (default behavior is to follow all
+      hosts), *follow_externals* enables or disables following external links
+      (default is false, meaning disabled).
+
+      The remaining parameters are related to the mirroring infrastructure
+      defined in :PEP:`381`.  *mirrors_url* gives a URL to look on for DNS
+      records giving mirror adresses; *mirrors* is a list of mirror URLs (see
+      the PEP).  If both *mirrors* and *mirrors_url* are given, *mirrors_url*
+      will only be used if *mirrors* is set to ``None``.  *timeout* is the time
+      (in seconds) to wait before considering a URL has timed out;
+      *mirrors_max_tries"* is the number of times to try requesting informations
+      on mirrors before switching.
+
+      The following methods are defined:
+
+      .. method:: get_distributions(project_name, version)
+
+         Return the distributions found in the index for the given release.
+
+      .. method:: get_metadata(project_name, version)
+
+         Return the metadata found on the index for this project name and
+         version.  Currently downloads and unpacks a distribution to read the
+         PKG-INFO file.
+
+      .. method:: get_release(requirements, prefer_final=None)
+
+         Return one release that fulfills the given requirements.
+
+      .. method:: get_releases(requirements, prefer_final=None, force_update=False)
+
+         Search for releases and return a
+         :class:`~packaging.pypi.dist.ReleasesList` object containing the
+         results.
+
+      .. method:: search_projects(name=None)
+
+         Search the index for projects containing the given name and return a
+         list of matching names.
+
+   See also the base class :class:`packaging.pypi.base.BaseClient` for inherited
+   methods.
+
+
+.. data:: DEFAULT_SIMPLE_INDEX_URL
+
+   The address used by default by the crawler class.  It is currently
+   ``'http://a.pypi.python.org/simple/'``, the main PyPI installation.
+
+
+
+
+Usage Exemples
+---------------
+
+To help you understand how using the `Crawler` class, here are some basic
+usages.
+
+Request the simple index to get a specific distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Supposing you want to scan an index to get a list of distributions for
+the "foobar" project. You can use the "get_releases" method for that.
+The get_releases method will browse the project page, and return
+:class:`ReleaseInfo`  objects for each found link that rely on downloads. ::
+
+   >>> from packaging.pypi.simple import Crawler
+   >>> crawler = Crawler()
+   >>> crawler.get_releases("FooBar")
+   [<ReleaseInfo "Foobar 1.1">, <ReleaseInfo "Foobar 1.2">]
+
+
+Note that you also can request the client about specific versions, using version
+specifiers (described in `PEP 345
+<http://www.python.org/dev/peps/pep-0345/#version-specifiers>`_)::
+
+   >>> client.get_releases("FooBar < 1.2")
+   [<ReleaseInfo "FooBar 1.1">, ]
+
+
+`get_releases` returns a list of :class:`ReleaseInfo`, but you also can get the
+best distribution that fullfil your requirements, using "get_release"::
+
+   >>> client.get_release("FooBar < 1.2")
+   <ReleaseInfo "FooBar 1.1">
+
+
+Download distributions
+^^^^^^^^^^^^^^^^^^^^^^
+
+As it can get the urls of distributions provided by PyPI, the `Crawler`
+client also can download the distributions and put it for you in a temporary
+destination::
+
+   >>> client.download("foobar")
+   /tmp/temp_dir/foobar-1.2.tar.gz
+
+
+You also can specify the directory you want to download to::
+
+   >>> client.download("foobar", "/path/to/my/dir")
+   /path/to/my/dir/foobar-1.2.tar.gz
+
+
+While downloading, the md5 of the archive will be checked, if not matches, it
+will try another time, then if fails again, raise `MD5HashDoesNotMatchError`.
+
+Internally, that's not the Crawler which download the distributions, but the
+`DistributionInfo` class. Please refer to this documentation for more details.
+
+
+Following PyPI external links
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The default behavior for packaging is to *not* follow the links provided
+by HTML pages in the "simple index", to find distributions related
+downloads.
+
+It's possible to tell the PyPIClient to follow external links by setting the
+`follow_externals` attribute, on instantiation or after::
+
+   >>> client = Crawler(follow_externals=True)
+
+or ::
+
+   >>> client = Crawler()
+   >>> client.follow_externals = True
+
+
+Working with external indexes, and mirrors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The default `Crawler` behavior is to rely on the Python Package index stored
+on PyPI (http://pypi.python.org/simple).
+
+As you can need to work with a local index, or private indexes, you can specify
+it using the index_url parameter::
+
+   >>> client = Crawler(index_url="file://filesystem/path/")
+
+or ::
+
+   >>> client = Crawler(index_url="http://some.specific.url/")
+
+
+You also can specify mirrors to fallback on in case the first index_url you
+provided doesnt respond, or not correctly. The default behavior for
+`Crawler` is to use the list provided by Python.org DNS records, as
+described in the :PEP:`381` about mirroring infrastructure.
+
+If you don't want to rely on these, you could specify the list of mirrors you
+want to try by specifying the `mirrors` attribute. It's a simple iterable::
+
+   >>> mirrors = ["http://first.mirror","http://second.mirror"]
+   >>> client = Crawler(mirrors=mirrors)
+
+
+Searching in the simple index
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It's possible to search for projects with specific names in the package index.
+Assuming you want to find all projects containing the "distutils" keyword::
+
+   >>> c.search_projects("distutils")
+   [<Project "collective.recipe.distutils">, <Project "Distutils">, <Project
+   "Packaging">, <Project "distutilscross">, <Project "lpdistutils">, <Project
+   "taras.recipe.distutils">, <Project "zerokspot.recipe.distutils">]
+
+
+You can also search the projects starting with a specific text, or ending with
+that text, using a wildcard::
+
+   >>> c.search_projects("distutils*")
+   [<Project "Distutils">, <Project "Packaging">, <Project "distutilscross">]
+
+   >>> c.search_projects("*distutils")
+   [<Project "collective.recipe.distutils">, <Project "Distutils">, <Project
+   "lpdistutils">, <Project "taras.recipe.distutils">, <Project
+   "zerokspot.recipe.distutils">]
diff --git a/Doc/library/packaging.pypi.xmlrpc.rst b/Doc/library/packaging.pypi.xmlrpc.rst
new file mode 100644
index 0000000000..0253d68089
--- /dev/null
+++ b/Doc/library/packaging.pypi.xmlrpc.rst
@@ -0,0 +1,143 @@
+:mod:`packaging.pypi.xmlrpc` --- Crawler using the PyPI XML-RPC interface
+=========================================================================
+
+.. module:: packaging.pypi.xmlrpc
+   :synopsis: Client using XML-RPC requests to fetch info and distributions.
+
+
+Indexes can be queried using XML-RPC calls, and Packaging provides a simple
+way to interface with XML-RPC.
+
+You should **use** XML-RPC when:
+
+* Searching the index for projects **on other fields than project
+  names**. For instance, you can search for projects based on the
+  author_email field.
+* Searching all the versions that have existed for a project.
+* you want to retrieve METADATAs information from releases or
+  distributions.
+
+
+You should **avoid using** XML-RPC method calls when:
+
+* Retrieving the last version of a project
+* Getting the projects with a specific name and version.
+* The simple index can match your needs
+
+
+When dealing with indexes, keep in mind that the index queries will always
+return you :class:`packaging.pypi.dist.ReleaseInfo` and
+:class:`packaging.pypi.dist.ReleasesList` objects.
+
+Some methods here share common APIs with the one you can find on
+:class:`packaging.pypi.simple`, internally, :class:`packaging.pypi.client`
+is inherited by :class:`Client`
+
+
+API
+---
+
+.. class:: Client
+
+
+Usage examples
+--------------
+
+Use case described here are use case that are not common to the other clients.
+If you want to see all the methods, please refer to API or to usage examples
+described in :class:`packaging.pypi.client.Client`
+
+
+Finding releases
+^^^^^^^^^^^^^^^^
+
+It's a common use case to search for "things" within the index. We can
+basically search for projects by their name, which is the most used way for
+users (eg. "give me the last version of the FooBar project").
+
+This can be accomplished using the following syntax::
+
+   >>> client = xmlrpc.Client()
+   >>> client.get_release("Foobar (<= 1.3))
+   <FooBar 1.2.1>
+   >>> client.get_releases("FooBar (<= 1.3)")
+   [FooBar 1.1, FooBar 1.1.1, FooBar 1.2, FooBar 1.2.1]
+
+
+And we also can find for specific fields::
+
+   >>> client.search_projects(field=value)
+
+
+You could specify the operator to use, default is "or"::
+
+   >>> client.search_projects(field=value, operator="and")
+
+
+The specific fields you can search are:
+
+* name
+* version
+* author
+* author_email
+* maintainer
+* maintainer_email
+* home_page
+* license
+* summary
+* description
+* keywords
+* platform
+* download_url
+
+
+Getting metadata information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+XML-RPC is a prefered way to retrieve metadata information from indexes.
+It's really simple to do so::
+
+   >>> client = xmlrpc.Client()
+   >>> client.get_metadata("FooBar", "1.1")
+   <ReleaseInfo FooBar 1.1>
+
+
+Assuming we already have a :class:`packaging.pypi.ReleaseInfo` object defined,
+it's possible to pass it to the xmlrpc client to retrieve and complete its
+metadata::
+
+   >>> foobar11 = ReleaseInfo("FooBar", "1.1")
+   >>> client = xmlrpc.Client()
+   >>> returned_release = client.get_metadata(release=foobar11)
+   >>> returned_release
+   <ReleaseInfo FooBar 1.1>
+
+
+Get all the releases of a project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To retrieve all the releases for a project, you can build them using
+`get_releases`::
+
+   >>> client = xmlrpc.Client()
+   >>> client.get_releases("FooBar")
+   [<ReleaseInfo FooBar 0.9>, <ReleaseInfo FooBar 1.0>, <ReleaseInfo 1.1>]
+
+
+Get information about distributions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Indexes have information about projects, releases **and** distributions.
+If you're not familiar with those, please refer to the documentation of
+:mod:`packaging.pypi.dist`.
+
+It's possible to retrieve information about distributions, e.g "what are the
+existing distributions for this release ? How to retrieve them ?"::
+
+   >>> client = xmlrpc.Client()
+   >>> release = client.get_distributions("FooBar", "1.1")
+   >>> release.dists
+   {'sdist': <FooBar 1.1 sdist>, 'bdist': <FooBar 1.1 bdist>}
+
+As you see, this does not return a list of distributions, but a release,
+because a release can be used like a list of distributions.
diff --git a/Doc/library/packaging.rst b/Doc/library/packaging.rst
new file mode 100644
index 0000000000..5bf2c06ad9
--- /dev/null
+++ b/Doc/library/packaging.rst
@@ -0,0 +1,78 @@
+:mod:`packaging` --- Packaging support
+======================================
+
+.. module:: packaging
+   :synopsis: Packaging system and building blocks for other packaging systems.
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>, distutils and packaging
+                   contributors
+
+
+The :mod:`packaging` package provides support for building, packaging,
+distributing and installing additional projects into a Python installation.
+Projects may include Python modules, extension modules, packages and scripts.
+:mod:`packaging` also provides building blocks for other packaging systems
+that are not tied to the command system.
+
+This manual is the reference documentation for those standalone building
+blocks and for extending Packaging. If you're looking for the user-centric
+guides to install a project or package your own code, head to `See also`__.
+
+
+Building blocks
+---------------
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   packaging-misc
+   packaging.version
+   packaging.metadata
+   packaging.database
+   packaging.depgraph
+   packaging.pypi
+   packaging.pypi.dist
+   packaging.pypi.simple
+   packaging.pypi.xmlrpc
+   packaging.install
+
+
+The command machinery
+---------------------
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   packaging.dist
+   packaging.command
+   packaging.compiler
+   packaging.fancy_getopt
+
+
+Other utilities
+----------------
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   packaging.util
+   packaging.tests.pypi_server
+
+.. XXX missing: compat config create (dir_util) run pypi.{base,mirrors}
+
+
+.. __:
+
+.. seealso::
+
+   :ref:`packaging-index`
+      The manual for developers of Python projects who want to package and
+      distribute them. This describes how to use :mod:`packaging` to make
+      projects easily found and added to an existing Python installation.
+
+   :ref:`packaging-install-index`
+      A user-centered manual which includes information on adding projects
+      into an existing Python installation.  You do not need to be a Python
+      programmer to read this manual.
diff --git a/Doc/library/packaging.tests.pypi_server.rst b/Doc/library/packaging.tests.pypi_server.rst
new file mode 100644
index 0000000000..f3b77203f4
--- /dev/null
+++ b/Doc/library/packaging.tests.pypi_server.rst
@@ -0,0 +1,105 @@
+:mod:`packaging.tests.pypi_server` --- PyPI mock server
+=======================================================
+
+.. module:: packaging.tests.pypi_server
+   :synopsis: Mock server used to test PyPI-related modules and commands.
+
+
+When you are testing code that works with Packaging, you might find these tools
+useful.
+
+
+The mock server
+---------------
+
+.. class:: PyPIServer
+
+   PyPIServer is a class that implements an HTTP server running in a separate
+   thread. All it does is record the requests for further inspection. The recorded
+   data is available under ``requests`` attribute. The default
+   HTTP response can be overridden with the ``default_response_status``,
+   ``default_response_headers`` and ``default_response_data`` attributes.
+
+   By default, when accessing the server with urls beginning with `/simple/`,
+   the server also record your requests, but will look for files under
+   the `/tests/pypiserver/simple/` path.
+
+   You can tell the sever to serve static files for other paths. This could be
+   accomplished by using the `static_uri_paths` parameter, as below::
+
+      server = PyPIServer(static_uri_paths=["first_path", "second_path"])
+
+
+   You need to create the content that will be served under the
+   `/tests/pypiserver/default` path. If you want to serve content from another
+   place, you also can specify another filesystem path (which needs to be under
+   `tests/pypiserver/`. This will replace the default behavior of the server, and
+   it will not serve content from the `default` dir ::
+
+      server = PyPIServer(static_filesystem_paths=["path/to/your/dir"])
+
+
+   If you just need to add some paths to the existing ones, you can do as shown,
+   keeping in mind that the server will always try to load paths in reverse order
+   (e.g here, try "another/super/path" then the default one) ::
+
+      server = PyPIServer(test_static_path="another/super/path")
+      server = PyPIServer("another/super/path")
+      # or
+      server.static_filesystem_paths.append("another/super/path")
+
+
+   As a result of what, in your tests, while you need to use the PyPIServer, in
+   order to isolates the test cases, the best practice is to place the common files
+   in the `default` folder, and to create a directory for each specific test case::
+
+      server = PyPIServer(static_filesystem_paths = ["default", "test_pypi_server"],
+                          static_uri_paths=["simple", "external"])
+
+
+Base class and decorator for tests
+----------------------------------
+
+.. class:: PyPIServerTestCase
+
+   ``PyPIServerTestCase`` is a test case class with setUp and tearDown methods that
+   take care of a single PyPIServer instance attached as a ``pypi`` attribute on
+   the test class. Use it as one of the base classes in your test case::
+
+
+      class UploadTestCase(PyPIServerTestCase):
+
+          def test_something(self):
+              cmd = self.prepare_command()
+              cmd.ensure_finalized()
+              cmd.repository = self.pypi.full_address
+              cmd.run()
+
+              environ, request_data = self.pypi.requests[-1]
+              self.assertEqual(request_data, EXPECTED_REQUEST_DATA)
+
+
+.. decorator:: use_pypi_server
+
+   You also can use a decorator for your tests, if you do not need the same server
+   instance along all you test case. So, you can specify, for each test method,
+   some initialisation parameters for the server.
+
+   For this, you need to add a `server` parameter to your method, like this::
+
+      class SampleTestCase(TestCase):
+
+          @use_pypi_server()
+          def test_something(self, server):
+              ...
+
+
+   The decorator will instantiate the server for you, and run and stop it just
+   before and after your method call. You also can pass the server initializer,
+   just like this::
+
+      class SampleTestCase(TestCase):
+
+          @use_pypi_server("test_case_name")
+          def test_something(self, server):
+              ...
diff --git a/Doc/library/packaging.util.rst b/Doc/library/packaging.util.rst
new file mode 100644
index 0000000000..b95d5b528e
--- /dev/null
+++ b/Doc/library/packaging.util.rst
@@ -0,0 +1,186 @@
+:mod:`packaging.util` --- Miscellaneous utility functions
+=========================================================
+
+.. module:: packaging.util
+   :synopsis: Miscellaneous utility functions.
+
+
+This module contains various helpers for the other modules.
+
+.. XXX a number of functions are missing, but the module may be split first
+   (it's ginormous right now, some things could go to compat for example)
+
+.. function:: get_platform()
+
+   Return a string that identifies the current platform.  This is used mainly to
+   distinguish platform-specific build directories and platform-specific built
+   distributions.  Typically includes the OS name and version and the
+   architecture (as supplied by 'os.uname()'), although the exact information
+   included depends on the OS; e.g. for IRIX the architecture isn't particularly
+   important (IRIX only runs on SGI hardware), but for Linux the kernel version
+   isn't particularly important.
+
+   Examples of returned values:
+
+   * ``linux-i586``
+   * ``linux-alpha``
+   * ``solaris-2.6-sun4u``
+   * ``irix-5.3``
+   * ``irix64-6.2``
+
+   For non-POSIX platforms, currently just returns ``sys.platform``.
+
+   For Mac OS X systems the OS version reflects the minimal version on which
+   binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
+   during the build of Python), not the OS version of the current system.
+
+   For universal binary builds on Mac OS X the architecture value reflects
+   the univeral binary status instead of the architecture of the current
+   processor. For 32-bit universal binaries the architecture is ``fat``,
+   for 64-bit universal binaries the architecture is ``fat64``, and
+   for 4-way universal binaries the architecture is ``universal``. Starting
+   from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
+   a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
+   a univeral build with the i386 and x86_64 architectures
+
+   Examples of returned values on Mac OS X:
+
+   * ``macosx-10.3-ppc``
+
+   * ``macosx-10.3-fat``
+
+   * ``macosx-10.5-universal``
+
+   * ``macosx-10.6-intel``
+
+   .. XXX reinvention of platform module?
+
+
+.. function:: convert_path(pathname)
+
+   Return 'pathname' as a name that will work on the native filesystem, i.e.
+   split it on '/' and put it back together again using the current directory
+   separator. Needed because filenames in the setup script are always supplied
+   in Unix style, and have to be converted to the local convention before we
+   can actually use them in the filesystem.  Raises :exc:`ValueError` on
+   non-Unix-ish systems if *pathname* either starts or ends with a slash.
+
+
+.. function:: change_root(new_root, pathname)
+
+   Return *pathname* with *new_root* prepended.  If *pathname* is relative, this
+   is equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires
+   making *pathname* relative and then joining the two, which is tricky on
+   DOS/Windows.
+
+
+.. function:: check_environ()
+
+   Ensure that 'os.environ' has all the environment variables we guarantee that
+   users can use in config files, command-line options, etc.  Currently this
+   includes:
+
+   * :envvar:`HOME` - user's home directory (Unix only)
+   * :envvar:`PLAT` - description of the current platform, including hardware
+     and OS (see :func:`get_platform`)
+
+
+.. function:: find_executable(executable, path=None)
+
+   Search the path for a given executable name.
+
+
+.. function:: subst_vars(s, local_vars)
+
+   Perform shell/Perl-style variable substitution on *s*.  Every occurrence of
+   ``$`` followed by a name is considered a variable, and variable is
+   substituted by the value found in the *local_vars* dictionary, or in
+   ``os.environ`` if it's not in *local_vars*. *os.environ* is first
+   checked/augmented to guarantee that it contains certain values: see
+   :func:`check_environ`.  Raise :exc:`ValueError` for any variables not found
+   in either *local_vars* or ``os.environ``.
+
+   Note that this is not a fully-fledged string interpolation function. A valid
+   ``$variable`` can consist only of upper and lower case letters, numbers and
+   an underscore. No { } or ( ) style quoting is available.
+
+
+.. function:: split_quoted(s)
+
+   Split a string up according to Unix shell-like rules for quotes and
+   backslashes. In short: words are delimited by spaces, as long as those spaces
+   are not escaped by a backslash, or inside a quoted string. Single and double
+   quotes are equivalent, and the quote characters can be backslash-escaped.
+   The backslash is stripped from any two-character escape sequence, leaving
+   only the escaped character.  The quote characters are stripped from any
+   quoted string.  Returns a list of words.
+
+   .. TODO Should probably be moved into the standard library.
+
+
+.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
+
+   Perform some action that affects the outside world (for instance, writing to
+   the filesystem).  Such actions are special because they are disabled by the
+   *dry_run* flag.  This method takes care of all that bureaucracy for you;
+   all you have to do is supply the function to call and an argument tuple for
+   it (to embody the "external action" being performed), and an optional message
+   to print.
+
+
+.. function:: newer(source, target)
+
+   Return true if *source* exists and is more recently modified than *target*,
+   or if *source* exists and *target* doesn't. Return false if both exist and
+   *target* is the same age or newer than *source*. Raise
+   :exc:`PackagingFileError` if *source* does not exist.
+
+
+.. function:: strtobool(val)
+
+   Convert a string representation of truth to true (1) or false (0).
+
+   True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false
+   values are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``.  Raises
+   :exc:`ValueError` if *val* is anything else.
+
+.. TODO Add :term: markup to bytecode when merging into the stdlib
+
+.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
+
+   Byte-compile a collection of Python source files to either :file:`.pyc` or
+   :file:`.pyo` files in the same directory.  *py_files* is a list of files to
+   compile; any files that don't end in :file:`.py` are silently skipped.
+   *optimize* must be one of the following:
+
+   * ``0`` - don't optimize (generate :file:`.pyc`)
+   * ``1`` - normal optimization (like ``python -O``)
+   * ``2`` - extra optimization (like ``python -OO``)
+
+   If *force* is true, all files are recompiled regardless of timestamps.
+
+   The source filename encoded in each bytecode file defaults to the filenames
+   listed in *py_files*; you can modify these with *prefix* and *basedir*.
+   *prefix* is a string that will be stripped off of each source filename, and
+   *base_dir* is a directory name that will be prepended (after *prefix* is
+   stripped).  You can supply either or both (or neither) of *prefix* and
+   *base_dir*, as you wish.
+
+   If *dry_run* is true, doesn't actually do anything that would affect the
+   filesystem.
+
+   Byte-compilation is either done directly in this interpreter process with the
+   standard :mod:`py_compile` module, or indirectly by writing a temporary
+   script and executing it.  Normally, you should let :func:`byte_compile`
+   figure out to use direct compilation or not (see the source for details).
+   The *direct* flag is used by the script generated in indirect mode; unless
+   you know what you're doing, leave it set to ``None``.
+
+
+.. function:: rfc822_escape(header)
+
+   Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
+   ensuring there are 8 spaces space after each newline.  Note that it does no
+   other modification of the string.
+
+   .. TODO this _can_ be replaced
diff --git a/Doc/library/packaging.version.rst b/Doc/library/packaging.version.rst
new file mode 100644
index 0000000000..f36cdaba10
--- /dev/null
+++ b/Doc/library/packaging.version.rst
@@ -0,0 +1,104 @@
+:mod:`packaging.version` --- Version number classes
+===================================================
+
+.. module:: packaging.version
+   :synopsis: Classes that represent project version numbers.
+
+
+This module contains classes and functions useful to deal with version numbers.
+It's an implementation of version specifiers `as defined in PEP 345
+<http://www.python.org/dev/peps/pep-0345/#version-specifiers>`_.
+
+
+Version numbers
+---------------
+
+.. class:: NormalizedVersion(self, s, error_on_huge_major_num=True)
+
+   A specific version of a distribution, as described in PEP 345.  *s* is a
+   string object containing the version number (for example ``'1.2b1'``),
+   *error_on_huge_major_num* a boolean specifying whether to consider an
+   apparent use of a year or full date as the major version number an error.
+
+   The rationale for the second argument is that there were projects using years
+   or full dates as version numbers, which could cause problems with some
+   packaging systems sorting.
+
+   Instances of this class can be compared and sorted::
+
+      >>> NormalizedVersion('1.2b1') < NormalizedVersion('1.2')
+      True
+
+   :class:`NormalizedVersion` is used internally by :class:`VersionPredicate` to
+   do its work.
+
+
+.. class:: IrrationalVersionError
+
+   Exception raised when an invalid string is given to
+   :class:`NormalizedVersion`.
+
+      >>> NormalizedVersion("irrational_version_number")
+      ...
+      IrrationalVersionError: irrational_version_number
+
+
+.. function:: suggest_normalized_version(s)
+
+   Before standardization in PEP 386, various schemes were in use.  Packaging
+   provides a function to try to convert any string to a valid, normalized
+   version::
+
+      >>> suggest_normalized_version('2.1-rc1')
+      2.1c1
+
+
+   If :func:`suggest_normalized_version` can't make sense of the given string,
+   it will return ``None``::
+
+      >>> print(suggest_normalized_version('not a version'))
+      None
+
+
+Version predicates
+------------------
+
+.. class:: VersionPredicate(predicate)
+
+   This class deals with the parsing of field values like
+   ``ProjectName (>=version)``.
+
+   .. method:: match(version)
+
+      Test if a version number matches the predicate:
+
+         >>> version = VersionPredicate("ProjectName (<1.2, >1.0)")
+         >>> version.match("1.2.1")
+         False
+         >>> version.match("1.1.1")
+         True
+
+
+Validation helpers
+------------------
+
+If you want to use :term:`LBYL`-style checks instead of instantiating the
+classes and catching :class:`IrrationalVersionError` and :class:`ValueError`,
+you can use these functions:
+
+.. function:: is_valid_version(predicate)
+
+   Check whether the given string is a valid version number.  Example of valid
+   strings: ``'1.2'``,  ``'4.2.0.dev4'``, ``'2.5.4.post2'``.
+
+
+.. function:: is_valid_versions(predicate)
+
+   Check whether the given string is a valid value for specifying multiple
+   versions, such as in the Requires-Python field.  Example: ``'2.7, >=3.2'``.
+
+
+.. function:: is_valid_predicate(predicate)
+
+   Check whether the given string is a valid version predicate.  Examples:
+   ``'some.project == 4.5, <= 4.7'``, ``'speciallib (> 1.0, != 1.4.2, < 2.0)'``.
diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index d8e516633e..5928c5fb98 100644
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -214,6 +214,10 @@ Win95/98 specific
    preferring :func:`win32pipe.popen`.  On Windows NT, :func:`win32pipe.popen`
    should work; on Windows 9x it hangs due to bugs in the MS C library.
 
+   .. deprecated:: 3.3
+      This function is obsolete.  Use the :mod:`subprocess` module.  Check
+      especially the :ref:`subprocess-replacements` section.
+
 
 Mac OS Platform
 ---------------
diff --git a/Doc/library/python.rst b/Doc/library/python.rst
index b67fbfc281..07eadb4faa 100644
--- a/Doc/library/python.rst
+++ b/Doc/library/python.rst
@@ -25,4 +25,5 @@ overview:
    inspect.rst
    site.rst
    fpectl.rst
+   packaging.rst
    distutils.rst
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index f0c4add61a..3040411bb0 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -43,6 +43,12 @@ The :mod:`random` module also provides the :class:`SystemRandom` class which
 uses the system function :func:`os.urandom` to generate random numbers
 from sources provided by the operating system.
 
+.. warning::
+
+   The generators of the :mod:`random` module should not be used for security
+   purposes. Use :func:`ssl.RAND_bytes` if you require a cryptographically
+   secure pseudorandom number generator.
+
 
 Bookkeeping functions:
 
diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index 3046755f29..606825c4c2 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -689,9 +689,12 @@ form.
 
 .. function:: escape(string)
 
-   Return *string* with all non-alphanumerics backslashed; this is useful if you
-   want to match an arbitrary literal string that may have regular expression
-   metacharacters in it.
+   Escape all the characters in pattern except ASCII letters, numbers and ``'_'``.
+   This is useful if you want to match an arbitrary literal string that may
+   have regular expression metacharacters in it.
+
+   .. versionchanged:: 3.3
+      The ``'_'`` character is no longer escaped.
 
 
 .. function:: purge()
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 1a878d5fd0..88c0eaa8db 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -164,6 +164,14 @@ Directory and files operations
    If the destination is on the current filesystem, then simply use rename.
    Otherwise, copy src (with :func:`copy2`) to the dst and then remove src.
 
+.. function:: disk_usage(path)
+
+   Return disk usage statistics about the given path as a namedtuple including
+   total, used and free space expressed in bytes.
+
+   .. versionadded:: 3.3
+
+   Availability: Unix, Windows.
 
 .. exception:: Error
 
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 698b1e74f4..9bca72e217 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -13,9 +13,6 @@ rules for working with signals and their handlers:
   underlying implementation), with the exception of the handler for
   :const:`SIGCHLD`, which follows the underlying implementation.
 
-* There is no way to "block" signals temporarily from critical sections (since
-  this is not supported by all Unix flavors).
-
 * Although Python signal handlers are called asynchronously as far as the Python
   user is concerned, they can only occur between the "atomic" instructions of the
   Python interpreter.  This means that signals arriving during long calculations
@@ -119,6 +116,28 @@ The variables defined in the :mod:`signal` module are:
    in user and kernel space. SIGPROF is delivered upon expiration.
 
 
+.. data:: SIG_BLOCK
+
+   A possible value for the *how* parameter to :func:`pthread_sigmask`
+   indicating that signals are to be blocked.
+
+   .. versionadded:: 3.3
+
+.. data:: SIG_UNBLOCK
+
+   A possible value for the *how* parameter to :func:`pthread_sigmask`
+   indicating that signals are to be unblocked.
+
+   .. versionadded:: 3.3
+
+.. data:: SIG_SETMASK
+
+   A possible value for the *how* parameter to :func:`pthread_sigmask`
+   indicating that the signal mask is to be replaced.
+
+   .. versionadded:: 3.3
+
+
 The :mod:`signal` module defines one exception:
 
 .. exception:: ItimerError
@@ -160,6 +179,60 @@ The :mod:`signal` module defines the following functions:
    will then be called.  Returns nothing.  Not on Windows. (See the Unix man page
    :manpage:`signal(2)`.)
 
+   See also :func:`sigwait`, :func:`sigwaitinfo`, :func:`sigtimedwait` and
+   :func:`sigpending`.
+
+
+.. function:: pthread_kill(thread_id, signum)
+
+   Send the signal *signum* to the thread *thread_id*, another thread in the same
+   process as the caller.  The signal is asynchronously directed to thread.
+
+   Use :func:`threading.get_ident()` or the :attr:`~threading.Thread.ident`
+   attribute of :attr:`threading.Thread` to get a 'thread identifier' for
+   *thread_id*.
+
+   If *signum* is 0, then no signal is sent, but error checking is still
+   performed; this can be used to check if a thread is still running.
+
+   Availability: Unix (see the man page :manpage:`pthread_kill(3)` for further
+   information).
+
+   See also :func:`os.kill`.
+
+   .. versionadded:: 3.3
+
+
+.. function:: pthread_sigmask(how, mask)
+
+   Fetch and/or change the signal mask of the calling thread.  The signal mask
+   is the set of signals whose delivery is currently blocked for the caller.
+   Return the old signal mask as a set of signals.
+
+   The behavior of the call is dependent on the value of *how*, as follows.
+
+    * :data:`SIG_BLOCK`: The set of blocked signals is the union of the current
+      set and the *mask* argument.
+    * :data:`SIG_UNBLOCK`: The signals in *mask* are removed from the current
+      set of blocked signals.  It is permissible to attempt to unblock a
+      signal which is not blocked.
+    * :data:`SIG_SETMASK`: The set of blocked signals is set to the *mask*
+      argument.
+
+   *mask* is a set of signal numbers (e.g. {:const:`signal.SIGINT`,
+   :const:`signal.SIGTERM`}). Use ``range(1, signal.NSIG)`` for a full mask
+   including all signals.
+
+   For example, ``signal.pthread_sigmask(signal.SIG_BLOCK, [])`` reads the
+   signal mask of the calling thread.
+
+   Availability: Unix. See the man page :manpage:`sigprocmask(3)` and
+   :manpage:`pthread_sigmask(3)` for further information.
+
+   See also :func:`pause`, :func:`sigpending` and :func:`sigwait`.
+
+   .. versionadded:: 3.3
+
 
 .. function:: setitimer(which, seconds[, interval])
 
@@ -189,13 +262,17 @@ The :mod:`signal` module defines the following functions:
 
 .. function:: set_wakeup_fd(fd)
 
-   Set the wakeup fd to *fd*.  When a signal is received, a ``'\0'`` byte is
-   written to the fd.  This can be used by a library to wakeup a poll or select
-   call, allowing the signal to be fully processed.
+   Set the wakeup file descriptor to *fd*.  When a signal is received, the
+   signal number is written as a single byte into the fd.  This can be used by
+   a library to wakeup a poll or select call, allowing the signal to be fully
+   processed.
 
    The old wakeup fd is returned.  *fd* must be non-blocking.  It is up to the
    library to remove any bytes before calling poll or select again.
 
+   Use for example ``struct.unpack('%uB' % len(data), data)`` to decode the
+   signal numbers list.
+
    When threads are enabled, this function can only be called from the main thread;
    attempting to call it from other threads will cause a :exc:`ValueError`
    exception to be raised.
@@ -235,6 +312,74 @@ The :mod:`signal` module defines the following functions:
    :const:`SIGTERM`. A :exc:`ValueError` will be raised in any other case.
 
 
+.. function:: sigpending()
+
+   Examine the set of signals that are pending for delivery to the calling
+   thread (i.e., the signals which have been raised while blocked).  Return the
+   set of the pending signals.
+
+   Availability: Unix (see the man page :manpage:`sigpending(2)` for further
+   information).
+
+   See also :func:`pause`, :func:`pthread_sigmask` and :func:`sigwait`.
+
+   .. versionadded:: 3.3
+
+
+.. function:: sigwait(sigset)
+
+   Suspend execution of the calling thread until the delivery of one of the
+   signals specified in the signal set *sigset*.  The function accepts the signal
+   (removes it from the pending list of signals), and returns the signal number.
+
+   Availability: Unix (see the man page :manpage:`sigwait(3)` for further
+   information).
+
+   See also :func:`pause`, :func:`pthread_sigmask`, :func:`sigpending`,
+   :func:`sigwaitinfo` and :func:`sigtimedwait`.
+
+   .. versionadded:: 3.3
+
+
+.. function:: sigwaitinfo(sigset)
+
+   Suspend execution of the calling thread until the delivery of one of the
+   signals specified in the signal set *sigset*.  The function accepts the
+   signal and removes it from the pending list of signals. If one of the
+   signals in *sigset* is already pending for the calling thread, the function
+   will return immediately with information about that signal. The signal
+   handler is not called for the delivered signal. The function raises an
+   :exc:`OSError` with error number set to :const:`errno.EINTR` if it is
+   interrupted by a signal that is not in *sigset*.
+
+   The return value is an object representing the data contained in the
+   :c:type:`siginfo_t` structure, namely: :attr:`si_signo`, :attr:`si_code`,
+   :attr:`si_errno`, :attr:`si_pid`, :attr:`si_uid`, :attr:`si_status`,
+   :attr:`si_band`.
+
+   Availability: Unix (see the man page :manpage:`sigwaitinfo(2)` for further
+   information).
+
+   See also :func:`pause`, :func:`sigwait` and :func:`sigtimedwait`.
+
+   .. versionadded:: 3.3
+
+
+.. function:: sigtimedwait(sigset, (timeout_sec, timeout_nsec))
+
+   Like :func:`sigtimedwait`, but takes a tuple of ``(seconds, nanoseconds)``
+   as an additional argument specifying a timeout. If both *timeout_sec* and
+   *timeout_nsec* are specified as :const:`0`, a poll is performed. Returns
+   :const:`None` if a timeout occurs.
+
+   Availability: Unix (see the man page :manpage:`sigtimedwait(2)` for further
+   information).
+
+   See also :func:`pause`, :func:`sigwait` and :func:`sigwaitinfo`.
+
+   .. versionadded:: 3.3
+
+
 .. _signal-example:
 
 Example
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index b77f3cf02d..46bd5dc6bd 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -13,7 +13,15 @@ import can be suppressed using the interpreter's :option:`-S` option.
 
 .. index:: triple: module; search; path
 
-Importing this module will append site-specific paths to the module search path.
+Importing this module will append site-specific paths to the module search
+path, unless :option:`-S` was used.  In that case, this module can be safely
+imported with no automatic modifications to the module search path.  To
+explicitly trigger the usual site-specific additions, call the
+:func:`site.main` function.
+
+.. versionchanged:: 3.3
+   Importing the module used to trigger paths manipulation even when using
+   :option:`-S`.
 
 .. index::
    pair: site-python; directory
@@ -114,6 +122,17 @@ empty, and the path manipulations are skipped; however the import of
 .. envvar:: PYTHONUSERBASE
 
 
+.. function:: main()
+
+   Adds all the standard site-specific directories to the module search
+   path.  This function is called automatically when this module is imported,
+   unless the :program:`python` interpreter was started with the :option:`-S`
+   flag.
+
+   .. versionchanged:: 3.3
+      This function used to be called unconditionnally.
+
+
 .. function:: addsitedir(sitedir, known_paths=None)
 
    Adds a directory to sys.path and processes its pth files.
diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst
index 5978a8fe9d..24aff0589b 100644
--- a/Doc/library/smtplib.rst
+++ b/Doc/library/smtplib.rst
@@ -34,8 +34,22 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
    For normal use, you should only require the initialization/connect,
    :meth:`sendmail`, and :meth:`quit` methods.  An example is included below.
 
+   The :class:`SMTP` class supports the :keyword:`with` statement.  When used
+   like this, the SMTP ``QUIT`` command is issued automatically when the
+   :keyword:`with` statement exits.  E.g.::
 
-.. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None[, timeout])
+    >>> from smtplib import SMTP
+    >>> with SMTP("domain.org") as smtp:
+    ...     smtp.noop()
+    ...
+    (250, b'Ok')
+    >>>
+
+   .. versionchanged:: 3.3
+      Support for the :keyword:`with` statement was added.
+
+
+.. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None[, timeout], context=None)
 
    A :class:`SMTP_SSL` instance behaves exactly the same as instances of
    :class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is
@@ -43,11 +57,16 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions).
    not appropriate. If *host* is not specified, the local host is used. If
    *port* is zero, the standard SMTP-over-SSL port (465) is used. *keyfile*
    and *certfile* are also optional, and can contain a PEM formatted private key
-   and certificate chain file for the SSL connection. The optional *timeout*
+   and certificate chain file for the SSL connection. *context* also optional, can contain
+   a SSLContext, and is an alternative to keyfile and certfile; If it is specified both
+   keyfile and certfile must be None.  The optional *timeout*
    parameter specifies a timeout in seconds for blocking operations like the
    connection attempt (if not specified, the global default timeout setting
    will be used).
 
+   .. versionchanged:: 3.3
+      *context* was added.
+
 
 .. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None)
 
@@ -242,7 +261,7 @@ An :class:`SMTP` instance has the following methods:
       No suitable authentication method was found.
 
 
-.. method:: SMTP.starttls(keyfile=None, certfile=None)
+.. method:: SMTP.starttls(keyfile=None, certfile=None, context=None)
 
    Put the SMTP connection in TLS (Transport Layer Security) mode.  All SMTP
    commands that follow will be encrypted.  You should then call :meth:`ehlo`
@@ -251,6 +270,9 @@ An :class:`SMTP` instance has the following methods:
    If *keyfile* and *certfile* are provided, these are passed to the :mod:`socket`
    module's :func:`ssl` function.
 
+   Optional *context* parameter is a :class:`ssl.SSLContext` object; This is an alternative to
+   using a keyfile and a certfile and if specified both *keyfile* and *certfile* should be None.
+
    If there has been no previous ``EHLO`` or ``HELO`` command this session,
    this method tries ESMTP ``EHLO`` first.
 
@@ -263,6 +285,9 @@ An :class:`SMTP` instance has the following methods:
    :exc:`RuntimeError`
      SSL/TLS support is not available to your Python interpreter.
 
+   .. versionchanged:: 3.3
+      *context* was added.
+
 
 .. method:: SMTP.sendmail(from_addr, to_addrs, msg, mail_options=[], rcpt_options=[])
 
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 14cd4ff5ce..afc674cd69 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -526,6 +526,49 @@ The module :mod:`socket` exports the following constants and functions:
    meanings.
 
 
+.. function:: sethostname(name)
+
+   Set the machine's hostname to *name*.  This will raise a
+   :exc:`socket.error` if you don't have enough rights.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: if_nameindex()
+
+   Return a list of network interface information
+   (index int, name string) tuples.
+   :exc:`socket.error` if the system call fails.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: if_nametoindex(if_name)
+
+   Return a network interface index number corresponding to an
+   interface name.
+   :exc:`socket.error` if no interface with the given name exists.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. function:: if_indextoname(if_index)
+
+   Return a network interface name corresponding to a
+   interface index number.
+   :exc:`socket.error` if no interface with the given index exists.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
 .. data:: SocketType
 
    This is a Python type object that represents the socket object type. It is the
diff --git a/Doc/library/socketserver.rst b/Doc/library/socketserver.rst
index 1d151a7fe6..b63571dfb9 100644
--- a/Doc/library/socketserver.rst
+++ b/Doc/library/socketserver.rst
@@ -153,8 +153,21 @@ Server Objects
 .. method:: BaseServer.serve_forever(poll_interval=0.5)
 
    Handle requests until an explicit :meth:`shutdown` request.  Polls for
-   shutdown every *poll_interval* seconds.
+   shutdown every *poll_interval* seconds. It also calls
+   :meth:`service_actions` which may be used by a subclass or Mixin to provide
+   various cleanup actions. For e.g. ForkingMixin class uses
+   :meth:`service_actions` to cleanup the zombie child processes.
 
+   .. versionchanged:: 3.3
+       Added service_actions call to the serve_forever method.
+
+
+.. method:: BaseServer.service_actions()
+
+   This is called by the serve_forever loop. This method is can be overridden
+   by Mixin's to add cleanup or service specific actions.
+
+   .. versionadded:: 3.3
 
 .. method:: BaseServer.shutdown()
 
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 32ae7244e3..299be038fd 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -369,6 +369,22 @@ Connection Objects
    method with :const:`None` for *handler*.
 
 
+.. method:: Connection.set_trace_callback(trace_callback)
+
+   Registers *trace_callback* to be called for each SQL statement that is
+   actually executed by the SQLite backend.
+
+   The only argument passed to the callback is the statement (as string) that
+   is being executed. The return value of the callback is ignored. Note that
+   the backend does not only run statements passed to the :meth:`Cursor.execute`
+   methods.  Other sources include the transaction management of the Python
+   module and the execution of triggers defined in the current database.
+
+   Passing :const:`None` as *trace_callback* will disable the trace callback.
+
+   .. versionadded:: 3.3
+
+
 .. method:: Connection.enable_load_extension(enabled)
 
    This routine allows/disallows the SQLite engine to load SQLite extensions
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 09a2961184..ca71d20405 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -162,6 +162,35 @@ instead.
 Random generation
 ^^^^^^^^^^^^^^^^^
 
+.. function:: RAND_bytes(num)
+
+   Returns *num* cryptographically strong pseudo-random bytes. Raises an
+   :class:`SSLError` if the PRNG has not been seeded with enough data or if the
+   operation is not supported by the current RAND method. :func:`RAND_status`
+   can be used to check the status of the PRNG and :func:`RAND_add` can be used
+   to seed the PRNG.
+
+   Read the Wikipedia article, `Cryptographically secure pseudorandom number
+   generator (CSPRNG)
+   <http://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator>`_,
+   to get the requirements of a cryptographically generator.
+
+   .. versionadded:: 3.3
+
+.. function:: RAND_pseudo_bytes(num)
+
+   Returns (bytes, is_cryptographic): bytes are *num* pseudo-random bytes,
+   is_cryptographic is True if the bytes generated are cryptographically
+   strong. Raises an :class:`SSLError` if the operation is not supported by the
+   current RAND method.
+
+   Generated pseudo-random byte sequences will be unique if they are of
+   sufficient length, but are not necessarily unpredictable. They can be used
+   for non-cryptographic purposes and for certain purposes in cryptographic
+   protocols, but usually not for key generation etc.
+
+   .. versionadded:: 3.3
+
 .. function:: RAND_status()
 
    Returns True if the SSL pseudo-random number generator has been seeded with
@@ -171,7 +200,7 @@ Random generation
 
 .. function:: RAND_egd(path)
 
-   If you are running an entropy-gathering daemon (EGD) somewhere, and ``path``
+   If you are running an entropy-gathering daemon (EGD) somewhere, and *path*
    is the pathname of a socket connection open to it, this will read 256 bytes
    of randomness from the socket, and add it to the SSL pseudo-random number
    generator to increase the security of generated secret keys.  This is
@@ -182,8 +211,8 @@ Random generation
 
 .. function:: RAND_add(bytes, entropy)
 
-   Mixes the given ``bytes`` into the SSL pseudo-random number generator.  The
-   parameter ``entropy`` (a float) is a lower bound on the entropy contained in
+   Mixes the given *bytes* into the SSL pseudo-random number generator.  The
+   parameter *entropy* (a float) is a lower bound on the entropy contained in
    string (so you can always use :const:`0.0`).  See :rfc:`1750` for more
    information on sources of entropy.
 
@@ -239,6 +268,9 @@ Certificate handling
    will attempt to validate the server certificate against that set of root
    certificates, and will fail if the validation attempt fails.
 
+   .. versionchanged:: 3.3
+      This function is now IPv6-compatible.
+
 .. function:: DER_cert_to_PEM_cert(DER_cert_bytes)
 
    Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index f0933a55bb..c72b63ec1d 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1661,6 +1661,8 @@ Note that while lists allow their items to be of any type, bytearray object
    single: append() (sequence method)
    single: extend() (sequence method)
    single: count() (sequence method)
+   single: clear() (sequence method)
+   single: copy() (sequence method)
    single: index() (sequence method)
    single: insert() (sequence method)
    single: pop() (sequence method)
@@ -1692,6 +1694,12 @@ Note that while lists allow their items to be of any type, bytearray object
 | ``s.extend(x)``              | same as ``s[len(s):len(s)] =   | \(2)                |
 |                              | x``                            |                     |
 +------------------------------+--------------------------------+---------------------+
+| ``s.clear()``                | remove all items from ``s``    |                     |
+|                              |                                |                     |
++------------------------------+--------------------------------+---------------------+
+| ``s.copy()``                 | return a shallow copy of ``s`` |                     |
+|                              |                                |                     |
++------------------------------+--------------------------------+---------------------+
 | ``s.count(x)``               | return number of *i*'s for     |                     |
 |                              | which ``s[i] == x``            |                     |
 +------------------------------+--------------------------------+---------------------+
@@ -1770,6 +1778,9 @@ Notes:
 (8)
    :meth:`sort` is not supported by :class:`bytearray` objects.
 
+    .. versionadded:: 3.3
+       :meth:`clear` and :meth:`!copy` methods.
+
 
 .. _bytes-methods:
 
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 16c2605acc..7e759f0d03 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -123,12 +123,14 @@ This module defines one class called :class:`Popen`:
 
    *stdin*, *stdout* and *stderr* specify the executed programs' standard input,
    standard output and standard error file handles, respectively.  Valid values
-   are :data:`PIPE`, an existing file descriptor (a positive integer), an
-   existing :term:`file object`, and ``None``.  :data:`PIPE` indicates that a
-   new pipe to the child should be created.  With ``None``, no redirection will
-   occur; the child's file handles will be inherited from the parent.  Additionally,
-   *stderr* can be :data:`STDOUT`, which indicates that the stderr data from the
-   applications should be captured into the same file handle as for stdout.
+   are :data:`PIPE`, :data:`DEVNULL`, an existing file descriptor (a positive
+   integer), an existing :term:`file object`, and ``None``.  :data:`PIPE`
+   indicates that a new pipe to the child should be created.  :data:`DEVNULL`
+   indicates that the special file :data:`os.devnull` will be used. With ``None``,
+   no redirection will occur; the child's file handles will be inherited from
+   the parent.  Additionally, *stderr* can be :data:`STDOUT`, which indicates
+   that the stderr data from the applications should be captured into the same
+   file handle as for stdout.
 
    If *preexec_fn* is set to a callable object, this object will be called in the
    child process just before the child is executed.
@@ -228,6 +230,15 @@ This module defines one class called :class:`Popen`:
       Added context manager support.
 
 
+.. data:: DEVNULL
+
+   Special value that can be used as the *stdin*, *stdout* or *stderr* argument
+   to :class:`Popen` and indicates that the special file :data:`os.devnull`
+   will be used.
+
+   .. versionadded:: 3.3
+
+
 .. data:: PIPE
 
    Special value that can be used as the *stdin*, *stdout* or *stderr* argument
@@ -248,15 +259,21 @@ Convenience Functions
 This module also defines the following shortcut functions:
 
 
-.. function:: call(*popenargs, **kwargs)
+.. function:: call(*popenargs, timeout=None, **kwargs)
 
    Run command with arguments.  Wait for command to complete, then return the
    :attr:`returncode` attribute.
 
-   The arguments are the same as for the :class:`Popen` constructor.  Example::
+   The arguments are the same as for the :class:`Popen` constructor, with the
+   exception of the *timeout* argument, which is given to :meth:`Popen.wait`.
+   Example::
 
       >>> retcode = subprocess.call(["ls", "-l"])
 
+   If the timeout expires, the child process will be killed and then waited for
+   again.  The :exc:`TimeoutExpired` exception will be re-raised after the child
+   process has terminated.
+
    .. warning::
 
       Like :meth:`Popen.wait`, this will deadlock when using
@@ -264,34 +281,43 @@ This module also defines the following shortcut functions:
       generates enough output to a pipe such that it blocks waiting
       for the OS pipe buffer to accept more data.
 
+   .. versionchanged:: 3.3
+      *timeout* was added.
+
 
-.. function:: check_call(*popenargs, **kwargs)
+.. function:: check_call(*popenargs, timeout=None, **kwargs)
 
    Run command with arguments.  Wait for command to complete. If the exit code was
    zero then return, otherwise raise :exc:`CalledProcessError`. The
    :exc:`CalledProcessError` object will have the return code in the
    :attr:`returncode` attribute.
 
-   The arguments are the same as for the :class:`Popen` constructor.  Example::
+   The arguments are the same as for the :func:`call` function.  Example::
 
       >>> subprocess.check_call(["ls", "-l"])
       0
 
+   As in the :func:`call` function, if the timeout expires, the child process
+   will be killed and the wait retried.  The :exc:`TimeoutExpired` exception
+   will be re-raised after the child process has terminated.
+
    .. warning::
 
       See the warning for :func:`call`.
 
+   .. versionchanged:: 3.3
+      *timeout* was added.
 
-.. function:: check_output(*popenargs, **kwargs)
 
-   Run command with arguments and return its output as a byte string.
+.. function:: check_output(*popenargs, timeout=None, **kwargs)
+
+   Run command with arguments and return its output as a bytes object.
 
    If the exit code was non-zero it raises a :exc:`CalledProcessError`.  The
    :exc:`CalledProcessError` object will have the return code in the
-   :attr:`returncode`
-   attribute and output in the :attr:`output` attribute.
+   :attr:`returncode` attribute and output in the :attr:`output` attribute.
 
-   The arguments are the same as for the :class:`Popen` constructor.  Example::
+   The arguments are the same as for the :func:`call` function.  Example::
 
       >>> subprocess.check_output(["ls", "-l", "/dev/null"])
       b'crw-rw-rw- 1 root root 1, 3 Oct 18  2007 /dev/null\n'
@@ -304,8 +330,17 @@ This module also defines the following shortcut functions:
       ...     stderr=subprocess.STDOUT)
       b'ls: non_existent_file: No such file or directory\n'
 
+   As in the :func:`call` function, if the timeout expires, the child process
+   will be killed and the wait retried.  The :exc:`TimeoutExpired` exception
+   will be re-raised after the child process has terminated.  The output from
+   the child process so far will be in the :attr:`output` attribute of the
+   exception.
+
    .. versionadded:: 3.1
 
+   .. versionchanged:: 3.3
+      *timeout* was added.
+
 
 .. function:: getstatusoutput(cmd)
 
@@ -358,6 +393,15 @@ arguments.
 check_call() will raise :exc:`CalledProcessError`, if the called process returns
 a non-zero return code.
 
+All of the functions and methods that accept a *timeout* parameter, such as
+:func:`call` and :meth:`Popen.communicate` will raise :exc:`TimeoutExpired` if
+the timeout expires before the process exits.
+
+Exceptions defined in this module all inherit from :exc:`SubprocessError`.
+
+   .. versionadded:: 3.3
+      The :exc:`SubprocessError` base class was added.
+
 
 Security
 ^^^^^^^^
@@ -379,11 +423,15 @@ Instances of the :class:`Popen` class have the following methods:
    attribute.
 
 
-.. method:: Popen.wait()
+.. method:: Popen.wait(timeout=None)
 
    Wait for child process to terminate.  Set and return :attr:`returncode`
    attribute.
 
+   If the process does not terminate after *timeout* seconds, raise a
+   :exc:`TimeoutExpired` exception.  It is safe to catch this exception and
+   retry the wait.
+
    .. warning::
 
       This will deadlock when using ``stdout=PIPE`` and/or
@@ -391,13 +439,17 @@ Instances of the :class:`Popen` class have the following methods:
       a pipe such that it blocks waiting for the OS pipe buffer to
       accept more data.  Use :meth:`communicate` to avoid that.
 
+   .. versionchanged:: 3.3
+      *timeout* was added.
 
-.. method:: Popen.communicate(input=None)
+
+.. method:: Popen.communicate(input=None, timeout=None)
 
    Interact with process: Send data to stdin.  Read data from stdout and stderr,
-   until end-of-file is reached.  Wait for process to terminate. The optional
-   *input* argument should be a byte string to be sent to the child process, or
-   ``None``, if no data should be sent to the child.
+   until end-of-file is reached.  Wait for process to terminate.  The optional
+   *input* argument should be data to be sent to the child process, or
+   ``None``, if no data should be sent to the child.  The type of *input*
+   must be bytes or, if *universal_newlines* was ``True``, a string.
 
    :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``.
 
@@ -406,11 +458,29 @@ Instances of the :class:`Popen` class have the following methods:
    ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
    ``stderr=PIPE`` too.
 
+   If the process does not terminate after *timeout* seconds, a
+   :exc:`TimeoutExpired` exception will be raised.  Catching this exception and
+   retrying communication will not lose any output.
+
+   The child process is not killed if the timeout expires, so in order to
+   cleanup properly a well-behaved application should kill the child process and
+   finish communication::
+
+      proc = subprocess.Popen(...)
+      try:
+          outs, errs = proc.communicate(timeout=15)
+      except TimeoutExpired:
+          proc.kill()
+          outs, errs = proc.communicate()
+
    .. note::
 
       The data read is buffered in memory, so do not use this method if the data
       size is large or unlimited.
 
+   .. versionchanged:: 3.3
+      *timeout* was added.
+
 
 .. method:: Popen.send_signal(signal)
 
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index ae2dbf3044..dfc2412196 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -36,18 +36,6 @@ always available.
    little-endian (least-significant byte first) platforms.
 
 
-.. data:: subversion
-
-   A triple (repo, branch, version) representing the Subversion information of the
-   Python interpreter. *repo* is the name of the repository, ``'CPython'``.
-   *branch* is a string of one of the forms ``'trunk'``, ``'branches/name'`` or
-   ``'tags/name'``. *version* is the output of ``svnversion``, if the interpreter
-   was built from a Subversion checkout; it contains the revision number (range)
-   and possibly a trailing 'M' if there were local modifications. If the tree was
-   exported (or svnversion was not available), it is the revision of
-   ``Include/patchlevel.h`` if the branch is a tag. Otherwise, it is ``None``.
-
-
 .. data:: builtin_module_names
 
    A tuple of strings giving the names of all modules that are compiled into this
@@ -236,14 +224,13 @@ always available.
 
 .. data:: flags
 
-   The struct sequence *flags* exposes the status of command line flags. The
-   attributes are read only.
+   The :term:`struct sequence` *flags* exposes the status of command line
+   flags. The attributes are read only.
 
    ============================= =============================
    attribute                     flag
    ============================= =============================
    :const:`debug`                :option:`-d`
-   :const:`division_warning`     :option:`-Q`
    :const:`inspect`              :option:`-i`
    :const:`interactive`          :option:`-i`
    :const:`optimize`             :option:`-O` or :option:`-OO`
@@ -259,15 +246,18 @@ always available.
    .. versionchanged:: 3.2
       Added ``quiet`` attribute for the new :option:`-q` flag.
 
+   .. versionchanged:: 3.3
+      Removed obsolete ``division_warning`` attribute.
+
 
 .. data:: float_info
 
-   A structseq holding information about the float type. It contains low level
-   information about the precision and internal representation.  The values
-   correspond to the various floating-point constants defined in the standard
-   header file :file:`float.h` for the 'C' programming language; see section
-   5.2.4.2.2 of the 1999 ISO/IEC C standard [C99]_, 'Characteristics of
-   floating types', for details.
+   A :term:`struct sequence` holding information about the float type. It
+   contains low level information about the precision and internal
+   representation.  The values correspond to the various floating-point
+   constants defined in the standard header file :file:`float.h` for the 'C'
+   programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard
+   [C99]_, 'Characteristics of floating types', for details.
 
    +---------------------+----------------+--------------------------------------------------+
    | attribute           | float.h macro  | explanation                                      |
@@ -513,8 +503,9 @@ always available.
 
 .. data:: hash_info
 
-   A structseq giving parameters of the numeric hash implementation.  For
-   more details about hashing of numeric types, see :ref:`numeric-hash`.
+   A :term:`struct sequence` giving parameters of the numeric hash
+   implementation.  For more details about hashing of numeric types, see
+   :ref:`numeric-hash`.
 
    +---------------------+--------------------------------------------------+
    | attribute           | explanation                                      |
@@ -549,8 +540,8 @@ always available.
 
    This is called ``hexversion`` since it only really looks meaningful when viewed
    as the result of passing it to the built-in :func:`hex` function.  The
-   struct sequence  :data:`sys.version_info` may be used for a more human-friendly
-   encoding of the same information.
+   :term:`struct sequence`  :data:`sys.version_info` may be used for a more
+   human-friendly encoding of the same information.
 
    The ``hexversion`` is a 32-bit number with the following layout:
 
@@ -578,8 +569,8 @@ always available.
 
 .. data:: int_info
 
-   A struct sequence that holds information about Python's
-   internal representation of integers.  The attributes are read only.
+   A :term:`struct sequence` that holds information about Python's internal
+   representation of integers.  The attributes are read only.
 
    +-------------------------+----------------------------------------------+
    | Attribute               | Explanation                                  |
@@ -970,6 +961,35 @@ always available.
        to a console and Python apps started with :program:`pythonw`.
 
 
+.. data:: thread_info
+
+   A :term:`struct sequence` holding information about the thread
+   implementation.
+
+   +------------------+---------------------------------------------------------+
+   | Attribute        | Explanation                                             |
+   +==================+=========================================================+
+   | :const:`name`    | Name of the thread implementation:                      |
+   |                  |                                                         |
+   |                  |  * ``'nt'``: Windows threads                            |
+   |                  |  * ``'os2'``: OS/2 threads                              |
+   |                  |  * ``'pthread'``: POSIX threads                         |
+   |                  |  * ``'solaris'``: Solaris threads                       |
+   +------------------+---------------------------------------------------------+
+   | :const:`lock`    | Name of the lock implementation:                        |
+   |                  |                                                         |
+   |                  |  * ``'semaphore'``: a lock uses a semaphore             |
+   |                  |  * ``'mutex+cond'``: a lock uses a mutex                |
+   |                  |    and a condition variable                             |
+   |                  |  * ``None`` if this information is unknown              |
+   +------------------+---------------------------------------------------------+
+   | :const:`version` | Name and version of the thread library. It is a string, |
+   |                  | or ``None`` if these informations are unknown.          |
+   +------------------+---------------------------------------------------------+
+
+   .. versionadded:: 3.3
+
+
 .. data:: tracebacklimit
 
    When this variable is set to an integer value, it determines the maximum number
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
index fff6c4eb57..dfeb2505ae 100644
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -25,7 +25,7 @@ instead a string of six random characters is used.
 
 Also, all the user-callable functions now take additional arguments which
 allow direct control over the location and name of temporary files.  It is
-no longer necessary to use the global *tempdir* and *template* variables.
+no longer necessary to use the global *tempdir* variable.
 To maintain backward compatibility, the argument order is somewhat odd; it
 is recommended to use keyword arguments for clarity.
 
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 9d02b0a8c5..5656b23b45 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -218,14 +218,14 @@ The :mod:`test.support` module defines the following constants:
 
 .. data:: verbose
 
-   :const:`True` when verbose output is enabled. Should be checked when more
+   ``True`` when verbose output is enabled. Should be checked when more
    detailed information is desired about a running test. *verbose* is set by
    :mod:`test.regrtest`.
 
 
 .. data:: is_jython
 
-   :const:`True` if the running interpreter is Jython.
+   ``True`` if the running interpreter is Jython.
 
 
 .. data:: TESTFN
@@ -233,6 +233,7 @@ The :mod:`test.support` module defines the following constants:
    Set to a name that is safe to use as the name of a temporary file.  Any
    temporary file that is created should be closed and unlinked (removed).
 
+
 The :mod:`test.support` module defines the following functions:
 
 
@@ -244,7 +245,7 @@ The :mod:`test.support` module defines the following functions:
 
 .. function:: is_resource_enabled(resource)
 
-   Return :const:`True` if *resource* is enabled and available. The list of
+   Return ``True`` if *resource* is enabled and available. The list of
    available resources is only set when :mod:`test.regrtest` is executing the
    tests.
 
@@ -253,7 +254,7 @@ The :mod:`test.support` module defines the following functions:
 
    Raise :exc:`ResourceDenied` if *resource* is not available. *msg* is the
    argument to :exc:`ResourceDenied` if it is raised. Always returns
-   :const:`True` if called by a function whose ``__name__`` is ``'__main__'``.
+   ``True`` if called by a function whose ``__name__`` is ``'__main__'``.
    Used when tests are executed by :mod:`test.regrtest`.
 
 
@@ -281,6 +282,15 @@ The :mod:`test.support` module defines the following functions:
    This will run all tests defined in the named module.
 
 
+.. function:: run_doctest(module, verbosity=None)
+
+   Run :func:`doctest.testmod` on the given *module*.  Return
+   ``(failure_count, test_count)``.
+
+   If *verbosity* is ``None``, :func:`doctest.testmod` is run with verbosity
+   set to :data:`verbose`.  Otherwise, it is run with verbosity set to
+   ``None``.
+
 .. function:: check_warnings(\*filters, quiet=True)
 
    A convenience wrapper for :func:`warnings.catch_warnings()` that makes it
@@ -291,12 +301,12 @@ The :mod:`test.support` module defines the following functions:
 
    ``check_warnings`` accepts 2-tuples of the form ``("message regexp",
    WarningCategory)`` as positional arguments. If one or more *filters* are
-   provided, or if the optional keyword argument *quiet* is :const:`False`,
+   provided, or if the optional keyword argument *quiet* is ``False``,
    it checks to make sure the warnings are as expected:  each specified filter
    must match at least one of the warnings raised by the enclosed code or the
    test fails, and if any warnings are raised that do not match any of the
    specified filters the test fails.  To disable the first of these checks,
-   set *quiet* to :const:`True`.
+   set *quiet* to ``True``.
 
    If no arguments are specified, it defaults to::
 
@@ -311,7 +321,7 @@ The :mod:`test.support` module defines the following functions:
    representing the most recent warning can also be accessed directly through
    the recorder object (see example below).  If no warning has been raised,
    then any of the attributes that would otherwise be expected on an object
-   representing a warning will return :const:`None`.
+   representing a warning will return ``None``.
 
    The recorder object also has a :meth:`reset` method, which clears the
    warnings list.
@@ -349,7 +359,7 @@ The :mod:`test.support` module defines the following functions:
 
 .. function:: captured_stdout()
 
-   This is a context manager that runs the :keyword:`with` statement body using
+   A context manager that runs the :keyword:`with` statement body using
    a :class:`StringIO.StringIO` object as sys.stdout.  That object can be
    retrieved using the ``as`` clause of the :keyword:`with` statement.
 
@@ -360,6 +370,50 @@ The :mod:`test.support` module defines the following functions:
       assert s.getvalue() == "hello"
 
 
+.. function:: temp_cwd(name='tempcwd', quiet=False, path=None)
+
+   A context manager that temporarily changes the current working
+   directory (CWD).
+
+   An existing path may be provided as *path*, in which case this function
+   makes no changes to the file system.
+
+   Otherwise, the new CWD is created in the current directory and it's named
+   *name*.  If *quiet* is ``False`` and it's not possible to create or
+   change the CWD, an error is raised.  If it's ``True``, only a warning
+   is raised and the original CWD is used.
+
+
+.. function:: temp_umask(umask)
+
+   A context manager that temporarily sets the process umask.
+
+
+.. function:: can_symlink()
+
+   Return ``True`` if the OS supports symbolic links, ``False``
+   otherwise.
+
+
+.. function:: skip_unless_symlink()
+
+   A decorator for running tests that require support for symbolic links.
+
+
+.. function:: run_with_locale(catstr, *locales)
+
+   A decorator for running a function in a different locale, correctly
+   resetting it after it has finished.  *catstr* is the locale category as
+   a string (for example ``"LC_ALL"``).  The *locales* passed will be tried
+   sequentially, and the first valid locale will be used.
+
+
+.. function:: make_bad_fd()
+
+   Create an invalid file descriptor by opening and closing a temporary file,
+   and returning its descripor.
+
+
 .. function:: import_module(name, deprecated=False)
 
    This function imports and returns the named module. Unlike a normal
@@ -367,7 +421,7 @@ The :mod:`test.support` module defines the following functions:
    cannot be imported.
 
    Module and package deprecation messages are suppressed during this import
-   if *deprecated* is :const:`True`.
+   if *deprecated* is ``True``.
 
    .. versionadded:: 3.1
 
@@ -391,7 +445,7 @@ The :mod:`test.support` module defines the following functions:
    ``sys.modules`` when the fresh import is complete.
 
    Module and package deprecation messages are suppressed during this import
-   if *deprecated* is :const:`True`.
+   if *deprecated* is ``True``.
 
    This function will raise :exc:`unittest.SkipTest` is the named module
    cannot be imported.
@@ -408,6 +462,48 @@ The :mod:`test.support` module defines the following functions:
    .. versionadded:: 3.1
 
 
+.. function:: bind_port(sock, host=HOST)
+
+   Bind the socket to a free port and return the port number.  Relies on
+   ephemeral ports in order to ensure we are using an unbound port.  This is
+   important as many tests may be running simultaneously, especially in a
+   buildbot environment.  This method raises an exception if the
+   ``sock.family`` is :const:`~socket.AF_INET` and ``sock.type`` is
+   :const:`~socket.SOCK_STREAM`, and the socket has
+   :const:`~socket.SO_REUSEADDR` or :const:`~socket.SO_REUSEPORT` set on it.
+   Tests should never set these socket options for TCP/IP sockets.
+   The only case for setting these options is testing multicasting via
+   multiple UDP sockets.
+
+   Additionally, if the :const:`~socket.SO_EXCLUSIVEADDRUSE` socket option is
+   available (i.e. on Windows), it will be set on the socket.  This will
+   prevent anyone else from binding to our host/port for the duration of the
+   test.
+
+
+.. function:: find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)
+
+   Returns an unused port that should be suitable for binding.  This is
+   achieved by creating a temporary socket with the same family and type as
+   the ``sock`` parameter (default is :const:`~socket.AF_INET`,
+   :const:`~socket.SOCK_STREAM`),
+   and binding it to the specified host address (defaults to ``0.0.0.0``)
+   with the port set to 0, eliciting an unused ephemeral port from the OS.
+   The temporary socket is then closed and deleted, and the ephemeral port is
+   returned.
+
+   Either this method or :func:`bind_port` should be used for any tests
+   where a server socket needs to be bound to a particular port for the
+   duration of the test.
+   Which one to use depends on whether the calling code is creating a python
+   socket, or if an unused port needs to be provided in a constructor
+   or passed to an external program (i.e. the ``-accept`` argument to
+   openssl's s_server mode).  Always prefer :func:`bind_port` over
+   :func:`find_unused_port` where possible.  Using a hard coded port is
+   discouraged since it can makes multiple instances of the test impossible to
+   run simultaneously, which is a problem for buildbots.
+
+
 The :mod:`test.support` module defines the following classes:
 
 .. class:: TransientResource(exc, **kwargs)
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 5f1b9bfb06..504a2fb1d3 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -20,17 +20,6 @@ The :mod:`dummy_threading` module is provided for situations where
    methods and functions in this module in the Python 2.x series are still
    supported by this module.
 
-.. impl-detail::
-
-   Due to the :term:`Global Interpreter Lock`, in CPython only one thread
-   can execute Python code at once (even though certain performance-oriented
-   libraries might overcome this limitation).
-   If you want your application to make better of use of the computational
-   resources of multi-core machines, you are advised to use
-   :mod:`multiprocessing` or :class:`concurrent.futures.ProcessPoolExecutor`.
-   However, threading is still an appropriate model if you want to run
-   multiple I/O-bound tasks simultaneously.
-
 
 This module defines the following functions and objects:
 
@@ -59,6 +48,17 @@ This module defines the following functions and objects:
    returned.
 
 
+.. function:: get_ident()
+
+   Return the 'thread identifier' of the current thread.  This is a nonzero
+   integer.  Its value has no direct meaning; it is intended as a magic cookie
+   to be used e.g. to index a dictionary of thread-specific data.  Thread
+   identifiers may be recycled when a thread exits and another thread is
+   created.
+
+   .. versionadded:: 3.3
+
+
 .. function:: enumerate()
 
    Return a list of all :class:`Thread` objects currently alive.  The list
@@ -241,7 +241,7 @@ changed through the :attr:`name` attribute.
 A thread can be flagged as a "daemon thread".  The significance of this flag is
 that the entire Python program exits when only daemon threads are left.  The
 initial value is inherited from the creating thread.  The flag can be set
-through the :attr:`daemon` property.
+through the :attr:`daemon` property or the *daemon* constructor argument.
 
 There is a "main thread" object; this corresponds to the initial thread of
 control in the Python program.  It is not a daemon thread.
@@ -254,7 +254,8 @@ daemonic, and cannot be :meth:`join`\ ed.  They are never deleted, since it is
 impossible to detect the termination of alien threads.
 
 
-.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={})
+.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={},
+                  verbose=None, *, daemon=None)
 
    This constructor should always be called with keyword arguments.  Arguments
    are:
@@ -273,10 +274,19 @@ impossible to detect the termination of alien threads.
    *kwargs* is a dictionary of keyword arguments for the target invocation.
    Defaults to ``{}``.
 
+   *verbose* is a flag used for debugging messages.
+
+   If not ``None``, *daemon* explicitly sets whether the thread is daemonic.
+   If ``None`` (the default), the daemonic property is inherited from the
+   current thread.
+
    If the subclass overrides the constructor, it must make sure to invoke the
    base class constructor (``Thread.__init__()``) before doing anything else to
    the thread.
 
+   .. versionchanged:: 3.3
+      Added the *daemon* argument.
+
    .. method:: start()
 
       Start the thread's activity.
@@ -333,10 +343,10 @@ impossible to detect the termination of alien threads.
    .. attribute:: ident
 
       The 'thread identifier' of this thread or ``None`` if the thread has not
-      been started.  This is a nonzero integer.  See the
-      :func:`thread.get_ident()` function.  Thread identifiers may be recycled
-      when a thread exits and another thread is created.  The identifier is
-      available even after the thread has exited.
+      been started.  This is a nonzero integer.  See the :func:`get_ident()`
+      function.  Thread identifiers may be recycled when a thread exits and
+      another thread is created.  The identifier is available even after the
+      thread has exited.
 
    .. method:: is_alive()
 
@@ -364,6 +374,18 @@ impossible to detect the termination of alien threads.
       property instead.
 
 
+.. impl-detail::
+
+   Due to the :term:`Global Interpreter Lock`, in CPython only one thread
+   can execute Python code at once (even though certain performance-oriented
+   libraries might overcome this limitation).
+   If you want your application to make better of use of the computational
+   resources of multi-core machines, you are advised to use
+   :mod:`multiprocessing` or :class:`concurrent.futures.ProcessPoolExecutor`.
+   However, threading is still an appropriate model if you want to run
+   multiple I/O-bound tasks simultaneously.
+
+
 .. _lock-objects:
 
 Lock Objects
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 28e994c61c..24461b3c19 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -41,25 +41,6 @@ An explanation of some terminology and conventions is in order.
   parsed, they are converted according to the POSIX and ISO C standards: values
   69--99 are mapped to 1969--1999, and values 0--68 are mapped to 2000--2068.
 
-  For backward compatibility, years with less than 4 digits are treated
-  specially by :func:`asctime`, :func:`mktime`, and :func:`strftime` functions
-  that operate on a 9-tuple or :class:`struct_time` values. If year (the first
-  value in the 9-tuple) is specified with less than 4 digits, its interpretation
-  depends on the value of ``accept2dyear`` variable.
-
-  If ``accept2dyear`` is true (default), a backward compatibility behavior is
-  invoked as follows:
-
-    - for 2-digit year, century is guessed according to POSIX rules for
-      ``%y`` strptime format.  A deprecation warning is issued when century
-      information is guessed in this way.
-
-    - for 3-digit or negative year, a :exc:`ValueError` exception is raised.
-
-  If ``accept2dyear`` is false (set by the program or as a result of a
-  non-empty value assigned to ``PYTHONY2K`` environment variable) all year
-  values are interpreted as given.
-
 .. index::
    single: UTC
    single: Coordinated Universal Time
@@ -117,24 +98,6 @@ An explanation of some terminology and conventions is in order.
 
 The module defines the following functions and data items:
 
-
-.. data:: accept2dyear
-
-   Boolean value indicating whether two-digit year values will be
-   mapped to 1969--2068 range by :func:`asctime`, :func:`mktime`, and
-   :func:`strftime` functions.  This is true by default, but will be
-   set to false if the environment variable :envvar:`PYTHONY2K` has
-   been set to a non-empty string.  It may also be modified at run
-   time.
-
-   .. deprecated:: 3.2
-      Mapping of 2-digit year values by :func:`asctime`,
-      :func:`mktime`, and :func:`strftime` functions to 1969--2068
-      range is deprecated.  Programs that need to process 2-digit
-      years should use ``%y`` code available in :func:`strptime`
-      function or convert 2-digit year values to 4-digit themselves.
-
-
 .. data:: altzone
 
    The offset of the local DST timezone, in seconds west of UTC, if one is defined.
@@ -308,7 +271,7 @@ The module defines the following functions and data items:
    | ``%y``    | Year without century as a decimal number       |       |
    |           | [00,99].                                       |       |
    +-----------+------------------------------------------------+-------+
-   | ``%Y``    | Year with century as a decimal number.         | \(4)  |
+   | ``%Y``    | Year with century as a decimal number.         |       |
    |           |                                                |       |
    +-----------+------------------------------------------------+-------+
    | ``%Z``    | Time zone name (no characters if no time zone  |       |
@@ -332,12 +295,6 @@ The module defines the following functions and data items:
       When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
       calculations when the day of the week and the year are specified.
 
-   (4)
-      Produces different results depending on the value of
-      ``time.accept2dyear`` variable.  See :ref:`Year 2000 (Y2K)
-      issues <time-y2kissues>` for details.
-
-
    Here is an example, a format for dates compatible with that specified  in the
    :rfc:`2822` Internet email standard.  [#]_ ::
 
@@ -418,8 +375,7 @@ The module defines the following functions and data items:
    +-------+-------------------+---------------------------------+
 
    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
+   [0, 11].  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.
 
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
index beed4ded86..191d5b9fdd 100644
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -723,7 +723,7 @@ Test cases
    Here, we create two instances of :class:`WidgetTestCase`, each of which runs a
    single test.
 
-   .. versionchanged::
+   .. versionchanged:: 3.2
       `TestCase` can be instantiated successfully without providing a method
       name. This makes it easier to experiment with `TestCase` from the
       interactive interpreter.
@@ -792,11 +792,14 @@ Test cases
       Run the test, collecting the result into the test result object passed as
       *result*.  If *result* is omitted or ``None``, a temporary result
       object is created (by calling the :meth:`defaultTestResult` method) and
-      used. The result object is not returned to :meth:`run`'s caller.
+      used. The result object is returned to :meth:`run`'s caller.
 
       The same effect may be had by simply calling the :class:`TestCase`
       instance.
 
+      .. versionchanged:: 3.3
+         Previous versions of ``run`` did not return the result. Neither did
+         calling an instance.
 
    .. method:: skipTest(reason)
 
@@ -857,10 +860,11 @@ Test cases
    | <TestCase.assertNotIsInstance>`         |                             |               |
    +-----------------------------------------+-----------------------------+---------------+
 
-   All the assert methods (except :meth:`assertRaises`,
-   :meth:`assertRaisesRegex`, :meth:`assertWarns`, :meth:`assertWarnsRegex`)
-   accept a *msg* argument that, if specified, is used as the error message on
-   failure (see also :data:`longMessage`).
+   All the assert methods accept a *msg* argument that, if specified, is used
+   as the error message on failure (see also :data:`longMessage`).
+   Note that the *msg* keyword argument can be passed to :meth:`assertRaises`,
+   :meth:`assertRaisesRegex`, :meth:`assertWarns`, :meth:`assertWarnsRegex`
+   only when they are used as a context manager.
 
    .. method:: assertEqual(first, second, msg=None)
 
@@ -954,7 +958,7 @@ Test cases
    +---------------------------------------------------------+--------------------------------------+------------+
 
    .. method:: assertRaises(exception, callable, *args, **kwds)
-               assertRaises(exception)
+               assertRaises(exception, msg=None)
 
       Test that an exception is raised when *callable* is called with any
       positional or keyword arguments that are also passed to
@@ -963,12 +967,16 @@ Test cases
       To catch any of a group of exceptions, a tuple containing the exception
       classes may be passed as *exception*.
 
-      If only the *exception* argument is given, returns a context manager so
-      that the code under test can be written inline rather than as a function::
+      If only the *exception* and possibly the *msg* arguments are given,
+      return a context manager so that the code under test can be written
+      inline rather than as a function::
 
          with self.assertRaises(SomeException):
              do_something()
 
+      When used as a context manager, :meth:`assertRaises` accepts the
+      additional keyword argument *msg*.
+
       The context manager will store the caught exception object in its
       :attr:`exception` attribute.  This can be useful if the intention
       is to perform additional checks on the exception raised::
@@ -985,9 +993,12 @@ Test cases
       .. versionchanged:: 3.2
          Added the :attr:`exception` attribute.
 
+      .. versionchanged:: 3.3
+         Added the *msg* keyword argument when used as a context manager.
+
 
    .. method:: assertRaisesRegex(exception, regex, callable, *args, **kwds)
-               assertRaisesRegex(exception, regex)
+               assertRaisesRegex(exception, regex, msg=None)
 
       Like :meth:`assertRaises` but also tests that *regex* matches
       on the string representation of the raised exception.  *regex* may be
@@ -1004,12 +1015,16 @@ Test cases
 
       .. versionadded:: 3.1
          under the name ``assertRaisesRegexp``.
+
       .. versionchanged:: 3.2
          Renamed to :meth:`assertRaisesRegex`.
 
+      .. versionchanged:: 3.3
+         Added the *msg* keyword argument when used as a context manager.
+
 
    .. method:: assertWarns(warning, callable, *args, **kwds)
-               assertWarns(warning)
+               assertWarns(warning, msg=None)
 
       Test that a warning is triggered when *callable* is called with any
       positional or keyword arguments that are also passed to
@@ -1018,12 +1033,16 @@ Test cases
       To catch any of a group of warnings, a tuple containing the warning
       classes may be passed as *warnings*.
 
-      If only the *warning* argument is given, returns a context manager so
-      that the code under test can be written inline rather than as a function::
+      If only the *warning* and possibly the *msg* arguments are given,
+      returns a context manager so that the code under test can be written
+      inline rather than as a function::
 
          with self.assertWarns(SomeWarning):
              do_something()
 
+      When used as a context manager, :meth:`assertRaises` accepts the
+      additional keyword argument *msg*.
+
       The context manager will store the caught warning object in its
       :attr:`warning` attribute, and the source line which triggered the
       warnings in the :attr:`filename` and :attr:`lineno` attributes.
@@ -1041,9 +1060,12 @@ Test cases
 
       .. versionadded:: 3.2
 
+      .. versionchanged:: 3.3
+         Added the *msg* keyword argument when used as a context manager.
+
 
    .. method:: assertWarnsRegex(warning, regex, callable, *args, **kwds)
-               assertWarnsRegex(warning, regex)
+               assertWarnsRegex(warning, regex, msg=None)
 
       Like :meth:`assertWarns` but also tests that *regex* matches on the
       message of the triggered warning.  *regex* may be a regular expression
@@ -1061,6 +1083,8 @@ Test cases
 
       .. versionadded:: 3.2
 
+      .. versionchanged:: 3.3
+         Added the *msg* keyword argument when used as a context manager.
 
 
    There are also other methods used to perform more specific checks, such as:
diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
index 2cd062031f..e94575a126 100644
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -240,10 +240,11 @@ The following classes are provided:
 
 .. class:: HTTPBasicAuthHandler(password_mgr=None)
 
-   Handle authentication with the remote host. *password_mgr*, if given, should be
-   something that is compatible with :class:`HTTPPasswordMgr`; refer to section
-   :ref:`http-password-mgr` for information on the interface that must be
-   supported.
+   Handle authentication with the remote host. *password_mgr*, if given, should
+   be something that is compatible with :class:`HTTPPasswordMgr`; refer to
+   section :ref:`http-password-mgr` for information on the interface that must
+   be supported. HTTPBasicAuthHandler will raise a :exc:`ValueError` when
+   presented with a wrong Authentication scheme.
 
 
 .. class:: ProxyBasicAuthHandler(password_mgr=None)
@@ -265,10 +266,19 @@ The following classes are provided:
 
 .. class:: HTTPDigestAuthHandler(password_mgr=None)
 
-   Handle authentication with the remote host. *password_mgr*, if given, should be
-   something that is compatible with :class:`HTTPPasswordMgr`; refer to section
-   :ref:`http-password-mgr` for information on the interface that must be
-   supported.
+   Handle authentication with the remote host. *password_mgr*, if given, should
+   be something that is compatible with :class:`HTTPPasswordMgr`; refer to
+   section :ref:`http-password-mgr` for information on the interface that must
+   be supported. When both Digest Authentication Handler and Basic
+   Authentication Handler are both added, Digest Authentication is always tried
+   first. If the Digest Authentication returns a 40x response again, it is sent
+   to Basic Authentication handler to Handle.  This Handler method will raise a
+   :exc:`ValueError` when presented with an authentication scheme other than
+   Digest or Basic.
+
+   .. versionchanged:: 3.3
+      Raise :exc:`ValueError` on unsupported Authentication Scheme.
+
 
 
 .. class:: ProxyDigestAuthHandler(password_mgr=None)