[Python-checkins] cpython (2.7): Update argparse docs to follow order of ArgumentParser() arguments.
andrew.svetlov
python-checkins at python.org
Sun Apr 7 13:47:20 CEST 2013
http://hg.python.org/cpython/rev/4712f9f8a90d
changeset: 83177:4712f9f8a90d
branch: 2.7
parent: 83169:d7aa625147f7
user: Andrew Svetlov <andrew.svetlov at gmail.com>
date: Sun Apr 07 14:45:37 2013 +0300
summary:
Update argparse docs to follow order of ArgumentParser() arguments.
files:
Doc/library/argparse.rst | 411 +++++++++++++-------------
Misc/ACKS | 1 +
2 files changed, 207 insertions(+), 205 deletions(-)
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -137,40 +137,136 @@
argument_default=None, conflict_handler='error', \
add_help=True)
- Create a new :class:`ArgumentParser` object. Each parameter has its own more
- detailed description below, but in short they are:
+ Create a new :class:`ArgumentParser` object. All parameters should be passed
+ as keyword arguments. Each parameter has its own more detailed description
+ below, but in short they are:
- * description_ - Text to display before the argument help.
+ * prog_ - The name of the program (default: ``sys.argv[0]``)
- * epilog_ - Text to display after the argument help.
+ * usage_ - The string describing the program usage (default: generated from
+ arguments added to parser)
- * add_help_ - Add a -h/--help option to the parser. (default: ``True``)
+ * description_ - Text to display before the argument help (default: none)
- * argument_default_ - Set the global default value for arguments.
- (default: ``None``)
+ * epilog_ - Text to display after the argument help (default: none)
* parents_ - A list of :class:`ArgumentParser` objects whose arguments should
- also be included.
+ also be included
- * prefix_chars_ - The set of characters that prefix optional arguments.
+ * formatter_class_ - A class for customizing the help output
+
+ * prefix_chars_ - The set of characters that prefix optional arguments
(default: '-')
* fromfile_prefix_chars_ - The set of characters that prefix files from
- which additional arguments should be read. (default: ``None``)
+ which additional arguments should be read (default: ``None``)
- * formatter_class_ - A class for customizing the help output.
+ * argument_default_ - The global default value for arguments
+ (default: ``None``)
- * conflict_handler_ - Usually unnecessary, defines strategy for resolving
- conflicting optionals.
+ * conflict_handler_ - The strategy for resolving conflicting optionals
+ (usually unnecessary)
- * prog_ - The name of the program (default:
- ``sys.argv[0]``)
-
- * usage_ - The string describing the program usage (default: generated)
+ * add_help_ - Add a -h/--help option to the parser (default: ``True``)
The following sections describe how each of these are used.
+prog
+^^^^
+
+By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine
+how to display the name of the program in help messages. This default is almost
+always desirable because it will make the help messages match how the program was
+invoked on the command line. For example, consider a file named
+``myprogram.py`` with the following code::
+
+ import argparse
+ parser = argparse.ArgumentParser()
+ parser.add_argument('--foo', help='foo help')
+ args = parser.parse_args()
+
+The help for this program will display ``myprogram.py`` as the program name
+(regardless of where the program was invoked from)::
+
+ $ python myprogram.py --help
+ usage: myprogram.py [-h] [--foo FOO]
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --foo FOO foo help
+ $ cd ..
+ $ python subdir\myprogram.py --help
+ usage: myprogram.py [-h] [--foo FOO]
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --foo FOO foo help
+
+To change this default behavior, another value can be supplied using the
+``prog=`` argument to :class:`ArgumentParser`::
+
+ >>> parser = argparse.ArgumentParser(prog='myprogram')
+ >>> parser.print_help()
+ usage: myprogram [-h]
+
+ optional arguments:
+ -h, --help show this help message and exit
+
+Note that the program name, whether determined from ``sys.argv[0]`` or from the
+``prog=`` argument, is available to help messages using the ``%(prog)s`` format
+specifier.
+
+::
+
+ >>> parser = argparse.ArgumentParser(prog='myprogram')
+ >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
+ >>> parser.print_help()
+ usage: myprogram [-h] [--foo FOO]
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --foo FOO foo of the myprogram program
+
+
+usage
+^^^^^
+
+By default, :class:`ArgumentParser` calculates the usage message from the
+arguments it contains::
+
+ >>> parser = argparse.ArgumentParser(prog='PROG')
+ >>> parser.add_argument('--foo', nargs='?', help='foo help')
+ >>> parser.add_argument('bar', nargs='+', help='bar help')
+ >>> parser.print_help()
+ usage: PROG [-h] [--foo [FOO]] bar [bar ...]
+
+ positional arguments:
+ bar bar help
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --foo [FOO] foo help
+
+The default message can be overridden with the ``usage=`` keyword argument::
+
+ >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
+ >>> parser.add_argument('--foo', nargs='?', help='foo help')
+ >>> parser.add_argument('bar', nargs='+', help='bar help')
+ >>> parser.print_help()
+ usage: PROG [options]
+
+ positional arguments:
+ bar bar help
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --foo [FOO] foo help
+
+The ``%(prog)s`` format specifier is available to fill in the program name in
+your usage messages.
+
+
description
^^^^^^^^^^^
@@ -218,122 +314,6 @@
argument to :class:`ArgumentParser`.
-add_help
-^^^^^^^^
-
-By default, ArgumentParser objects add an option which simply displays
-the parser's help message. For example, consider a file named
-``myprogram.py`` containing the following code::
-
- import argparse
- parser = argparse.ArgumentParser()
- parser.add_argument('--foo', help='foo help')
- args = parser.parse_args()
-
-If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
-help will be printed::
-
- $ python myprogram.py --help
- usage: myprogram.py [-h] [--foo FOO]
-
- optional arguments:
- -h, --help show this help message and exit
- --foo FOO foo help
-
-Occasionally, it may be useful to disable the addition of this help option.
-This can be achieved by passing ``False`` as the ``add_help=`` argument to
-:class:`ArgumentParser`::
-
- >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
- >>> parser.add_argument('--foo', help='foo help')
- >>> parser.print_help()
- usage: PROG [--foo FOO]
-
- optional arguments:
- --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
-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::
-
- >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
- >>> parser.print_help()
- usage: PROG [+h]
-
- optional arguments:
- +h, ++help show this help message and exit
-
-
-prefix_chars
-^^^^^^^^^^^^
-
-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
-to the ArgumentParser constructor::
-
- >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
- >>> parser.add_argument('+f')
- >>> parser.add_argument('++bar')
- >>> parser.parse_args('+f X ++bar Y'.split())
- 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
-disallowed.
-
-
-fromfile_prefix_chars
-^^^^^^^^^^^^^^^^^^^^^
-
-Sometimes, for example when dealing with a particularly long argument lists, it
-may make sense to keep the list of arguments in a file rather than typing it out
-at the command line. If the ``fromfile_prefix_chars=`` argument is given to the
-:class:`ArgumentParser` constructor, then arguments that start with any of the
-specified characters will be treated as files, and will be replaced by the
-arguments they contain. For example::
-
- >>> with open('args.txt', 'w') as fp:
- ... fp.write('-f\nbar')
- >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
- >>> parser.add_argument('-f')
- >>> parser.parse_args(['-f', 'foo', '@args.txt'])
- Namespace(f='bar')
-
-Arguments read from a file must by default be one per line (but see also
-:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
-were in the same place as the original file referencing argument on the command
-line. So in the example above, the expression ``['-f', 'foo', '@args.txt']``
-is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
-
-The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
-arguments will never be treated as file references.
-
-
-argument_default
-^^^^^^^^^^^^^^^^
-
-Generally, argument defaults are specified either by passing a default to
-:meth:`~ArgumentParser.add_argument` or by calling the
-:meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value
-pairs. Sometimes however, it may be useful to specify a single parser-wide
-default for arguments. This can be accomplished by passing the
-``argument_default=`` keyword argument to :class:`ArgumentParser`. For example,
-to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
-calls, we supply ``argument_default=SUPPRESS``::
-
- >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
- >>> parser.add_argument('--foo')
- >>> parser.add_argument('bar', nargs='?')
- >>> parser.parse_args(['--foo', '1', 'BAR'])
- Namespace(bar='BAR', foo='1')
- >>> parser.parse_args([])
- Namespace()
-
-
parents
^^^^^^^
@@ -452,6 +432,74 @@
--foo FOO FOO! (default: 42)
+prefix_chars
+^^^^^^^^^^^^
+
+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
+to the ArgumentParser constructor::
+
+ >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
+ >>> parser.add_argument('+f')
+ >>> parser.add_argument('++bar')
+ >>> parser.parse_args('+f X ++bar Y'.split())
+ 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
+disallowed.
+
+
+fromfile_prefix_chars
+^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes, for example when dealing with a particularly long argument lists, it
+may make sense to keep the list of arguments in a file rather than typing it out
+at the command line. If the ``fromfile_prefix_chars=`` argument is given to the
+:class:`ArgumentParser` constructor, then arguments that start with any of the
+specified characters will be treated as files, and will be replaced by the
+arguments they contain. For example::
+
+ >>> with open('args.txt', 'w') as fp:
+ ... fp.write('-f\nbar')
+ >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
+ >>> parser.add_argument('-f')
+ >>> parser.parse_args(['-f', 'foo', '@args.txt'])
+ Namespace(f='bar')
+
+Arguments read from a file must by default be one per line (but see also
+:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
+were in the same place as the original file referencing argument on the command
+line. So in the example above, the expression ``['-f', 'foo', '@args.txt']``
+is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
+
+The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
+arguments will never be treated as file references.
+
+
+argument_default
+^^^^^^^^^^^^^^^^
+
+Generally, argument defaults are specified either by passing a default to
+:meth:`~ArgumentParser.add_argument` or by calling the
+:meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value
+pairs. Sometimes however, it may be useful to specify a single parser-wide
+default for arguments. This can be accomplished by passing the
+``argument_default=`` keyword argument to :class:`ArgumentParser`. For example,
+to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
+calls, we supply ``argument_default=SUPPRESS``::
+
+ >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
+ >>> parser.add_argument('--foo')
+ >>> parser.add_argument('bar', nargs='?')
+ >>> parser.parse_args(['--foo', '1', 'BAR'])
+ Namespace(bar='BAR', foo='1')
+ >>> parser.parse_args([])
+ Namespace()
+
+
conflict_handler
^^^^^^^^^^^^^^^^
@@ -489,22 +537,20 @@
string was overridden.
-prog
-^^^^
+add_help
+^^^^^^^^
-By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine
-how to display the name of the program in help messages. This default is almost
-always desirable because it will make the help messages match how the program was
-invoked on the command line. For example, consider a file named
-``myprogram.py`` with the following code::
+By default, ArgumentParser objects add an option which simply displays
+the parser's help message. For example, consider a file named
+``myprogram.py`` containing the following code::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
-The help for this program will display ``myprogram.py`` as the program name
-(regardless of where the program was invoked from)::
+If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
+help will be printed::
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
@@ -512,76 +558,31 @@
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
- $ cd ..
- $ python subdir\myprogram.py --help
- usage: myprogram.py [-h] [--foo FOO]
+
+Occasionally, it may be useful to disable the addition of this help option.
+This can be achieved by passing ``False`` as the ``add_help=`` argument to
+:class:`ArgumentParser`::
+
+ >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
+ >>> parser.add_argument('--foo', help='foo help')
+ >>> parser.print_help()
+ usage: PROG [--foo FOO]
optional arguments:
- -h, --help show this help message and exit
- --foo FOO foo help
+ --foo FOO foo help
-To change this default behavior, another value can be supplied using the
-``prog=`` argument to :class:`ArgumentParser`::
+The help option is typically ``-h/--help``. The exception to this is
+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::
- >>> parser = argparse.ArgumentParser(prog='myprogram')
+ >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
- usage: myprogram [-h]
+ usage: PROG [-h]
optional arguments:
- -h, --help show this help message and exit
-
-Note that the program name, whether determined from ``sys.argv[0]`` or from the
-``prog=`` argument, is available to help messages using the ``%(prog)s`` format
-specifier.
-
-::
-
- >>> parser = argparse.ArgumentParser(prog='myprogram')
- >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
- >>> parser.print_help()
- usage: myprogram [-h] [--foo FOO]
-
- optional arguments:
- -h, --help show this help message and exit
- --foo FOO foo of the myprogram program
-
-
-usage
-^^^^^
-
-By default, :class:`ArgumentParser` calculates the usage message from the
-arguments it contains::
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('--foo', nargs='?', help='foo help')
- >>> parser.add_argument('bar', nargs='+', help='bar help')
- >>> parser.print_help()
- usage: PROG [-h] [--foo [FOO]] bar [bar ...]
-
- positional arguments:
- bar bar help
-
- optional arguments:
- -h, --help show this help message and exit
- --foo [FOO] foo help
-
-The default message can be overridden with the ``usage=`` keyword argument::
-
- >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
- >>> parser.add_argument('--foo', nargs='?', help='foo help')
- >>> parser.add_argument('bar', nargs='+', help='bar help')
- >>> parser.print_help()
- usage: PROG [options]
-
- positional arguments:
- bar bar help
-
- optional arguments:
- -h, --help show this help message and exit
- --foo [FOO] foo help
-
-The ``%(prog)s`` format specifier is available to fill in the program name in
-your usage messages.
+ -h, --help show this help message and exit
The add_argument() method
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -593,6 +593,7 @@
Tshepang Lekhonkhobe
Marc-André Lemburg
John Lenton
+Kostyantyn Leschenko
Christopher Tur Lesniewski-Laas
Mark Levinson
William Lewis
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list