Branch merge
diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst
index 57d34a4..0ece646 100644
--- a/Doc/distutils/introduction.rst
+++ b/Doc/distutils/introduction.rst
@@ -84,8 +84,8 @@
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
diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
index 606ea0f..8029243 100644
--- a/Doc/distutils/setupscript.rst
+++ b/Doc/distutils/setupscript.rst
@@ -254,7 +254,7 @@
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
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 2003e0b..63d4c2b 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -30,7 +30,10 @@
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` 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 @@
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
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index 171ef98..b20f1fb 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -101,8 +101,8 @@
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 @@
: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
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 8d602fe..38e52fb 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -6,10 +6,10 @@
.. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>
.. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>
-**Source code:** :source:`Lib/argparse.py`
-
.. versionadded:: 3.2
+**Source code:** :source:`Lib/argparse.py`
+
--------------
The :mod:`argparse` module makes it easy to write user-friendly command-line
@@ -109,7 +109,7 @@
:class:`ArgumentParser` parses arguments through the
:meth:`~ArgumentParser.parse_args` method. This will inspect the command line,
-convert each arg to the appropriate type and then invoke the appropriate action.
+convert each argument to the appropriate type and then invoke the appropriate action.
In most cases, this means a simple :class:`Namespace` object will be built up from
attributes parsed out of the command line::
@@ -244,7 +244,7 @@
--foo FOO foo help
The help option is typically ``-h/--help``. The exception to this is
-if the ``prefix_chars=`` is specified and does not include ``'-'``, in
+if the ``prefix_chars=`` is specified and does not include ``-``, in
which case ``-h`` and ``--help`` are not valid options. In
this case, the first character in ``prefix_chars`` is used to prefix
the help options::
@@ -260,7 +260,7 @@
prefix_chars
^^^^^^^^^^^^
-Most command-line options will use ``'-'`` as the prefix, e.g. ``-f/--foo``.
+Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
Parsers that need to support different or additional prefix
characters, e.g. for options
like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
@@ -273,7 +273,7 @@
Namespace(bar='Y', f='X')
The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
-characters that does not include ``'-'`` will cause ``-f/--foo`` options to be
+characters that does not include ``-`` will cause ``-f/--foo`` options to be
disallowed.
@@ -395,7 +395,7 @@
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,7 +421,7 @@
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`,
@@ -759,7 +759,7 @@
different number of command-line arguments with a single action. The supported
values are:
-* N (an integer). N arguments from the command line will be gathered together into a
+* ``N`` (an integer). ``N`` arguments from the command line will be gathered together into a
list. For example::
>>> parser = argparse.ArgumentParser()
@@ -771,11 +771,11 @@
Note that ``nargs=1`` produces a list of one item. This is different from
the default, in which the item is produced by itself.
-* ``'?'``. One arg will be consumed from the command line if possible, and
- produced as a single item. If no command-line arg is present, the value from
+* ``'?'``. One argument will be consumed from the command line if possible, and
+ produced as a single item. If no command-line argument is present, the value from
default_ will be produced. Note that for optional arguments, there is an
additional case - the option string is present but not followed by a
- command-line arg. In this case the value from const_ will be produced. Some
+ command-line argument. In this case the value from const_ will be produced. Some
examples to illustrate this::
>>> parser = argparse.ArgumentParser()
@@ -817,7 +817,7 @@
* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
list. Additionally, an error message will be generated if there wasn't at
- least one command-line arg present. For example::
+ least one command-line argument present. For example::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
@@ -828,7 +828,7 @@
PROG: error: too few arguments
If the ``nargs`` keyword argument is not provided, the number of arguments consumed
-is determined by the action_. Generally this means a single command-line arg
+is determined by the action_. Generally this means a single command-line argument
will be consumed and a single item (not a list) will be produced.
@@ -847,7 +847,7 @@
(like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional
argument that can be followed by zero or one command-line arguments.
When parsing the command line, if the option string is encountered with no
- command-line arg following it, the value of ``const`` will be assumed instead.
+ command-line argument following it, the value of ``const`` will be assumed instead.
See the nargs_ description for examples.
The ``const`` keyword argument defaults to ``None``.
@@ -859,7 +859,7 @@
All optional arguments and some positional arguments may be omitted at the
command line. The ``default`` keyword argument of
:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
-specifies what value should be used if the command-line arg is not present.
+specifies what value should be used if the command-line argument is not present.
For optional arguments, the ``default`` value is used when the option string
was not present at the command line::
@@ -870,8 +870,8 @@
>>> parser.parse_args(''.split())
Namespace(foo=42)
-For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value
-is used when no command-line arg was present::
+For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value
+is used when no command-line argument was present::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
@@ -957,8 +957,8 @@
Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a container object as the ``choices`` keyword
argument to :meth:`~ArgumentParser.add_argument`. When the command line is
-parsed, arg values will be checked, and an error message will be displayed if
-the arg was not one of the acceptable values::
+parsed, argument values will be checked, and an error message will be displayed if
+the argument was not one of the acceptable values::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', choices='abc')
@@ -1061,7 +1061,7 @@
actions, the dest_ value is used directly, and for optional argument actions,
the dest_ value is uppercased. So, a single positional argument with
``dest='bar'`` will that argument will be referred to as ``bar``. A single
-optional argument ``--foo`` that should be followed by a single command-line arg
+optional argument ``--foo`` that should be followed by a single command-line argument
will be referred to as ``FOO``. An example::
>>> parser = argparse.ArgumentParser()
@@ -1133,10 +1133,10 @@
For optional argument actions, the value of ``dest`` is normally inferred from
the option strings. :class:`ArgumentParser` generates the value of ``dest`` by
-taking the first long option string and stripping away the initial ``'--'``
+taking the first long option string and stripping away the initial ``--``
string. If no long option strings were supplied, ``dest`` will be derived from
-the first short option string by stripping the initial ``'-'`` character. Any
-internal ``'-'`` characters will be converted to ``'_'`` characters to make sure
+the first short option string by stripping the initial ``-`` character. Any
+internal ``-`` characters will be converted to ``_`` characters to make sure
the string is a valid attribute name. The examples below illustrate this
behavior::
@@ -1168,7 +1168,7 @@
created and how they are assigned. See the documentation for
:meth:`add_argument` for details.
- By default, the arg strings are taken from :data:`sys.argv`, and a new empty
+ By default, the argument strings are taken from :data:`sys.argv`, and a new empty
:class:`Namespace` object is created for the attributes.
@@ -1239,15 +1239,15 @@
PROG: error: extra arguments found: badger
-Arguments containing ``"-"``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Arguments containing ``-``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever
the user has clearly made a mistake, but some situations are inherently
-ambiguous. For example, the command-line arg ``'-1'`` could either be an
+ambiguous. For example, the command-line argument ``-1`` could either be an
attempt to specify an option or an attempt to provide a positional argument.
The :meth:`~ArgumentParser.parse_args` method is cautious here: positional
-arguments may only begin with ``'-'`` if they look like negative numbers and
+arguments may only begin with ``-`` if they look like negative numbers and
there are no options in the parser that look like negative numbers::
>>> parser = argparse.ArgumentParser(prog='PROG')
@@ -1280,7 +1280,7 @@
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument
-If you have positional arguments that must begin with ``'-'`` and don't look
+If you have positional arguments that must begin with ``-`` and don't look
like negative numbers, you can insert the pseudo-argument ``'--'`` which tells
:meth:`~ArgumentParser.parse_args` that everything after that is a positional
argument::
@@ -1398,7 +1398,7 @@
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
>>>
- >>> # parse some arg lists
+ >>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
@@ -1407,8 +1407,8 @@
Note that the object returned by :meth:`parse_args` will only contain
attributes for the main parser and the subparser that was selected by the
command line (and not any other subparsers). So in the example above, when
- the ``"a"`` command is specified, only the ``foo`` and ``bar`` attributes are
- present, and when the ``"b"`` command is specified, only the ``foo`` and
+ the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
+ present, and when the ``b`` command is specified, only the ``foo`` and
``baz`` attributes are present.
Similarly, when a help message is requested from a subparser, only the help
diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index 5b87b94..f2dccc2 100644
--- a/Doc/library/atexit.rst
+++ b/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
diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst
index e9a049f..30f1726 100644
--- a/Doc/library/cmd.rst
+++ b/Doc/library/cmd.rst
@@ -205,6 +205,9 @@
: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
-----------
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 4975f74..bf1fe2c 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -1,4 +1,3 @@
-
:mod:`collections` --- Container datatypes
==========================================
@@ -886,7 +885,7 @@
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):
@@ -985,6 +984,7 @@
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
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index e5d13f3..2359dd1 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/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
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index edff106..3b6fdc3 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -624,7 +624,8 @@
.. 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 @@
.. 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.
diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index a18cf92..c4dd438 100644
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -790,7 +790,7 @@
-.. queue-listener:
+.. _queue-listener:
QueueListener
^^^^^^^^^^^^^
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index fddc1fb..7d2d91b 100644
--- a/Doc/library/optparse.rst
+++ b/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
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index 3f9ec0b..2443180 100644
--- a/Doc/library/string.rst
+++ b/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
----------------
diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst
index 1e89bd0..5b2509a 100644
--- a/Doc/library/sysconfig.rst
+++ b/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
diff --git a/Doc/library/urllib.parse.rst b/Doc/library/urllib.parse.rst
index c77a679..aece714 100644
--- a/Doc/library/urllib.parse.rst
+++ b/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"
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
index 3282054..019a894 100644
--- a/Doc/library/zipfile.rst
+++ b/Doc/library/zipfile.rst
@@ -30,15 +30,16 @@
.. 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
diff --git a/Lib/shutil.py b/Lib/shutil.py
index d2e2dc5..7789cec 100644
--- a/Lib/shutil.py
+++ b/Lib/shutil.py
@@ -398,7 +398,7 @@
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)