merge heads.

.hgtags

@@ -75,6 +75,7 @@ a69a031ac1402dede8b1ef80096436bca6d371f3 v3.1
 960efa327c5d9c18df995437b0ac550cb89c9f85 v3.1.2
 d18e9d71f369d8211f6ac87252c6d3211f9bd09f v3.1.3rc1
 a4f75773c0060cee38b0bb651a7aba6f56b0e996 v3.1.3
+32fcb9e94985cb19ce37ba9543f091c0dbe9d7dd v3.1.4rc1
 b37b7834757492d009b99cf0ca4d42d2153d7fac v3.2a1
 56d4373cecb73c8b45126ba7b045b3c7b3f94b0b v3.2a2
 da012d9a2c23d144e399d2e01a55b8a83ad94573 v3.2a3

Doc/c-api/weakref.rst

@@ -55,7 +55,7 @@ as much as it can.
    Return the referenced object from a weak reference, *ref*.  If the referent is
    no longer live, returns :const:`Py_None`.
 
-   .. warning::
+   .. note::
 
       This function returns a **borrowed reference** to the referenced object.
       This means that you should always call :c:func:`Py_INCREF` on the object

Doc/contents.rst

@@ -11,7 +11,7 @@
    library/index.rst
    extending/index.rst
    c-api/index.rst
-   distutils/index.rst
+   packaging/index.rst
    install/index.rst
    documenting/index.rst
    howto/index.rst

Doc/distutils/extending.rst

@@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that
 should be copied into packages in addition to :file:`.py` files as a
 convenience.
 
-Most distutils command implementations are subclasses of the :class:`Command`
-class from :mod:`distutils.cmd`.  New commands may directly inherit from
+Most distutils command implementations are subclasses of the
+:class:`distutils.cmd.Command` class.  New commands may directly inherit from
 :class:`Command`, while replacements often derive from :class:`Command`
 indirectly, directly subclassing the command they are replacing.  Commands are
 required to derive from :class:`Command`.

Doc/distutils/index.rst

@@ -14,6 +14,10 @@ the module developer's point of view, describing how to use the Distutils to
 make Python modules and extensions easily available to a wider audience with
 very little overhead for build/release/install mechanics.
 
+.. deprecated:: 3.3
+   :mod:`packaging` replaces Distutils.  See :ref:`packaging-index` and
+   :ref:`packaging-install-index`.
+
 .. toctree::
    :maxdepth: 2
    :numbered:
@@ -29,3 +33,10 @@ very little overhead for build/release/install mechanics.
    extending.rst
    commandref.rst
    apiref.rst
+
+Another document describes how to install modules and extensions packaged
+following the above guidelines:
+
+.. toctree::
+
+   install.rst

Doc/documenting/building.rst

@@ -14,6 +14,7 @@ Using make
 Luckily, a Makefile has been prepared so that on Unix, provided you have
 installed Python and Subversion, you can just run ::
 
+   cd Doc
    make html
 
 to check out the necessary toolset in the :file:`tools/` subdirectory and build

Doc/documenting/style.rst

@@ -136,7 +136,7 @@ Good example (establishing confident knowledge in the effective use of the langu
 Economy of Expression
 ---------------------
 
-More documentation is not necessarily better documentation.  Error on the side
+More documentation is not necessarily better documentation.  Err on the side
 of being succinct.
 
 It is an unfortunate fact that making documentation longer can be an impediment
@@ -198,7 +198,7 @@ Audience
 The tone of the tutorial (and all the docs) needs to be respectful of the
 reader's intelligence.  Don't presume that the readers are stupid.  Lay out the
 relevant information, show motivating use cases, provide glossary links, and do
-our best to connect-the-dots, but don't talk down to them or waste their time.
+your best to connect-the-dots, but don't talk down to them or waste their time.
 
 The tutorial is meant for newcomers, many of whom will be using the tutorial to
 evaluate the language as a whole.  The experience needs to be positive and not

Doc/glossary.rst

@@ -247,7 +247,7 @@ Glossary
       processing, remembering the location execution state (including local
       variables and pending try-statements).  When the generator resumes, it
       picks-up where it left-off (in contrast to functions which start fresh on
-      every invocation.
+      every invocation).
 
       .. index:: single: generator expression
 

Doc/howto/sockets.rst

@@ -23,8 +23,8 @@ It's not really a tutorial - you'll still have work to do in getting things
 working. It doesn't cover the fine points (and there are a lot of them), but I
 hope it will give you enough background to begin using them decently.
 
-I'm only going to talk about INET sockets, but they account for at least 99% of
-the sockets in use. And I'll only talk about STREAM sockets - unless you really
+I'm only going to talk about INET (i.e. IPv4) sockets, but they account for at least 99% of
+the sockets in use. And I'll only talk about STREAM (i.e. TCP) sockets - unless you really
 know what you're doing (in which case this HOWTO isn't for you!), you'll get
 better behavior and performance from a STREAM socket than anything else. I will
 try to clear up the mystery of what a socket is, as well as some hints on how to
@@ -208,10 +208,10 @@ length message::
                totalsent = totalsent + sent
 
        def myreceive(self):
-           msg = ''
+           msg = b''
            while len(msg) < MSGLEN:
                chunk = self.sock.recv(MSGLEN-len(msg))
-               if chunk == '':
+               if chunk == b'':
                    raise RuntimeError("socket connection broken")
                msg = msg + chunk
            return msg

Doc/install/pysetup-config.rst

+.. _packaging-pysetup-config:
+
+=====================
+Pysetup Configuration
+=====================
+
+Pysetup supports two configuration files: :file:`.pypirc` and :file:`packaging.cfg`.
+
+.. FIXME integrate with configfile instead of duplicating
+
+Configuring indexes
+-------------------
+
+You can configure additional indexes in :file:`.pypirc` to be used for index-related
+operations. By default, all configured index-servers and package-servers will be used
+in an additive fashion. To limit operations to specific indexes, use the :option:`--index`
+and :option:`--package-server options`::
+
+  $ pysetup install --index pypi --package-server django some.project
+
+Adding indexes to :file:`.pypirc`::
+
+  [packaging]
+  index-servers =
+      pypi
+      other
+
+  package-servers =
+      django
+
+  [pypi]
+      repository: <repository-url>
+      username: <username>
+      password: <password>
+
+  [other]
+      repository: <repository-url>
+      username: <username>
+      password: <password>
+
+  [django]
+      repository: <repository-url>
+      username: <username>
+      password: <password>

Doc/install/pysetup-servers.rst

+.. _packaging-pysetup-servers:
+
+===============
+Package Servers
+===============
+
+Pysetup supports installing Python packages from *Package Servers* in addition
+to PyPI indexes and mirrors.
+
+Package Servers are simple directory listings of Python distributions. Directories
+can be served via HTTP or a local file system. This is useful when you want to
+dump source distributions in a directory and not worry about the full index structure.
+
+Serving distributions from Apache
+---------------------------------
+::
+
+   $ mkdir -p /var/www/html/python/distributions
+   $ cp *.tar.gz /var/www/html/python/distributions/
+
+   <VirtualHost python.example.org:80>
+       ServerAdmin webmaster@domain.com
+       DocumentRoot "/var/www/html/python"
+       ServerName python.example.org
+       ErrorLog logs/python.example.org-error.log
+       CustomLog logs/python.example.org-access.log common
+       Options Indexes FollowSymLinks MultiViews
+       DirectoryIndex index.html index.htm
+
+       <Directory "/var/www/html/python/distributions">
+           Options Indexes FollowSymLinks MultiViews
+           Order allow,deny
+           Allow from all
+       </Directory>
+   </VirtualHost>
+
+Add the Apache based distribution server to :file:`.pypirc`::
+
+   [packaging]
+   package-servers =
+       apache
+
+   [apache]
+   repository: http://python.example.org/distributions/
+
+
+Serving distributions from a file system
+----------------------------------------
+::
+
+   $ mkdir -p /data/python/distributions
+   $ cp *.tar.gz /data/python/distributions/
+
+Add the directory to :file:`.pypirc`::
+
+   [packaging]
+   package-servers =
+       local
+
+   [local]
+   repository: file:///data/python/distributions/

Doc/install/pysetup.rst

+.. _packaging-pysetup:
+
+================
+Pysetup Tutorial
+================
+
+Getting started
+---------------
+
+Pysetup is a simple script that supports the following features:
+
+- install, remove, list, and verify Python packages;
+- search for available packages on PyPI or any *Simple Index*;
+- verify installed packages (md5sum, installed files, version).
+
+
+Finding out what's installed
+----------------------------
+
+Pysetup makes it easy to find out what Python packages are installed::
+
+   $ pysetup search virtualenv
+   virtualenv 1.6 at /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info
+
+   $ pysetup search --all
+   pyverify 0.8.1 at /opt/python3.3/lib/python3.3/site-packages/pyverify-0.8.1.dist-info
+   virtualenv 1.6 at /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info
+   wsgiref 0.1.2 at /opt/python3.3/lib/python3.3/wsgiref.egg-info
+   ...
+
+
+Installing a distribution
+-------------------------
+
+Pysetup can install a Python project from the following sources:
+
+- PyPI and Simple Indexes;
+- source directories containing a valid :file:`setup.py` or :file:`setup.cfg`;
+- distribution source archives (:file:`project-1.0.tar.gz`, :file:`project-1.0.zip`);
+- HTTP (http://host/packages/project-1.0.tar.gz).
+
+
+Installing from PyPI and Simple Indexes::
+
+   $ pysetup install project
+   $ pysetup install project==1.0
+
+Installing from a distribution source archive::
+
+   $ pysetup install project-1.0.tar.gz
+
+Installing from a source directory containing a valid :file:`setup.py` or
+:file:`setup.cfg`::
+
+   $ cd path/to/source/directory
+   $ pysetup install
+
+   $ pysetup install path/to/source/directory
+
+Installing from HTTP::
+
+   $ pysetup install http://host/packages/project-1.0.tar.gz
+
+
+Retrieving metadata
+-------------------
+
+You can gather metadata from two sources, a project's source directory or an
+installed distribution. The `pysetup metadata` command can retrieve one or
+more metadata fields using the `-f` option and a metadata field as the
+argument. ::
+
+   $ pysetup metadata virtualenv -f version -f name
+   Version:
+       1.6
+   Name:
+       virtualenv
+
+   $ pysetup metadata virtualenv --all
+   Metadata-Version:
+       1.0
+   Name:
+       virtualenv
+   Version:
+       1.6
+   Platform:
+       UNKNOWN
+   Summary:
+       Virtual Python Environment builder
+   ...
+
+.. seealso::
+
+   There are three metadata versions, 1.0, 1.1, and 1.2. The following PEPs
+   describe specifics of the field names, and their semantics and usage.  1.0
+   :PEP:`241`, 1.1 :PEP:`314`, and 1.2 :PEP:`345`
+
+
+Removing a distribution
+-----------------------
+
+You can remove one or more installed distributions using the `pysetup remove`
+command::
+
+   $ pysetup remove virtualenv
+   removing 'virtualenv':
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/dependency_links.txt
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/entry_points.txt
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/not-zip-safe
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/PKG-INFO
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/SOURCES.txt
+     /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/top_level.txt
+   Proceed (y/n)? y
+   success: removed 6 files and 1 dirs
+
+The optional '-y' argument auto confirms, skipping the conformation prompt::
+
+  $ pysetup remove virtualenv -y
+
+
+Getting help
+------------
+
+All pysetup actions take the `-h` and `--help` options which prints the commands
+help string to stdout. ::
+
+   $ pysetup remove -h
+   Usage: pysetup remove dist [-y]
+      or: pysetup remove --help
+
+   Uninstall a Python package.
+
+   positional arguments:
+      dist  installed distribution name
+
+   optional arguments:
+      -y  auto confirm package removal
+
+Getting a list of all pysetup actions and global options::
+
+   $ pysetup --help
+   Usage: pysetup [options] action [action_options]
+
+   Actions:
+       run: Run one or several commands
+       metadata: Display the metadata of a project
+       install: Install a project
+       remove: Remove a project
+       search: Search for a project
+       graph: Display a graph
+       create: Create a Project
+
+   To get more help on an action, use:
+
+       pysetup action --help
+
+   Global options:
+       --verbose (-v)  run verbosely (default)
+       --quiet (-q)    run quietly (turns verbosity off)
+       --dry-run (-n)  don't actually do anything
+       --help (-h)     show detailed help message
+       --no-user-cfg   ignore pydistutils.cfg in your home directory
+       --version       Display the version

Doc/library/abc.rst

+.. _abstract-base-classes:
+
 :mod:`abc` --- Abstract Base Classes
 ====================================
 
@@ -12,7 +14,7 @@
 --------------
 
 This module provides the infrastructure for defining an :term:`abstract base
-class` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
+class` (ABC) in Python, as outlined in :pep:`3119`; see the PEP for why this
 was added to Python. (See also :pep:`3141` and the :mod:`numbers` module
 regarding a type hierarchy for numbers based on ABCs.)
 

Doc/library/bz2.rst

@@ -37,14 +37,18 @@ All of the classes in this module may safely be accessed from multiple threads.
    *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), or ``'w'``
-   for writing.
+   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'``.
 
    The *buffering* argument is ignored. Its use is deprecated.
 
-   If *mode* is ``'w'``, *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 ``'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.
 
    :class:`BZ2File` provides all of the members specified by the
    :class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
@@ -70,6 +74,10 @@ All of the classes in this module may safely be accessed from multiple threads.
    .. versionchanged:: 3.3
       The *fileobj* argument to the constructor was added.
 
+   .. versionchanged:: 3.3
+      The ``'a'`` (append) mode was added, along with support for reading
+      multi-stream files.
+
 
 Incremental (de)compression
 ---------------------------
@@ -106,14 +114,20 @@ Incremental (de)compression
    incrementally. For one-shot compression, use the :func:`decompress` function
    instead.
 
+   .. 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.
+
    .. method:: decompress(data)
 
       Provide data to the decompressor object. Returns a chunk of decompressed
       data if possible, or an empty byte string otherwise.
 
-      Attempting to decompress data after the end of 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.
+      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.
 
 
    .. attribute:: eof
@@ -127,6 +141,9 @@ Incremental (de)compression
 
       Data found after the end of the compressed stream.
 
+      If this attribute is accessed before the end of the stream has been
+      reached, its value will be ``b''``.
+
 
 One-shot (de)compression
 ------------------------
@@ -145,5 +162,11 @@ One-shot (de)compression
 
    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.
+

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

Doc/library/collections.abc.rst

@@ -23,7 +23,7 @@ example, whether it is hashable or whether it is a mapping.
 .. versionchanged:: 3.3
    Formerly, this module was part of the :mod:`collections` module.
 
-.. _abstract-base-classes:
+.. _collections-abstract-base-classes:
 
 Collections Abstract Base Classes
 ---------------------------------

Doc/library/collections.rst

@@ -34,7 +34,7 @@ Python's general purpose built-in containers, :class:`dict`, :class:`list`,
 =====================   ====================================================================
 
 .. versionchanged:: 3.3
-   Moved :ref:`abstract-base-classes` to the :mod:`collections.abc` module.
+   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.
 

Doc/library/crypt.rst

@@ -29,6 +29,8 @@ this module.
 Hashing Methods
 ---------------
 
+.. versionadded:: 3.3
+
 The :mod:`crypt` module defines the list of hashing methods (not all methods
 are available on all platforms):
 
@@ -37,33 +39,26 @@ are available on all platforms):
    A Modular Crypt Format method with 16 character salt and 86 character
    hash.  This is the strongest method.
 
-   .. versionadded:: 3.3
-
 .. data:: METHOD_SHA256
 
    Another Modular Crypt Format method with 16 character salt and 43
    character hash.
 
-   .. versionadded:: 3.3
-
 .. data:: METHOD_MD5
 
    Another Modular Crypt Format method with 8 character salt and 22
    character hash.
 
-   .. versionadded:: 3.3
-
 .. data:: METHOD_CRYPT
 
    The traditional method with a 2 character salt and 13 characters of
    hash.  This is the weakest method.
 
-   .. versionadded:: 3.3
-
 
 Module Attributes
 -----------------
 
+.. versionadded:: 3.3
 
 .. attribute:: methods
 
@@ -71,8 +66,6 @@ Module Attributes
    ``crypt.METHOD_*`` objects.  This list is sorted from strongest to
    weakest, and is guaranteed to have at least ``crypt.METHOD_CRYPT``.
 
-   .. versionadded:: 3.3
-
 
 Module Functions
 ----------------
@@ -108,9 +101,8 @@ The :mod:`crypt` module defines the following functions:
    different sizes in the *salt*, it is recommended to use  the full crypted
    password as salt when checking for a password.
 
-.. versionchanged:: 3.3
-   Before version 3.3, *salt*  must be specified as a string and cannot
-   accept ``crypt.METHOD_*`` values (which don't exist anyway).
+   .. versionchanged:: 3.3
+      Accept ``crypt.METHOD_*`` values in addition to strings for *salt*.
 
 
 .. function:: mksalt(method=None)
@@ -124,25 +116,27 @@ The :mod:`crypt` module defines the following functions:
    16 random characters from the set ``[./a-zA-Z0-9]``, suitable for
    passing as the *salt* argument to :func:`crypt`.
 
-.. versionadded:: 3.3
+   .. 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::
@@ -151,4 +145,4 @@ check it against the original::
 
    hashed = crypt.crypt(plaintext)
    if hashed != crypt.crypt(plaintext, hashed):
-      raise "Hashed version doesn't validate against original"
+      raise ValueError("hashed version doesn't validate against original")

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

Doc/library/functions.rst

@@ -290,19 +290,18 @@ are always available.  They are listed here in alphabetical order.
    The resulting list is sorted alphabetically.  For example:
 
       >>> import struct
-      >>> dir()   # doctest: +SKIP
+      >>> dir()   # show the names in the module namespace
       ['__builtins__', '__doc__', '__name__', 'struct']
-      >>> dir(struct)   # doctest: +NORMALIZE_WHITESPACE
+      >>> dir(struct)   # show the names in the struct module
       ['Struct', '__builtins__', '__doc__', '__file__', '__name__',
        '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
        'unpack', 'unpack_from']
-      >>> class Foo:
-      ...     def __dir__(self):
-      ...         return ["kan", "ga", "roo"]
-      ...
-      >>> f = Foo()
-      >>> dir(f)
-      ['ga', 'kan', 'roo']
+      >>> class Shape(object):
+              def __dir__(self):
+                  return ['area', 'perimeter', 'location']
+      >>> s = Shape()
+      >>> dir(s)
+      ['area', 'perimeter', 'location']
 
    .. note::
 
@@ -333,15 +332,21 @@ are always available.  They are listed here in alphabetical order.
    :meth:`__next__` method of the iterator returned by :func:`enumerate` returns a
    tuple containing a count (from *start* which defaults to 0) and the
    corresponding value obtained from iterating over *iterable*.
-   :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
-   ``(1, seq[1])``, ``(2, seq[2])``, .... For example:
 
-      >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
-      ...     print(i, season)
-      0 Spring
-      1 Summer
-      2 Fall
-      3 Winter
+      >>> for i, season in enumerate('Spring Summer Fall Winter'.split(), start=1):
+              print(i, season)
+      1 Spring
+      2 Summer
+      3 Fall
+      4 Winter
+
+   Equivalent to::
+
+      def enumerate(sequence, start=0):
+          n = start
+          for elem in sequence:
+              yield n, elem
+              n += 1
 
 
 .. function:: eval(expression, globals=None, locals=None)
@@ -580,7 +585,7 @@ are always available.  They are listed here in alphabetical order.
    Two objects with non-overlapping lifetimes may have the same :func:`id`
    value.
 
-   .. impl-detail:: This is the address of the object.
+   .. impl-detail:: This is the address of the object in memory.
 
 
 .. function:: input([prompt])
@@ -652,10 +657,10 @@ are always available.  They are listed here in alphabetical order.
 
    One useful application of the second form of :func:`iter` is to read lines of
    a file until a certain line is reached.  The following example reads a file
-   until ``"STOP"`` is reached: ::
+   until the :meth:`readline` method returns an empty string::
 
-      with open("mydata.txt") as fp:
-          for line in iter(fp.readline, "STOP"):
+      with open('mydata.txt') as fp:
+          for line in iter(fp.readline, ''):
               process_line(line)
 
 
@@ -1169,8 +1174,9 @@ are always available.  They are listed here in alphabetical order.
    It can be called either on the class (such as ``C.f()``) or on an instance (such
    as ``C().f()``).  The instance is ignored except for its class.
 
-   Static methods in Python are similar to those found in Java or C++. For a more
-   advanced concept, see :func:`classmethod` in this section.
+   Static methods in Python are similar to those found in Java or C++. Also see
+   :func:`classmethod` for a variant that is useful for creating alternate class
+   constructors.
 
    For more information on static methods, consult the documentation on the
    standard type hierarchy in :ref:`types`.
@@ -1270,6 +1276,10 @@ are always available.  They are listed here in alphabetical order.
    references.  The zero argument form automatically searches the stack frame
    for the class (``__class__``) and the first argument.
 
+   For practical suggestions on how to design cooperative classes using
+   :func:`super`, see `guide to using super()
+   <http://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
+
 
 .. function:: tuple([iterable])
 

Doc/library/os.rst

@@ -1019,6 +1019,19 @@ as internal buffering of data.
    Availability: Unix, Windows.
 
 
+.. function:: pipe2(flags=0)
+
+   Create a pipe with *flags* set atomically.
+   *flags* is optional and can be constructed by ORing together zero 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*

Doc/library/packaging-misc.rst

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

Doc/library/packaging.command.rst

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

Doc/library/packaging.pypi.rst

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

Doc/library/pprint.rst

@@ -193,7 +193,7 @@ Example
 -------
 
 To demonstrate several uses of the :func:`pprint` function and its parameters,
-let's fetch information about a package from PyPI::
+let's fetch information about a project from PyPI::
 
    >>> import json
    >>> import pprint
@@ -201,8 +201,8 @@ let's fetch information about a package from PyPI::
    >>> with urlopen('http://pypi.python.org/pypi/configparser/json') as url:
    ...     http_info = url.info()
    ...     raw_data = url.read().decode(http_info.get_content_charset())
-   >>> package_data = json.loads(raw_data)
-   >>> result = {'headers': http_info.items(), 'body': package_data}
+   >>> project_info = json.loads(raw_data)
+   >>> result = {'headers': http_info.items(), 'body': project_info}
 
 In its basic form, :func:`pprint` shows the whole object::