From 0519b09936d1ec0ea0f339e733ba454905c3f543 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:39:19 +0200 Subject: [PATCH 01/19] Avoid splitting a word between a link and text --- Doc/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 2003e0bc9a7..9d63bc49c6e 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -163,8 +163,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 `.) Instead, it + typically employs :func:`hasattr` tests or :term:`EAFP` programming. EAFP Easier to ask for forgiveness than permission. This common Python coding From 6e7d0ba309757421905f4df4ca4f752680c1df53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:39:57 +0200 Subject: [PATCH 02/19] Add missing reST target for one section of this file --- Doc/library/cmd.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst index e9a049fd8ab..30f17262b64 100644 --- a/Doc/library/cmd.rst +++ b/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 ----------- From 889a7dcb3a113508b9e0298dda5ba3ee6cfc2808 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:40:46 +0200 Subject: [PATCH 03/19] Fix a typo and touch up blank lines --- Doc/library/collections.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 4975f747706..bf1fe2c6c0b 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -1,4 +1,3 @@ - :mod:`collections` --- Container datatypes ========================================== @@ -886,7 +885,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): @@ -985,6 +984,7 @@ attribute. 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 From 5eada9416368f43a138f569447d36f3bff52b5f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:41:23 +0200 Subject: [PATCH 04/19] Fix markup to get a target instead of a comment --- Doc/library/logging.handlers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst index a18cf923293..c4dd438f5b2 100644 --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -790,7 +790,7 @@ possible, while any potentially slow operations (such as sending an email via -.. queue-listener: +.. _queue-listener: QueueListener ^^^^^^^^^^^^^ From d001ffe7455605219ae47867beb2b8eb643e4493 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:44:31 +0200 Subject: [PATCH 05/19] Minor improvements to BadZipFile and BadZipfile docs. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I made the doc for the compat alias BadZipfile shorter and used a directive to document deprecation. I figured there was no point of talking about zipfile.error (“the old name” that’s older than the other old name BadZipfile) in the 3.x docs so I just removed it. --- Doc/library/zipfile.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 3282054485d..019a894721e 100644 --- a/Doc/library/zipfile.rst +++ b/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 From 19f9b71ffea430bbab6fe993873bb2febd6f7af6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:49:18 +0200 Subject: [PATCH 06/19] Add a few missing source links from 2.7 and harmonize lib docs headers --- Doc/library/argparse.rst | 4 ++-- Doc/library/atexit.rst | 3 +++ Doc/library/concurrent.futures.rst | 4 ++-- Doc/library/optparse.rst | 8 ++++---- Doc/library/string.rst | 7 +++---- Doc/library/sysconfig.rst | 9 +++++---- Doc/library/urllib.parse.rst | 4 ++++ 7 files changed, 23 insertions(+), 16 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 8d602fed116..612c15263a0 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -6,10 +6,10 @@ .. moduleauthor:: Steven Bethard .. sectionauthor:: Steven Bethard -**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 diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst index 5b87b94ca15..f2dccc2c915 100644 --- a/Doc/library/atexit.rst +++ b/Doc/library/atexit.rst @@ -6,6 +6,9 @@ .. moduleauthor:: Skip Montanaro .. sectionauthor:: Skip Montanaro +**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/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index e5d13f37f3c..2359dd1ad0f 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/optparse.rst b/Doc/library/optparse.rst index fddc1fbe8b8..7d2d91bfb80 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -7,14 +7,14 @@ .. moduleauthor:: Greg Ward .. sectionauthor:: Greg Ward +.. 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 3f9ec0b7860..2443180f315 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 1e89bd02eed..5b2509a9096 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 -.. sectionauthor:: Tarek Ziade +.. moduleauthor:: Tarek Ziadé +.. sectionauthor:: Tarek Ziadé + .. 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 c77a6793fae..aece7149ef4 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" From 55b9fe232df1530403b3d79286f840dd1030f633 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:53:04 +0200 Subject: [PATCH 07/19] Remove class that was only useful with Sphinx autodoc --- Lib/packaging/metadata.py | 8 -------- 1 file changed, 8 deletions(-) diff --git a/Lib/packaging/metadata.py b/Lib/packaging/metadata.py index 53d91f74515..104600b54e9 100644 --- a/Lib/packaging/metadata.py +++ b/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 '' - -_MISSING = NoDefault() - - class Metadata: """The metadata of a release. From b931ab43452d5d71983efc459e495829e1f2a465 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:53:20 +0200 Subject: [PATCH 08/19] Fix typo --- Lib/packaging/database.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/packaging/database.py b/Lib/packaging/database.py index 0aaa0cdc91f..c733b7af674 100644 --- a/Lib/packaging/database.py +++ b/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 From 50e516aa8e981b767398dd0a0d42cb726bb35975 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 00:56:57 +0200 Subject: [PATCH 09/19] =?UTF-8?q?Improve=20=E2=80=9Cpysetup=20create?= =?UTF-8?q?=E2=80=9D=20help=20messages.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The example version numbers were invalid and “package” was misused. I also made lines shorter, replaced “e-mail” with “email” (more common in the stdlib and I believe in English generally) and tweaked a few other things. --- Lib/packaging/create.py | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/Lib/packaging/create.py b/Lib/packaging/create.py index 917b6cf8496..8f391724c2f 100644 --- a/Lib/packaging/create.py +++ b/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'], From fde924263149c69400d8ec55114b0c92ee400a3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 01:30:26 +0200 Subject: [PATCH 10/19] =?UTF-8?q?Don=E2=80=99t=20use=20=E2=80=9Carg?= =?UTF-8?q?=E2=80=9D=20for=20=E2=80=9Cargument=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Doc/library/argparse.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 612c15263a0..b58a58cee52 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -109,7 +109,7 @@ Parsing arguments :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:: @@ -771,11 +771,11 @@ values are: 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 @@ values are: * ``'+'``. 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 @@ values are: 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 @@ the various :class:`ArgumentParser` actions. The two most common uses of it are (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 @@ default 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:: @@ -871,7 +871,7 @@ was not present at the command line:: Namespace(foo=42) For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value -is used when no command-line arg was present:: +is used when no command-line argument was present:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', nargs='?', default=42) @@ -957,8 +957,8 @@ choices 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 @@ value as the "name" of each object. By default, for positional argument 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() @@ -1168,7 +1168,7 @@ The parse_args() method 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. @@ -1244,7 +1244,7 @@ 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 @@ -1398,7 +1398,7 @@ Sub-commands >>> 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']) From 543edbdab8e1853827a8c5bf9c226120a2472238 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 01:45:12 +0200 Subject: [PATCH 11/19] =?UTF-8?q?Don=E2=80=99t=20quote=20characters=20twic?= =?UTF-8?q?e.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ``code`` markup is enough to mark command-line fragments or to talk about a character. ``'c'`` is still used for actual Python string objects. I did a similar change in optparse.rst in r86521. I’ve also ported two minor changes from the 3.3 version of the file (removing an unnecessary module name in a class directive, adding a comma). --- Doc/library/argparse.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index b58a58cee52..38e52fb1577 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -244,7 +244,7 @@ This can be achieved by passing ``False`` as the ``add_help=`` argument to --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 @@ the help options:: 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 @@ to the ArgumentParser constructor:: 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 @@ 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,7 +421,7 @@ 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`, @@ -759,7 +759,7 @@ single action to be taken. The ``nargs`` keyword argument associates a 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() @@ -870,7 +870,7 @@ was not present at the command line:: >>> parser.parse_args(''.split()) Namespace(foo=42) -For positional arguments with nargs_ ``='?'`` or ``'*'``, the ``default`` value +For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value is used when no command-line argument was present:: >>> parser = argparse.ArgumentParser() @@ -1133,10 +1133,10 @@ attribute is determined by the ``dest`` keyword argument of 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:: @@ -1239,15 +1239,15 @@ it exits and prints the error along with a usage message:: 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 argument ``'-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 @@ there are no options in the parser that look like negative numbers:: 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:: @@ -1407,8 +1407,8 @@ Sub-commands 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 From e8b7eb07e1e911c7f692b25b4aa8021abb578fbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 02:17:03 +0200 Subject: [PATCH 12/19] Link isinstance/issubclass to the ABC glossary entry (#12256) --- Doc/library/functions.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index edff106d081..3b6fdc370fc 100644 --- a/Doc/library/functions.rst +++ b/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 `) 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 + `) 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. From e197df06fb466cbeda5d3117b29fe2705ad43aa5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 02:30:15 +0200 Subject: [PATCH 13/19] Remove obsolete term + indicate how to find the program (#1626300). Suggested by Terry J. Reedy. --- Doc/distutils/introduction.rst | 4 ++-- Doc/install/index.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst index 57d34a4b57e..0ece646c345 100644 --- a/Doc/distutils/introduction.rst +++ b/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 diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 171ef984ebc..9112c0f1584 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -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 (:menuselection:`Start --> Accessories`) and run:: cd c:\Temp\foo-1.0 python setup.py install From 43a7ee1f3b478e4b2220bb5217c70d1b08e9d344 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 02:55:11 +0200 Subject: [PATCH 14/19] Make logging call lazy --- Lib/shutil.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/shutil.py b/Lib/shutil.py index d2e2dc52fc9..7789cec2fb4 100644 --- a/Lib/shutil.py +++ b/Lib/shutil.py @@ -398,7 +398,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) From a2d26182e28e99a66d9ed128f429d17ea53d48ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 03:12:38 +0200 Subject: [PATCH 15/19] Fix instance I missed in 59f7bbe1236c (#1626300) --- Doc/install/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 9112c0f1584..9d916d3d228 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.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 windows +(: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 (:menuselection:`Start --> Accessories`) and run:: +command prompt window and run:: cd c:\Temp\foo-1.0 python setup.py install From 4d71a66a01fec95556bc7f61f7e9ac29d66efe76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 03:44:36 +0200 Subject: [PATCH 16/19] Fix typo in command name --- Doc/distutils/setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst index 606ea0f2f46..80292432a9c 100644 --- a/Doc/distutils/setupscript.rst +++ b/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 From 87552785c3f5e80dea44b170e790d7d29602e758 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 03:53:51 +0200 Subject: [PATCH 17/19] Mark abc.abstractproperty as a property --- Doc/library/abc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 2776dbf9b61..5afc8475eab 100644 --- a/Doc/library/abc.rst +++ b/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. From 04ac59a22a16e2c95a6a86d0127c29016431819e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 09:07:46 +0200 Subject: [PATCH 18/19] Mention virtual subclasses in the glossary entry for ABCs (#12256). MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I added a link from the term “virtual subclass” to the glossary entry for ABCs but this was not enough, now the glossary briefly defines “virtual” and links to the abc module doc which contains more mentions of virtual subclasses. --- Doc/glossary.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 9d63bc49c6e..63d4c2bd498 100644 --- a/Doc/glossary.rst +++ b/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 `). Python comes with many built-in ABCs for + :ref:`magic methods `). 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 From 355d48ad8374d4b0f2ac40ad274104bff861ea5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 09:28:46 +0200 Subject: [PATCH 19/19] Typo --- Doc/install/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/install/index.rst b/Doc/install/index.rst index 9d916d3d228..b20f1fbd171 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -101,7 +101,7 @@ one command from a terminal:: python setup.py install -For Windows, this command should be run from a command prompt windows +For Windows, this command should be run from a command prompt window (:menuselection:`Start --> Accessories`):: setup.py install