Branch merge

Doc/distutils/install.rst

@@ -101,8 +101,8 @@ one command from a terminal::
 
    python setup.py install
 
-For Windows, this command should be run from a command prompt windows ("DOS
-box")::
+For Windows, this command should be run from a command prompt window
+(:menuselection:`Start --> Accessories`)::
 
    setup.py install
 
@@ -144,7 +144,7 @@ archive file to :file:`C:\\Temp`, then it would unpack into
 :file:`C:\\Temp\\foo-1.0`; you can use either a archive manipulator with a
 graphical user interface (such as WinZip) or a command-line tool (such as
 :program:`unzip` or :program:`pkunzip`) to unpack the archive.  Then, open a
-command prompt window ("DOS box"), and run::
+command prompt window and run::
 
    cd c:\Temp\foo-1.0
    python setup.py install

Doc/distutils/introduction.rst

@@ -84,8 +84,8 @@ terminal::
 
    python setup.py sdist
 
-For Windows, open a command prompt windows ("DOS box") and change the command
-to::
+For Windows, open a command prompt window (:menuselection:`Start -->
+Accessories`) and change the command to::
 
    setup.py sdist
 

Doc/distutils/setupscript.rst

@@ -254,7 +254,7 @@ code: it's probably better to write C code like  ::
 
 If you need to include header files from some other Python extension, you can
 take advantage of the fact that header files are installed in a consistent way
-by the Distutils :command:`install_header` command.  For example, the Numerical
+by the Distutils :command:`install_headers` command.  For example, the Numerical
 Python header files are installed (on a standard Unix installation) to
 :file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
 according to your platform and Python installation.)  Since the Python include

Doc/glossary.rst

@@ -30,7 +30,10 @@ Glossary
       Abstract base classes complement :term:`duck-typing` by
       providing a way to define interfaces when other techniques like
       :func:`hasattr` would be clumsy or subtly wrong (for example with
-      :ref:`magic methods <special-lookup>`). Python comes with many built-in ABCs for
+      :ref:`magic methods <special-lookup>`).  ABCs introduce virtual
+      subclasses, which are classes that don't inherit from a class but are
+      still recognized by :func:`isinstance` and :func:`issubclass`; see the
+      :mod:`abc` module documentation.  Python comes with many built-in ABCs for
       data structures (in the :mod:`collections.abc` module), numbers (in the
       :mod:`numbers` module), streams (in the :mod:`io` module), import finders
       and loaders (in the :mod:`importlib.abc` module).  You can create your own
@@ -163,8 +166,8 @@ Glossary
       well-designed code improves its flexibility by allowing polymorphic
       substitution.  Duck-typing avoids tests using :func:`type` or
       :func:`isinstance`.  (Note, however, that duck-typing can be complemented
-      with :term:`abstract base class`\ es.)  Instead, it typically employs
-      :func:`hasattr` tests or :term:`EAFP` programming.
+      with :term:`abstract base classes <abstract base class>`.)  Instead, it
+      typically employs :func:`hasattr` tests or :term:`EAFP` programming.
 
    EAFP
       Easier to ask for forgiveness than permission.  This common Python coding

Doc/install/install.rst

@@ -119,12 +119,9 @@ command::
 
    pysetup run install_dist
 
-How you actually run this command depends on the platform and the command line
-interface it provides:
-
-* **Unix**: Use a shell prompt.
-* **Windows**: Open a command prompt ("DOS console") or use :command:`Powershell`.
-* **OS X**: Open a :command:`Terminal`.
+This is a command that should be run in a terminal.  On Windows, it is called a
+command prompt and found in :menuselection:`Start --> Accessories`; Powershell
+is a popular alternative.
 
 
 .. _packaging-platform-variations:
@@ -147,8 +144,7 @@ archive file to :file:`C:\\Temp`, then it would unpack into
 :file:`C:\\Temp\\foo-1.0`. To actually unpack the archive, you can use either
 an archive manipulator with a graphical user interface (such as WinZip or 7-Zip)
 or a command-line tool (such as :program:`unzip`, :program:`pkunzip` or, again,
-:program:`7z`). Then, open a command prompt window ("DOS box" or
-Powershell), and run::
+:program:`7z`). Then, open a command prompt window and run::
 
    cd c:\Temp\foo-1.0
    pysetup run install_dist
@@ -279,7 +275,8 @@ different recipe for each platform. Under Unix, just type :command:`python` at
 the shell prompt. Under Windows (assuming the Python executable is on your
 :envvar:`PATH`, which is the usual case), you can choose :menuselection:`Start --> Run`,
 type ``python`` and press ``enter``. Alternatively, you can simply execute
-:command:`python` at a command prompt ("DOS console" or Powershell).
+:command:`python` at a command prompt (:menuselection:`Start --> Accessories`)
+or in Powershell.
 
 Once the interpreter is started, you type Python code at the prompt. For
 example, on my Linux system, I type the three Python statements shown below,

Doc/library/abc.rst

@@ -194,7 +194,7 @@ It also provides the following decorators:
    .. versionadded:: 3.2
 
 
-.. function:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
+.. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
 
    A subclass of the built-in :func:`property`, indicating an abstract property.
 

Doc/library/atexit.rst

@@ -6,6 +6,9 @@
 .. moduleauthor:: Skip Montanaro <skip@pobox.com>
 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
+**Source code:** :source:`Lib/atexit.py`
+
+--------------
 
 The :mod:`atexit` module defines functions to register and unregister cleanup
 functions.  Functions thus registered are automatically executed upon normal

Doc/library/cmd.rst

@@ -205,6 +205,9 @@ Instances of :class:`Cmd` subclasses have some public instance variables:
    :mod:`readline`, on systems that support it, the interpreter will automatically
    support :program:`Emacs`\ -like line editing  and command-history keystrokes.)
 
+
+.. _cmd-example:
+
 Cmd Example
 -----------
 

Doc/library/collections.rst

-
 :mod:`collections` --- Container datatypes
 ==========================================
 
@@ -977,7 +976,7 @@ original insertion position is changed and moved to the end::
                 del self[key]
             OrderedDict.__setitem__(self, key, value)
 
-An ordered dictionary can combined with the :class:`Counter` class
+An ordered dictionary can be combined with the :class:`Counter` class
 so that the counter remembers the order elements are first encountered::
 
    class OrderedCounter(Counter, OrderedDict):

Doc/library/concurrent.futures.rst

@@ -4,11 +4,11 @@
 .. module:: concurrent.futures
    :synopsis: Execute computations concurrently using threads or processes.
 
+.. versionadded:: 3.2
+
 **Source code:** :source:`Lib/concurrent/futures/thread.py`
 and :source:`Lib/concurrent/futures/process.py`
 
-.. versionadded:: 3.2
-
 --------------
 
 The :mod:`concurrent.futures` module provides a high-level interface for

Doc/library/functions.rst

@@ -624,7 +624,8 @@ are always available.  They are listed here in alphabetical order.
 .. function:: isinstance(object, classinfo)
 
    Return true if the *object* argument is an instance of the *classinfo*
-   argument, or of a (direct or indirect) subclass thereof.  If *object* is not
+   argument, or of a (direct, indirect or :term:`virtual <abstract base
+   class>`) subclass thereof.  If *object* is not
    an object of the given type, the function always returns false.  If
    *classinfo* is not a class (type object), it may be a tuple of type objects,
    or may recursively contain other such tuples (other sequence types are not
@@ -634,7 +635,8 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: issubclass(class, classinfo)
 
-   Return true if *class* is a subclass (direct or indirect) of *classinfo*.  A
+   Return true if *class* is a subclass (direct, indirect or :term:`virtual
+   <abstract base class>`) of *classinfo*.  A
    class is considered a subclass of itself. *classinfo* may be a tuple of class
    objects, in which case every entry in *classinfo* will be checked. In any other
    case, a :exc:`TypeError` exception is raised.

Doc/library/logging.handlers.rst

@@ -799,7 +799,7 @@ possible, while any potentially slow operations (such as sending an email via
 
 
 
-.. queue-listener:
+.. _queue-listener:
 
 QueueListener
 ^^^^^^^^^^^^^

Doc/library/optparse.rst

@@ -7,14 +7,14 @@
 .. moduleauthor:: Greg Ward <gward@python.net>
 .. sectionauthor:: Greg Ward <gward@python.net>
 
+.. deprecated:: 3.2
+  The :mod:`optparse` module is deprecated and will not be developed further;
+  development will continue with the :mod:`argparse` module.
+
 **Source code:** :source:`Lib/optparse.py`
 
 --------------
 
-.. deprecated:: 2.7
-  The :mod:`optparse` module is deprecated and will not be developed further;
-  development will continue with the :mod:`argparse` module.
-
 :mod:`optparse` is a more convenient, flexible, and powerful library for parsing
 command-line options than the old :mod:`getopt` module.  :mod:`optparse` uses a
 more declarative style of command-line parsing: you create an instance of

Doc/library/string.rst

@@ -4,6 +4,9 @@
 .. module:: string
    :synopsis: Common string operations.
 
+**Source code:** :source:`Lib/string.py`
+
+--------------
 
 .. seealso::
 
@@ -11,10 +14,6 @@
 
    :ref:`string-methods`
 
-**Source code:** :source:`Lib/string.py`
-
---------------
-
 String constants
 ----------------
 

Doc/library/sysconfig.rst

@@ -3,15 +3,16 @@
 
 .. module:: sysconfig
    :synopsis: Python's configuration information
-.. moduleauthor:: Tarek Ziade <tarek@ziade.org>
-.. sectionauthor:: Tarek Ziade <tarek@ziade.org>
+.. moduleauthor:: Tarek Ziadé <tarek@ziade.org>
+.. sectionauthor:: Tarek Ziadé <tarek@ziade.org>
+
 .. index::
    single: configuration information
 
-**Source code:** :source:`Lib/sysconfig.py`
-
 .. versionadded:: 3.2
 
+**Source code:** :source:`Lib/sysconfig.py`
+
 --------------
 
 The :mod:`sysconfig` module provides access to Python's configuration

Doc/library/urllib.parse.rst

@@ -12,6 +12,10 @@
    pair: URL; parsing
    pair: relative; URL
 
+**Source code:** :source:`Lib/urllib/parse.py`
+
+--------------
+
 This module defines a standard interface to break Uniform Resource Locator (URL)
 strings up in components (addressing scheme, network location, path etc.), to
 combine the components back into a URL string, and to convert a "relative URL"

Doc/library/zipfile.rst

@@ -30,15 +30,16 @@ The module defines the following items:
 
 .. exception:: BadZipFile
 
-   The error raised for bad ZIP files (old name: ``zipfile.error``).
+   The error raised for bad ZIP files.
 
    .. versionadded:: 3.2
 
 
 .. exception:: BadZipfile
 
-   This is an alias for :exc:`BadZipFile` that exists for compatibility with
-   Python versions prior to 3.2.  Usage is deprecated.
+   Alias of :exc:`BadZipFile`, for compatibility with older Python versions.
+
+   .. deprecated:: 3.2
 
 
 .. exception:: LargeZipFile

Lib/packaging/create.py

@@ -40,35 +40,36 @@ _DEFAULT_CFG = '.pypkgcreate'
 
 _helptext = {
     'name': '''
-The name of the program to be packaged, usually a single word composed
-of lower-case characters such as "python", "sqlalchemy", or "CherryPy".
+The name of the project to be packaged, usually a single word composed
+of lower-case characters such as "zope.interface", "sqlalchemy" or
+"CherryPy".
 ''',
     'version': '''
-Version number of the software, typically 2 or 3 numbers separated by dots
-such as "1.00", "0.6", or "3.02.01".  "0.1.0" is recommended for initial
-development.
+Version number of the software, typically 2 or 3 numbers separated by
+dots such as "1.0", "0.6b3", or "3.2.1".  "0.1.0" is recommended for
+initial development.
 ''',
     'summary': '''
-A one-line summary of what this project is or does, typically a sentence 80
-characters or less in length.
+A one-line summary of what this project is or does, typically a sentence
+80 characters or less in length.
 ''',
     'author': '''
 The full name of the author (typically you).
 ''',
     'author_email': '''
-E-mail address of the project author (typically you).
+Email address of the project author.
 ''',
     'do_classifier': '''
 Trove classifiers are optional identifiers that allow you to specify the
 intended audience by saying things like "Beta software with a text UI
-for Linux under the PSF license".  However, this can be a somewhat involved
-process.
+for Linux under the PSF license".  However, this can be a somewhat
+involved process.
 ''',
     'packages': '''
-You can provide a package name contained in your project.
+Python packages included in the project.
 ''',
     'modules': '''
-You can provide a python module contained in your project.
+Pure Python modules included in the project.
 ''',
     'extra_files': '''
 You can provide extra files/dirs contained in your project.
@@ -76,15 +77,15 @@ It has to follow the template syntax. XXX add help here.
 ''',
 
     'home_page': '''
-The home page for the project, typically starting with "http://".
+The home page for the project, typically a public Web page.
 ''',
     'trove_license': '''
-Optionally you can specify a license.  Type a string that identifies a common
-license, and then you can select a list of license specifiers.
+Optionally you can specify a license.  Type a string that identifies a
+common license, and then you can select a list of license specifiers.
 ''',
     'trove_generic': '''
 Optionally, you can set other trove identifiers for things such as the
-human language, programming language, user interface, etc...
+human language, programming language, user interface, etc.
 ''',
     'setup.py found': '''
 The setup.py script will be executed to retrieve the metadata.
@@ -468,12 +469,12 @@ class MainProgram:
 
         self.data['version'] = ask('Current version number',
               self.data.get('version'), _helptext['version'])
-        self.data['summary'] = ask('Package summary',
+        self.data['summary'] = ask('Project description summary',
               self.data.get('summary'), _helptext['summary'],
               lengthy=True)
         self.data['author'] = ask('Author name',
               self.data.get('author'), _helptext['author'])
-        self.data['author_email'] = ask('Author e-mail address',
+        self.data['author_email'] = ask('Author email address',
               self.data.get('author_email'), _helptext['author_email'])
         self.data['home_page'] = ask('Project home page',
               self.data.get('home_page'), _helptext['home_page'],

Lib/packaging/database.py

@@ -191,7 +191,7 @@ class Distribution:
         A local absolute path is an absolute path in which occurrences of
         ``'/'`` have been replaced by the system separator given by ``os.sep``.
 
-        :parameter local: flag to say if the path should be returned a local
+        :parameter local: flag to say if the path should be returned as a local
                           absolute path
 
         :type local: boolean

Lib/packaging/metadata.py

@@ -182,14 +182,6 @@ _UNICODEFIELDS = ('Author', 'Maintainer', 'Summary', 'Description')
 _MISSING = object()
 
 
-class NoDefault:
-    """Marker object used for clean representation"""
-    def __repr__(self):
-        return '<NoDefault>'
-
-_MISSING = NoDefault()
-
-
 class Metadata:
     """The metadata of a release.
 

Lib/shutil.py

@@ -399,7 +399,7 @@ def _make_tarball(base_name, base_dir, compress="gzip", verbose=0, dry_run=0,
 
     if not os.path.exists(archive_dir):
         if logger is not None:
-            logger.info("creating %s" % archive_dir)
+            logger.info("creating %s", archive_dir)
         if not dry_run:
             os.makedirs(archive_dir)