diff options
| -rw-r--r-- | Doc/library/argparse.rst | 470 |
1 files changed, 221 insertions, 249 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 7e74a68..f3962e0 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -9,17 +9,16 @@ The :mod:`argparse` module makes it easy to write user friendly command line -interfaces. You define what arguments your program requires, and :mod:`argparse` +interfaces. The program defines what arguments it requires, and :mod:`argparse` will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse` -module also automatically generates help and usage messages based on the -arguments you have defined, and issues errors when users give your program -invalid arguments. +module also automatically generates help and usage messages and issues errors +when users give the program invalid arguments. Example ------- -As an example, the following code is a Python program that takes a list of -integers and produces either the sum or the max:: +The following code is a Python program that takes a list of integers and +produces either the sum or the max:: import argparse @@ -68,24 +67,23 @@ The following sections walk you through this example. Creating a parser ^^^^^^^^^^^^^^^^^ -Pretty much every script that uses the :mod:`argparse` module will start out by -creating an :class:`ArgumentParser` object:: +Mose uses of the :mod:`argparse` module will start out by creating an +:class:`ArgumentParser` object:: >>> parser = argparse.ArgumentParser(description='Process some integers.') The :class:`ArgumentParser` object will hold all the information necessary to -parse the command line into a more manageable form for your program. +parse the command line into python data types. Adding arguments ^^^^^^^^^^^^^^^^ -Once you've created an :class:`ArgumentParser`, you'll want to fill it with -information about your program arguments. You typically do this by making calls -to the :meth:`add_argument` method. Generally, these calls tell the -:class:`ArgumentParser` how to take the strings on the command line and turn -them into objects for you. This information is stored and used when -:meth:`parse_args` is called. For example, if we add some arguments like this:: +Filling an :class:`ArgumentParser` with information about program arguments is +done by making calls to the :meth:`~ArgumentParser.add_argument` method. +Generally, these calls tell the :class:`ArgumentParser` how to take the strings +on the command line and turn them into objects. This information is stored and +used when :meth:`~ArgumentParser.parse_args` is called. For example:: >>> parser.add_argument('integers', metavar='N', type=int, nargs='+', ... help='an integer for the accumulator') @@ -93,7 +91,7 @@ them into objects for you. This information is stored and used when ... const=sum, default=max, ... help='sum the integers (default: find the max)') -when we later call :meth:`parse_args`, we can expect it to return an object with +Later, calling :meth:`parse_args` will return an object with two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute will be a list of one or more ints, and the ``accumulate`` attribute will be either the :func:`sum` function, if ``--sum`` was specified at the command line, @@ -102,9 +100,8 @@ or the :func:`max` function if it was not. Parsing arguments ^^^^^^^^^^^^^^^^^ -Once an :class:`ArgumentParser` has been initialized with appropriate calls to -:meth:`add_argument`, it can be instructed to parse the command-line args by -calling the :meth:`parse_args` method. This will inspect the command-line, +:class:`ArgumentParser` parses args 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. In most cases, this means a simple namespace object will be built up from attributes parsed out of the command-line:: @@ -112,10 +109,9 @@ attributes parsed out of the command-line:: >>> parser.parse_args(['--sum', '7', '-1', '42']) Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42]) -In a script, :meth:`parse_args` will typically be called with no arguments, and -the :class:`ArgumentParser` will automatically determine the command-line args -from :data:`sys.argv`. That's pretty much it. You're now ready to go write -some command line interfaces! +In a script, :meth:`~ArgumentParser.parse_args` will typically be called with no +arguments, and the :class:`ArgumentParser` will automatically determine the +command-line args from :data:`sys.argv`. ArgumentParser objects @@ -130,41 +126,41 @@ ArgumentParser objects * epilog_ - Text to display after the argument help. - * add_help_ - Add a -h/--help option to the parser. (default: True) + * add_help_ - Add a -h/--help option to the parser. (default: ``True``) * argument_default_ - Set the global default value for arguments. - (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. * 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. * conflict_handler_ - Usually unnecessary, defines strategy for resolving conflicting optionals. - * prog_ - Usually unnecessary, the name of the program - (default: ``sys.argv[0]``) + * prog_ - The name of the program (default: + :data:`sys.argv[0]`) - * usage_ - Usually unnecessary, the string describing the program usage - (default: generated) + * usage_ - The string describing the program usage (default: generated) - The following sections describe how each of these are used. +The following sections describe how each of these are used. description ^^^^^^^^^^^ -Most calls to the ArgumentParser constructor will use the ``description=`` -keyword argument. This argument gives a brief description of what the program -does and how it works. In help messages, the description is displayed between -the command-line usage string and the help messages for the various arguments:: +Most calls to the :class:`ArgumentParser` constructor will use the +``description=`` keyword argument. This argument gives a brief description of +what the program does and how it works. In help messages, the description is +displayed between the command-line usage string and the help messages for the +various arguments:: >>> parser = argparse.ArgumentParser(description='A foo that bars') >>> parser.print_help() @@ -201,7 +197,7 @@ argument to :class:`ArgumentParser`:: 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 ArgumentParser. +argument to :class:`ArgumentParser`. add_help @@ -228,7 +224,7 @@ help will be printed:: 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 -ArgumentParser:: +:class:`ArgumentParser`:: >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) >>> parser.add_argument('--foo', help='foo help') @@ -261,14 +257,15 @@ disallowed. fromfile_prefix_chars ^^^^^^^^^^^^^^^^^^^^^ -Sometimes, e.g. for 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 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:: +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:: - >>> open('args.txt', 'w').write('-f\nbar') + >>> 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']) @@ -290,9 +287,9 @@ Generally, argument defaults are specified either by passing a default to :meth:`add_argument` or by calling the :meth:`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 ArgumentParser. For -example, to globally suppress attribute creation on :meth:`parse_args` calls, we -supply ``argument_default=SUPPRESS``:: +passing the ``argument_default=`` keyword argument to :class:`ArgumentParser`. +For example, to globally suppress attribute creation on :meth:`parse_args` +calls, we supply ``argument_default=SUPPRESS``:: >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS) >>> parser.add_argument('--foo') @@ -307,12 +304,11 @@ parents ^^^^^^^ Sometimes, several parsers share a common set of arguments. Rather than -repeating the definitions of these arguments, you can define a single parser -with all the shared arguments and then use the ``parents=`` argument to -ArgumentParser to have these "inherited". The ``parents=`` argument takes a -list of ArgumentParser objects, collects all the positional and optional actions -from them, and adds these actions to the ArgumentParser object being -constructed:: +repeating the definitions of these arguments, a single parser with all the +shared arguments and passed to ``parents=`` argument to :class:`ArgumentParser` +can be used. The ``parents=`` argument takes a list of :class:`ArgumentParser` +objects, collects all the positional and optional actions from them, and adds +these actions to the :class:`ArgumentParser` object being constructed:: >>> parent_parser = argparse.ArgumentParser(add_help=False) >>> parent_parser.add_argument('--parent', type=int) @@ -328,23 +324,23 @@ constructed:: Namespace(bar='YYY', parent=None) Note that most parent parsers will specify ``add_help=False``. Otherwise, the -ArgumentParser will see two ``-h/--help`` options (one in the parent and one in -the child) and raise an error. +:class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent +and one in the child) and raise an error. formatter_class ^^^^^^^^^^^^^^^ -ArgumentParser objects allow the help formatting to be customized by specifying -an alternate formatting class. Currently, there are three such classes: -:class:`argparse.RawDescriptionHelpFormatter`, +:class:`ArgumentParser` objects allow the help formatting to be customized by +specifying an alternate formatting class. Currently, there are three such +classes: :class:`argparse.RawDescriptionHelpFormatter`, :class:`argparse.RawTextHelpFormatter` and :class:`argparse.ArgumentDefaultsHelpFormatter`. The first two allow more control over how textual descriptions are displayed, while the last automatically adds information about argument default values. -By default, ArgumentParser objects line-wrap the description_ and epilog_ texts -in command-line help messages:: +By default, :class:`ArgumentParser` objects line-wrap the description_ and +epilog_ texts in command-line help messages:: >>> parser = argparse.ArgumentParser( ... prog='PROG', @@ -366,10 +362,9 @@ 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 -When you have description_ and epilog_ that is already correctly formatted and -should not be line-wrapped, you can indicate this by passing -``argparse.RawDescriptionHelpFormatter`` as the ``formatter_class=`` argument to -ArgumentParser:: +Passing :class:`argparse.RawDescriptionHelpFormatter` as ``formatter_class=`` +indicates that description_ and epilog_ are already correctly formatted and +should not be line-wrapped:: >>> parser = argparse.ArgumentParser( ... prog='PROG', @@ -393,10 +388,10 @@ ArgumentParser:: optional arguments: -h, --help show this help message and exit -If you want to maintain whitespace for all sorts of help text (including -argument descriptions), you can use ``argparse.RawTextHelpFormatter``. +:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text +including argument descriptions. -The other formatter class available, ``argparse.ArgumentDefaultsHelpFormatter``, +The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`, will add information about the default value of each of the arguments:: >>> parser = argparse.ArgumentParser( @@ -418,9 +413,10 @@ will add information about the default value of each of the arguments:: conflict_handler ^^^^^^^^^^^^^^^^ -ArgumentParser objects do not allow two actions with the same option string. By -default, ArgumentParser objects will raise an exception if you try to create an -argument with an option string that is already in use:: +:class:`ArgumentParser` objects do not allow two actions with the same option +string. By default, :class:`ArgumentParser` objects raises an exception if an +attempt is made to create an argument with an option string that is already in +use:: >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('-f', '--foo', help='old foo help') @@ -432,7 +428,7 @@ argument with an option string that is already in use:: Sometimes (e.g. when using parents_) it may be useful to simply override any older arguments with the same option string. To get this behavior, the value ``'resolve'`` can be supplied to the ``conflict_handler=`` argument of -ArgumentParser:: +:class:`ArgumentParser`:: >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve') >>> parser.add_argument('-f', '--foo', help='old foo help') @@ -445,20 +441,20 @@ ArgumentParser:: -f FOO old foo help --foo FOO new foo help -Note that ArgumentParser objects only remove an action if all of its option -strings are overridden. So, in the example above, the old ``-f/--foo`` action -is retained as the ``-f`` action, because only the ``--foo`` option string was -overridden. +Note that :class:`ArgumentParser` objects only remove an action if all of its +option strings are overridden. So, in the example above, the old ``-f/--foo`` +action is retained as the ``-f`` action, because only the ``--foo`` option +string was overridden. prog ^^^^ -By default, ArgumentParser objects use ``sys.argv[0]`` to determine how to -display the name of the program in help messages. This default is almost always -what you want because it will make the help messages match what your users have -typed at the command line. For example, consider a file named ``myprogram.py`` -with the following code:: +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 pgoram was +invoked on the command line. For example, consider a file named +``myprogram.py`` with the following code:: import argparse parser = argparse.ArgumentParser() @@ -483,7 +479,7 @@ The help for this program will display ``myprogram.py`` as the program name --foo FOO foo help To change this default behavior, another value can be supplied using the -``prog=`` argument to ArgumentParser:: +``prog=`` argument to :class:`ArgumentParser`:: >>> parser = argparse.ArgumentParser(prog='myprogram') >>> parser.print_help() @@ -511,7 +507,7 @@ specifier. usage ^^^^^ -By default, ArgumentParser objects calculate the usage message from the +By default, :class:`ArgumentParser` calculates the usage message from the arguments it contains:: >>> parser = argparse.ArgumentParser(prog='PROG') @@ -527,9 +523,7 @@ arguments it contains:: -h, --help show this help message and exit --foo [FOO] foo help -If the default usage message is not appropriate for your application, you can -supply your own usage message using the ``usage=`` keyword argument to -ArgumentParser:: +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') @@ -544,14 +538,14 @@ ArgumentParser:: -h, --help show this help message and exit --foo [FOO] foo help -Note you can use the ``%(prog)s`` format specifier to fill in the program name -in your usage messages. +The ``%(prog)s`` format specifier is available to fill in the program name in +your usage messages. The add_argument() method ------------------------- -.. method:: add_argument(name or flags..., [action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest]) +.. method:: ArgumentParser.add_argument(name or flags..., [action], [nargs], [const], [default], [type], [choices], [required], [help], [metavar], [dest]) Define how a single command line argument should be parsed. Each parameter has its own more detailed description below, but in short they are: @@ -583,16 +577,16 @@ The add_argument() method * dest_ - The name of the attribute to be added to the object returned by :meth:`parse_args`. - The following sections describe how each of these are used. +The following sections describe how each of these are used. name or flags ^^^^^^^^^^^^^ -The :meth:`add_argument` method needs to know whether you're expecting an -optional argument, e.g. ``-f`` or ``--foo``, or a positional argument, e.g. a -list of filenames. The first arguments passed to :meth:`add_argument` must -therefore be either a series of flags, or a simple argument name. For example, -an optional argument could be created like:: +The :meth:`add_argument` method must know whether an optional argument, like +``-f`` or ``--foo``, or a positional argument, like a list of filenames, is +expected. The first arguments passed to :meth:`add_argument` must therefore be +either a series of flags, or a simple argument name. For example, an optional +argument could be created like:: >>> parser.add_argument('-f', '--foo') @@ -620,10 +614,8 @@ action :class:`ArgumentParser` objects associate command-line args with actions. These actions can do just about anything with the command-line args associated with them, though most actions simply add an attribute to the object returned by -:meth:`parse_args`. When you specify a new argument using the -:meth:`add_argument` method, you can indicate how the command-line args should -be handled by specifying the ``action`` keyword argument. The supported actions -are: +:meth:`parse_args`. The ``action`` keyword argument specifies how the +command-line args should be handled. The supported actions are: * ``'store'`` - This just stores the argument's value. This is the default action. For example:: @@ -634,10 +626,9 @@ are: Namespace(foo='1') * ``'store_const'`` - This stores the value specified by the const_ keyword - argument. Note that the const_ keyword argument defaults to ``None``, so - you'll almost always need to provide a value for it. The ``'store_const'`` - action is most commonly used with optional arguments that specify some sort - of flag. For example:: + argument. (Note that the const_ keyword argument defaults to the rather + unhelpful ``None``.) The ``'store_const'`` action is most commonly used with + optional arguments that specify some sort of flag. For example:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_const', const=42) @@ -645,8 +636,8 @@ are: Namespace(foo=42) * ``'store_true'`` and ``'store_false'`` - These store the values ``True`` and - ``False`` respectively. These are basically special cases of - ``'store_const'``. For example:: + ``False`` respectively. These are special cases of ``'store_const'``. For + example:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='store_true') @@ -655,8 +646,8 @@ are: Namespace(bar=False, foo=True) * ``'append'`` - This stores a list, and appends each argument value to the - list. This is useful when you want to allow an option to be specified - multiple times. Example usage:: + list. This is useful to allow an option to be specified multiple times. + Example usage:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', action='append') @@ -664,10 +655,10 @@ are: Namespace(foo=['1', '2']) * ``'append_const'`` - This stores a list, and appends the value specified by - the const_ keyword argument to the list. Note that the const_ keyword - argument defaults to ``None``, so you'll almost always need to provide a value - for it. The ``'append_const'`` action is typically useful when you want - multiple arguments to store constants to the same list, for example:: + the const_ keyword argument to the list. (Note that the const_ keyword + argument defaults to ``None``.) The ``'append_const'`` action is typically + useful when multiple arguments need to store constants to the same list. For + example:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--str', dest='types', action='append_const', const=str) @@ -686,9 +677,9 @@ are: PROG 2.0 You can also specify an arbitrary action by passing an object that implements -the Action API. The easiest way to do this is to extend ``argparse.Action``, -supplying an appropriate :meth:`__call__` method. The ``__call__`` method -accepts four parameters: +the Action API. The easiest way to do this is to extend +:class:`argparse.Action`, supplying an appropriate ``__call__`` method. The +``__call__`` method should accept four parameters: * ``parser`` - The ArgumentParser object which contains this action. @@ -703,7 +694,7 @@ accepts four parameters: The ``option_string`` argument is optional, and will be absent if the action is associated with a positional argument. -So for example:: +An example of a custom action:: >>> class FooAction(argparse.Action): ... def __call__(self, parser, namespace, values, option_string=None): @@ -724,9 +715,9 @@ nargs ^^^^^ ArgumentParser objects usually associate a single command-line argument with a -single action to be taken. In the situations where you'd like to associate a -different number of command-line arguments with a single action, you can use the -``nargs`` keyword argument to :meth:`add_argument`. The supported values are: +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 args from the command-line will be gathered together into a list. For example:: @@ -846,8 +837,8 @@ is used when no command-line arg was present:: Namespace(foo=42) -If you don't want to see an attribute when an option was not present at the -command line, you can supply ``default=argparse.SUPPRESS``:: +Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if the +command-line argument was not present.:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default=argparse.SUPPRESS) @@ -862,10 +853,10 @@ type By default, ArgumentParser objects read command-line args in as simple strings. However, quite often the command-line string should instead be interpreted as -another type, e.g. :class:`float`, :class:`int` or :class:`file`. The ``type`` -keyword argument of :meth:`add_argument` allows any necessary type-checking and -type-conversions to be performed. Many common builtin types can be used -directly as the value of the ``type`` argument:: +another type, like a :class:`float`, :class:`int` or :class:`file`. The +``type`` keyword argument of :meth:`add_argument` allows any necessary +type-checking and type-conversions to be performed. Many common builtin types +can be used directly as the value of the ``type`` argument:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', type=int) @@ -883,9 +874,8 @@ writable file:: >>> parser.parse_args(['out.txt']) Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>) -If you need to do some special type-checking or type-conversions, you can -provide your own types by passing to ``type=`` a callable that takes a single -string argument and returns the type-converted value:: +``type=`` can take any callable that takes a single string argument and returns +the type-converted value:: >>> def perfect_square(string): ... value = int(string) @@ -903,8 +893,8 @@ string argument and returns the type-converted value:: usage: PROG [-h] foo PROG: error: argument foo: '7' is not a perfect square -Note that if your type-checking function is just checking for a particular set -of values, it may be more convenient to use the choices_ keyword argument:: +The choices_ keyword argument may be more convenient for type checkers that +simply check against a range of values:: >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('foo', type=int, choices=xrange(5, 10)) @@ -921,11 +911,10 @@ choices ^^^^^^^ Some command-line args should be selected from a restricted set of values. -ArgumentParser objects can be told about such sets of values by passing a -container object as the ``choices`` keyword argument to :meth:`add_argument`. -When the command-line is parsed with :meth:`parse_args`, arg values will be -checked, and an error message will be displayed if the arg was not one of the -acceptable values:: +These can be handled by passing a container object as the ``choices`` keyword +argument to :meth:`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:: >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('foo', choices='abc') @@ -957,9 +946,8 @@ required In general, the argparse module assumes that flags like ``-f`` and ``--bar`` indicate *optional* arguments, which can always be omitted at the command-line. -To change this behavior, i.e. to make an option *required*, the value ``True`` -should be specified for the ``required=`` keyword argument to -:meth:`add_argument`:: +To make an option *required*, ``True`` can be specified for the ``required=`` +keyword argument to :meth:`add_argument`:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', required=True) @@ -972,20 +960,18 @@ should be specified for the ``required=`` keyword argument to As the example shows, if an option is marked as ``required``, :meth:`parse_args` will report an error if that option is not present at the command line. -**Warning:** Required options are generally considered bad form - normal users -expect *options* to be *optional*. You should avoid the use of required options -whenever possible. +.. note:: + + Required options are generally considered bad form because users expect + *options* to be *optional*, and thus they should be avoided when possible. help ^^^^ -A great command-line interface isn't worth anything if your users can't figure -out which option does what. So for the end-users, ``help`` is probably the most -important argument to include in your :meth:`add_argument` calls. The ``help`` -value should be a string containing a brief description of what the argument -specifies. When a user requests help (usually by using ``-h`` or ``--help`` at -the command-line), these ``help`` descriptions will be displayed with each +The ``help`` value is a string containing a brief description of the argument. +When a user requests help (usually by using ``-h`` or ``--help`` at the +command-line), these ``help`` descriptions will be displayed with each argument:: >>> parser = argparse.ArgumentParser(prog='frobble') @@ -1024,15 +1010,14 @@ specifiers include the program name, ``%(prog)s`` and most keyword arguments to metavar ^^^^^^^ -When ArgumentParser objects generate help messages, they need some way to refer +When :class:`ArgumentParser` generates help messages, it need some way to refer to each expected argument. By default, ArgumentParser objects use the dest_ 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 if we have a single positional argument with -``dest='bar'``, that argument will be referred to as ``bar``. And if we have a -single optional argument ``--foo`` that should be followed by a single -command-line arg, that arg will be referred to as ``FOO``. You can see this -behavior in the example below:: +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 +will be referred to as ``FOO``. An example:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo') @@ -1049,9 +1034,7 @@ behavior in the example below:: -h, --help show this help message and exit --foo FOO -If you would like to provide a different name for your argument in help -messages, you can supply a value for the ``metavar`` keyword argument to -:meth:`add_argument`:: +An alternative name can be specified with ``metavar``:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', metavar='YYY') @@ -1073,8 +1056,8 @@ attribute on the :meth:`parse_args` object is still determined by the dest_ value. Different values of ``nargs`` may cause the metavar to be used multiple times. -If you'd like to specify a different display name for each of the arguments, you -can provide a tuple to ``metavar``:: +Providing a tuple to ``metavar`` specifies a different display for each of the +arguments:: >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('-x', nargs=2) @@ -1091,10 +1074,10 @@ can provide a tuple to ``metavar``:: dest ^^^^ -Most ArgumentParser actions add some value as an attribute of the object -returned by :meth:`parse_args`. The name of this attribute is determined by the -``dest`` keyword argument of :meth:`add_argument`. For positional argument -actions, ``dest`` is normally supplied as the first argument to +Most :class:`ArgumentParser` actions add some value as an attribute of the +object returned by :meth:`parse_args`. The name of this attribute is determined +by the ``dest`` keyword argument of :meth:`add_argument`. For positional +argument actions, ``dest`` is normally supplied as the first argument to :meth:`add_argument`:: >>> parser = argparse.ArgumentParser() @@ -1103,7 +1086,7 @@ actions, ``dest`` is normally supplied as the first argument to Namespace(bar='XXX') For optional argument actions, the value of ``dest`` is normally inferred from -the option strings. ArgumentParser objects generate the value of ``dest`` by +the option strings. :class:`ArgumentParser` generates the value of ``dest`` by 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 @@ -1119,9 +1102,7 @@ behavior:: >>> parser.parse_args('--foo 1 -y 2'.split()) Namespace(foo_bar='1', x='2') -If you would like to use a different attribute name from the one automatically -inferred by the ArgumentParser, you can supply it with an explicit ``dest`` -parameter:: +``dest`` allows a custom attribute name to be provided:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', dest='bar') @@ -1132,9 +1113,9 @@ parameter:: The parse_args() method ----------------------- -.. method:: parse_args([args], [namespace]) +.. method:: ArgumentParser.parse_args([args], [namespace]) - Convert the strings to objects and assign them as attributes of the + Convert argument strings to objects and assign them as attributes of the namespace. Return the populated namespace. Previous calls to :meth:`add_argument` determine exactly what objects are @@ -1142,7 +1123,7 @@ The parse_args() method :meth:`add_argument` for details. By default, the arg strings are taken from :data:`sys.argv`, and a new empty - ``Namespace`` object is created for the attributes. + :class:`Namespace` object is created for the attributes. Option value syntax ^^^^^^^^^^^^^^^^^^^ @@ -1159,21 +1140,21 @@ passed as two separate arguments:: >>> parser.parse_args('--foo FOO'.split()) Namespace(foo='FOO', x=None) -For long options (options with names longer than a single character), you may -also pass the option and value as a single command line argument, using ``=`` to +For long options (options with names longer than a single character), the option +and value can also be passed as a single command line argument, using ``=`` to separate them:: >>> parser.parse_args('--foo=FOO'.split()) Namespace(foo='FOO', x=None) -For short options (options only one character long), you may simply concatenate -the option and its value:: +For short options (options only one character long), the option and its value +can be concatenated:: >>> parser.parse_args('-xX'.split()) Namespace(foo=None, x='X') -You can also combine several short options together, using only a single ``-`` -prefix, as long as only the last option (or none of them) requires a value:: +Several short options can be joined together, using only a single ``-`` prefix, +as long as only the last option (or none of them) requires a value:: >>> parser = argparse.ArgumentParser(prog='PROG') >>> parser.add_argument('-x', action='store_true') @@ -1263,7 +1244,7 @@ like negative numbers, you can insert the pseudo-argument ``'--'`` which tells Argument abbreviations ^^^^^^^^^^^^^^^^^^^^^^ -The :meth:`parse_args` method allows you to abbreviate long options if the +The :meth:`parse_args` method allows long options to be abbreviated if the abbreviation is unambiguous:: >>> parser = argparse.ArgumentParser(prog='PROG') @@ -1277,8 +1258,7 @@ abbreviation is unambiguous:: usage: PROG [-h] [-bacon BACON] [-badger BADGER] PROG: error: ambiguous option: -ba could match -badger, -bacon -As you can see above, you will get an error if you pick a prefix that could -refer to more than one option. +An error is produced for arguments that could produce more than one options. Beyond ``sys.argv`` @@ -1286,9 +1266,7 @@ Beyond ``sys.argv`` Sometimes it may be useful to have an ArgumentParser parse args other than those of :data:`sys.argv`. This can be accomplished by passing a list of strings to -``parse_args``. You may have noticed that the examples in the argparse -documentation have made heavy use of this calling style - it is much easier to -use at the interactive prompt:: +``parse_args``. This is useful for testing at the interactive prompt:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument( @@ -1306,9 +1284,10 @@ use at the interactive prompt:: Custom namespaces ^^^^^^^^^^^^^^^^^ -It may also be useful to have an ArgumentParser assign attributes to an already -existing object, rather than the newly-created Namespace object that is normally -used. This can be achieved by specifying the ``namespace=`` keyword argument:: +It may also be useful to have an :class:`ArgumentParser` assign attributes to an +already existing object, rather than the newly-created :class:`Namespace` object +that is normally used. This can be achieved by specifying the ``namespace=`` +keyword argument:: >>> class C(object): ... pass @@ -1327,19 +1306,19 @@ Other utilities Sub-commands ^^^^^^^^^^^^ -.. method:: add_subparsers() +.. method:: ArgumentParser.add_subparsers() - A lot of programs split up their functionality into a number of sub-commands, + Many programs split up their functionality into a number of sub-commands, for example, the ``svn`` program can invoke sub-commands like ``svn - checkout``, ``svn update``, ``svn commit``, etc. Splitting up functionality + checkout``, ``svn update``, and ``svn commit``. Splitting up functionality this way can be a particularly good idea when a program performs several different functions which require different kinds of command-line arguments. - ArgumentParser objects support the creation of such sub-commands with the + :class:`ArgumentParser` supports the creation of such sub-commands with the :meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally called with no arguments and returns an special action object. This object has a single method, ``add_parser``, which takes a command name and any - ArgumentParser constructor arguments, and returns an ArgumentParser object - that can be modified as usual. + :class:`ArgumentParser` constructor arguments, and returns an + :class:`ArgumentParser` object that can be modified as usual. Some example usage:: @@ -1371,9 +1350,9 @@ Sub-commands Similarly, when a help message is requested from a subparser, only the help for that particular parser will be printed. The help message will not - include parent parser or sibling parser messages. (You can however supply a - help message for each subparser command by suppling the ``help=`` argument to - ``add_parser`` as above.) + include parent parser or sibling parser messages. (A help message for each + subparser command, however, can be given by supplying the ``help=`` argument + to ``add_parser`` as above.) :: @@ -1464,13 +1443,12 @@ Sub-commands >>> args.func(args) ((XYZYX)) - This way, you can let :meth:`parse_args` do all the work for you, and then - just call the appropriate function after the argument parsing is complete. - Associating functions with actions like this is typically the easiest way to - handle the different actions for each of your subparsers. However, if you - find it necessary to check the name of the subparser that was invoked, you - can always provide a ``dest`` keyword argument to the :meth:`add_subparsers` - call:: + This way, you can let :meth:`parse_args` does the job of calling the + appropriate function after argument parsing is complete. Associating + functions with actions like this is typically the easiest way to handle the + different actions for each of your subparsers. However, if it is necessary + to check the name of the subparser that was invoked, the ``dest`` keyword + argument to the :meth:`add_subparsers` call will work:: >>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(dest='subparser_name') @@ -1488,9 +1466,9 @@ FileType objects .. class:: FileType(mode='r', bufsize=None) The :class:`FileType` factory creates objects that can be passed to the type - argument of :meth:`add_argument`. Arguments that have :class:`FileType` - objects as their type will open command-line args as files with the requested - modes and buffer sizes: + argument of :meth:`ArgumentParser.add_argument`. Arguments that have + :class:`FileType` objects as their type will open command-line args as files + with the requested modes and buffer sizes: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--output', type=argparse.FileType('wb', 0)) @@ -1510,9 +1488,9 @@ FileType objects Argument groups ^^^^^^^^^^^^^^^ -.. method:: add_argument_group([title], [description]) +.. method:: ArgumentParser.add_argument_group([title], [description]) - By default, ArgumentParser objects group command-line arguments into + By default, :class:`ArgumentParser` groups command-line arguments into "positional arguments" and "optional arguments" when displaying help messages. When there is a better conceptual grouping of arguments than this default one, appropriate groups can be created using the @@ -1530,11 +1508,12 @@ Argument groups --foo FOO foo help The :meth:`add_argument_group` method returns an argument group object which - has an :meth:`add_argument` method just like a regular ArgumentParser - objects. When an argument is added to the group, the parser treats it just - like a normal argument, but displays the argument in a separate group for - help messages. The :meth:`add_argument_group` method accepts ``title`` and - ``description`` arguments which can be used to customize this display:: + has an :meth:`~ArgumentParser.add_argument` method just like a regular + :class:`ArgumentParser`. When an argument is added to the group, the parser + treats it just like a normal argument, but displays the argument in a + separate group for help messages. The :meth:`add_argument_group` method + accepts ``title`` and ``description`` arguments which can be used to + customize this display:: >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False) >>> group1 = parser.add_argument_group('group1', 'group1 description') @@ -1554,8 +1533,8 @@ Argument groups --bar BAR bar help - Note that any arguments not in your user defined groups will end up back in - the usual "positional arguments" and "optional arguments" sections. + Note that any arguments not your user defined groups will end up back in the + usual "positional arguments" and "optional arguments" sections. Mutual exclusion @@ -1563,10 +1542,7 @@ Mutual exclusion .. method:: add_mutually_exclusive_group([required=False]) - Sometimes, you need to make sure that only one of a couple different options - is specified on the command line. You can create groups of such mutually - exclusive arguments using the :meth:`add_mutually_exclusive_group` method. - When :func:`parse_args` is called, argparse will make sure that only one of + Create a mutually exclusive group. argparse will make sure that only one of the arguments in the mutually exclusive group was present on the command line:: @@ -1595,22 +1571,19 @@ Mutual exclusion PROG: error: one of the arguments --foo --bar is required Note that currently mutually exclusive argument groups do not support the - ``title`` and ``description`` arguments of :meth:`add_argument_group`. This - may change in the future however, so you are *strongly* recommended to - specify ``required`` as a keyword argument if you use it. + ``title`` and ``description`` arguments of :meth:`add_argument_group`. Parser defaults ^^^^^^^^^^^^^^^ -.. method:: set_defaults(**kwargs) +.. method:: ArgumentParser.set_defaults(**kwargs) Most of the time, the attributes of the object returned by :meth:`parse_args` will be fully determined by inspecting the command-line args and the argument - actions described in your :meth:`add_argument` calls. However, sometimes it - may be useful to add some additional attributes that are determined without - any inspection of the command-line. The :meth:`set_defaults` method allows - you to do this:: + actions. :meth:`ArgumentParser.set_defaults` allows some additional + attributes that are determined without any inspection of the command-line to + be added:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('foo', type=int) @@ -1618,9 +1591,7 @@ Parser defaults >>> parser.parse_args(['736']) Namespace(bar=42, baz='badger', foo=736) - Note that parser-level defaults always override argument-level defaults. So - if you set a parser-level default for a name that matches an argument, the - old argument default will no longer be used:: + Note that parser-level defaults always override argument-level defaults:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='bar') @@ -1628,14 +1599,15 @@ Parser defaults >>> parser.parse_args([]) Namespace(foo='spam') - Parser-level defaults can be particularly useful when you're working with - multiple parsers. See the :meth:`add_subparsers` method for an example of - this type. + Parser-level defaults can be particularly useful when working with multiple + parsers. See the :meth:`~ArgumentParser.add_subparsers` method for an + example of this type. -.. method:: get_default(dest) +.. method:: ArgumentParser.get_default(dest) Get the default value for a namespace attribute, as set by either - :meth:`add_argument` or by :meth:`set_defaults`:: + :meth:`~ArgumentParser.add_argument` or by + :meth:`~ArgumentParser.set_defaults`:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('--foo', default='badger') @@ -1647,16 +1619,16 @@ Printing help ^^^^^^^^^^^^^ In most typical applications, :meth:`parse_args` will take care of formatting -and printing any usage or error messages. However, should you want to format or -print these on your own, several methods are available: +and printing any usage or error messages. However, several formatting methods +are available: -.. method:: print_usage([file]): +.. method:: ArgumentParser.print_usage([file]): Print a brief description of how the :class:`ArgumentParser` should be invoked on the command line. If ``file`` is not present, ``sys.stderr`` is assumed. -.. method:: print_help([file]): +.. method:: ArgumentParser.print_help([file]): Print a help message, including the program usage and information about the arguments registered with the :class:`ArgumentParser`. If ``file`` is not @@ -1665,12 +1637,12 @@ print these on your own, several methods are available: There are also variants of these methods that simply return a string instead of printing it: -.. method:: format_usage(): +.. method:: ArgumentParser.format_usage(): Return a string containing a brief description of how the :class:`ArgumentParser` should be invoked on the command line. -.. method:: format_help(): +.. method:: ArgumentParser.format_help(): Return a string containing a help message, including the program usage and information about the arguments registered with the :class:`ArgumentParser`. @@ -1680,14 +1652,14 @@ printing it: Partial parsing ^^^^^^^^^^^^^^^ -.. method:: parse_known_args([args], [namespace]) +.. method:: ArgumentParser.parse_known_args([args], [namespace]) Sometimes a script may only parse a few of the command line arguments, passing the remaining arguments on to another script or program. In these cases, the :meth:`parse_known_args` method can be useful. It works much like -:meth:`parse_args` except that it does not produce an error when extra arguments -are present. Instead, it returns a two item tuple containing the populated -namespace and the list of remaining argument strings. +:meth:`~ArgumentParser.parse_args` except that it does not produce an error when +extra arguments are present. Instead, it returns a two item tuple containing +the populated namespace and the list of remaining argument strings. :: @@ -1701,13 +1673,12 @@ namespace and the list of remaining argument strings. Customizing file parsing ^^^^^^^^^^^^^^^^^^^^^^^^ -.. method:: convert_arg_line_to_args(arg_line) +.. method:: ArgumentParser.convert_arg_line_to_args(arg_line) Arguments that are read from a file (see the ``fromfile_prefix_chars`` keyword argument to the :class:`ArgumentParser` constructor) are read one - argument per line. If you need fancier parsing, then you can subclass the - :class:`ArgumentParser` and override the :meth:`convert_arg_line_to_args` - method. + argument per line. :meth:`convert_arg_line_to_args` can be overriden for + fancier reading. This method takes a single argument ``arg_line`` which is a string read from the argument file. It returns a list of arguments parsed from this string. @@ -1735,10 +1706,10 @@ backwards compatibility. A partial upgrade path from optparse to argparse: -* Replace all ``add_option()`` calls with :meth:`add_argument` calls. +* Replace all ``add_option()`` calls with :meth:`ArgumentParser.add_argument` calls. * Replace ``options, args = parser.parse_args()`` with ``args = - parser.parse_args()`` and add additional :meth:`add_argument` calls for the + parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument` calls for the positional arguments. * Replace callback actions and the ``callback_*`` keyword arguments with @@ -1747,8 +1718,9 @@ A partial upgrade path from optparse to argparse: * Replace string names for ``type`` keyword arguments with the corresponding type objects (e.g. int, float, complex, etc). -* Replace ``Values`` with ``Namespace`` and ``OptionError/OptionValueError`` - with ``ArgumentError``. +* Replace :class:`optparse.Values` with :class:`Namespace` and + :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with + :exc:`ArgumentError`. * Replace strings with implicit arguments such as ``%default`` or ``%prog`` with the standard python syntax to use dictionaries to format strings, that is, |