Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
C
cpython
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
Kirill Smelkov
cpython
Commits
aff9ceff
Commit
aff9ceff
authored
Apr 07, 2013
by
Andrew Svetlov
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Update argparse docs to follow order of ArgumentParser() arguments.
parent
75b249c9
Changes
2
Show whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
204 additions
and
202 deletions
+204
-202
Doc/library/argparse.rst
Doc/library/argparse.rst
+203
-202
Misc/ACKS
Misc/ACKS
+1
-0
No files found.
Doc/library/argparse.rst
View file @
aff9ceff
...
@@ -137,201 +137,181 @@ ArgumentParser objects
...
@@ -137,201 +137,181 @@ ArgumentParser objects
argument_default=None, conflict_handler='error', \
argument_default=None, conflict_handler='error', \
add_help=True)
add_help=True)
Create a new :class:`ArgumentParser` object. Each parameter has its own more
Create a new :class:`ArgumentParser` object. All parameters should be passed
detailed description below, but in short they are:
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.
* epilog_ - Text to display after the argument help (default: none)
(default: ``None``)
* parents_ - A list of :class:`ArgumentParser` objects whose arguments should
* parents_ - A list of :class:`ArgumentParser` objects whose arguments should
also be included.
also be included
* formatter_class_ - A class for customizing the help output
* prefix_chars_ - The set of characters that prefix optional arguments
.
* prefix_chars_ - The set of characters that prefix optional arguments
(default: '-')
(default: '-')
* fromfile_prefix_chars_ - The set of characters that prefix files from
* 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.
*
conflict_handler_ - Usually unnecessary, defines strategy for resolving
*
argument_default_ - The global default value for arguments
conflicting optionals.
(default: ``None``)
*
prog_ - The name of the program (default:
*
conflict_handler_ - The strategy for resolving conflicting optionals
``sys.argv[0]``
)
(usually unnecessary
)
*
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.
The following sections describe how each of these are used.
description
prog
^^^^
^^^^^^^
^^^^
Most calls to the :class:`ArgumentParser` constructor will use th
e
By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determin
e
``description=`` keyword argument. This argument gives a brief description of
how to display the name of the program in help messages. This default is almost
what the program does and how it works. In help messages, the description i
s
always desirable because it will make the help messages match how the program wa
s
displayed between the command-line usage string and the help messages for the
invoked on the command line. For example, consider a file named
various arguments
::
``myprogram.py`` with the following code
::
>>> parser = argparse.ArgumentParser(description='A foo that bars')
import argparse
>>> parser.print_help()
parser = argparse.ArgumentParser()
usage: argparse.py [-h]
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
A foo that bars
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:
optional arguments:
-h, --help show this help message and exit
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir\myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
By default, the description will be line-wrapped so that it fits within the
optional arguments:
given space. To change this behavior, see the formatter_class_ argument.
-h, --help show this help message and exit
--foo FOO foo help
epilog
^^^^^^
Some programs like to display additional description of the program after the
To change this default behavior, another value can be supplied using the
description of the arguments. Such text can be specified using the ``epilog=``
``prog=`` argument to :class:`ArgumentParser`::
argument to :class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(
>>> parser = argparse.ArgumentParser(prog='myprogram')
... description='A foo that bars',
... epilog="And that's how you'd foo a bar")
>>> parser.print_help()
>>> parser.print_help()
usage: argparse.py [-h]
usage: myprogram [-h]
A foo that bars
optional arguments:
optional arguments:
-h, --help show this help message and exit
-h, --help show this help message and exit
And that's how you'd foo a bar
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.
As with the description_ argument, the ``epilog=`` text is by default
::
line-wrapped, but this behavior can be adjusted with the formatter_class_
argument to :class:`ArgumentParser`.
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
add_help
optional arguments:
^^^^^^^^
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
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
usage
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
By default, :class:`ArgumentParser` calculates the usage message from the
help will be printed
::
arguments it contains
::
$ python myprogram.py --help
>>> parser = argparse.ArgumentParser(prog='PROG')
usage: myprogram.py [-h] [--foo FOO]
>>> 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:
optional arguments:
-h, --help show this help message and exit
-h, --help show this help message and exit
--foo
FOO
foo help
--foo
[FOO]
foo help
Occasionally, it may be useful to disable the addition of this help option.
The default message can be overridden with the ``usage=`` keyword argument::
This can be achieved by passing ``False`` as the ``add_help=`` argument to
:class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', help='foo help')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
>>> parser.print_help()
usage: PROG [--foo FOO]
usage: PROG [options]
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='+/')
positional arguments:
>>> parser.print_help()
bar bar help
usage: PROG [+h]
optional arguments:
optional arguments:
+h, ++help show this help message and exit
-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.
prefix_chars
^^^^^^^^^^^^
Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
description
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='-+')
Most calls to the :class:`ArgumentParser` constructor will use the
>>> parser.add_argument('+f')
``description=`` keyword argument. This argument gives a brief description of
>>> parser.add_argument('++bar')
what the program does and how it works. In help messages, the description is
>>> parser.parse_args('+f X ++bar Y'.split())
displayed between the command-line usage string and the help messages for the
Namespace(bar='Y', f='X')
various arguments::
The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
>>> parser = argparse.ArgumentParser(description='A foo that bars')
characters that does not include ``-`` will cause ``-f/--foo`` options to be
>>> parser.print_help()
disallowed.
usage: argparse.py [-h]
A foo that bars
fromfile_prefix_chars
optional arguments:
^^^^^^^^^^^^^^^^^^^^^
-h, --help show this help message and exit
Sometimes, for example when dealing with a particularly long argument lists, it
By default, the description will be line-wrapped so that it fits within the
may make sense to keep the list of arguments in a file rather than typing it out
given space. To change this behavior, see the formatter_class_ argument.
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
epilog
: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
Some programs like to display additional description of the program after the
arguments will never be treated as file references.
description of the arguments. Such text can be specified using the ``epilog=``
argument to :class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(
... description='A foo that bars',
... epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
argument_default
optional arguments:
^^^^^^^^^^^^^^^^
-h, --help show this help message and exit
Generally, argument defaults are specified either by passing a default to
And that's how you'd foo a bar
: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)
As with the description_ argument, the ``epilog=`` text is by default
>>> parser.add_argument('--foo')
line-wrapped, but this behavior can be adjusted with the formatter_class_
>>> parser.add_argument('bar', nargs='?')
argument to :class:`ArgumentParser`.
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()
parents
parents
...
@@ -452,6 +432,74 @@ will add information about the default value of each of the arguments::
...
@@ -452,6 +432,74 @@ will add information about the default value of each of the arguments::
--foo FOO FOO! (default: 42)
--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
conflict_handler
^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^
...
@@ -489,22 +537,20 @@ action is retained as the ``-f`` action, because only the ``--foo`` option
...
@@ -489,22 +537,20 @@ action is retained as the ``-f`` action, because only the ``--foo`` option
string was overridden.
string was overridden.
prog
add_help
^^^^
^^^^
^^^^
By default, :class:`ArgumentParser` objects uses ``sys.argv[0]`` to determine
By default, ArgumentParser objects add an option which simply displays
how to display the name of the program in help messages. This default is almost
the parser's help message. For example, consider a file named
always desirable because it will make the help messages match how the program was
``myprogram.py`` containing the following code::
invoked on the command line. For example, consider a file named
``myprogram.py`` with the following code::
import argparse
import argparse
parser = argparse.ArgumentParser()
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
args = parser.parse_args()
The help for this program will display ``myprogram.py`` as the program name
If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
(regardless of where the program was invoked from)
::
help will be printed
::
$ python myprogram.py --help
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
usage: myprogram.py [-h] [--foo FOO]
...
@@ -512,76 +558,31 @@ The help for this program will display ``myprogram.py`` as the program name
...
@@ -512,76 +558,31 @@ The help for this program will display ``myprogram.py`` as the program name
optional arguments:
optional arguments:
-h, --help show this help message and exit
-h, --help show this help message and exit
--foo FOO foo help
--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
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`::
By default, :class:`ArgumentParser` calculates the usage message from the
arguments it contains::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('--foo', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]
usage: PROG [--foo FOO]
positional arguments:
bar bar help
optional arguments:
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
--foo [FOO] foo help
The default message can be overridden with the ``usage=`` keyword argument::
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', usage='%(prog)s [options]')
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
>>> parser.print_help()
usage: PROG [options]
usage: PROG [-h]
positional arguments:
bar bar help
optional arguments:
optional arguments:
-h, --help show this help message and exit
-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.
The add_argument() method
The add_argument() method
...
...
Misc/ACKS
View file @
aff9ceff
...
@@ -593,6 +593,7 @@ Luke Kenneth Casson Leighton
...
@@ -593,6 +593,7 @@ Luke Kenneth Casson Leighton
Tshepang Lekhonkhobe
Tshepang Lekhonkhobe
Marc-André Lemburg
Marc-André Lemburg
John Lenton
John Lenton
Kostyantyn Leschenko
Christopher Tur Lesniewski-Laas
Christopher Tur Lesniewski-Laas
Mark Levinson
Mark Levinson
William Lewis
William Lewis
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment