diff options
Diffstat (limited to 'doc/source/parse_args.rst')
-rw-r--r-- | doc/source/parse_args.rst | 322 |
1 files changed, 161 insertions, 161 deletions
diff --git a/doc/source/parse_args.rst b/doc/source/parse_args.rst index 9ce86f4..4e460be 100644 --- a/doc/source/parse_args.rst +++ b/doc/source/parse_args.rst @@ -1,161 +1,161 @@ -The parse_args() method
-=========================
-
-.. method:: parse_args([args], [namespace])
-
- Convert the 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 created and how they are assigned. See the documentation for :meth:`add_argument` for details.
-
- By default, the arg strings are taken from ``sys.argv``, and a new empty ``Namespace`` object is created for the attributes.
-
-Option value syntax
--------------------
-
-The :meth:`parse_args` method supports several ways of specifying the value of an option (if it takes one). In the simplest case, the option and its value are passed as two separate arguments::
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('-x')
- >>> parser.add_argument('--foo')
- >>> parser.parse_args('-x X'.split())
- Namespace(foo=None, x='X')
- >>> 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 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::
-
- >>> 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::
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('-x', action='store_true')
- >>> parser.add_argument('-y', action='store_true')
- >>> parser.add_argument('-z')
- >>> parser.parse_args('-xyzZ'.split())
- Namespace(x=True, y=True, z='Z')
-
-
-Invalid arguments
------------------
-
-While parsing the command-line, ``parse_args`` checks for a variety of errors, including ambiguous options, invalid types, invalid options, wrong number of positional arguments, etc. When it encounters such an error, it exits and prints the error along with a usage message::
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('--foo', type=int)
- >>> parser.add_argument('bar', nargs='?')
-
- >>> # invalid type
- >>> parser.parse_args(['--foo', 'spam'])
- usage: PROG [-h] [--foo FOO] [bar]
- PROG: error: argument --foo: invalid int value: 'spam'
-
- >>> # invalid option
- >>> parser.parse_args(['--bar'])
- usage: PROG [-h] [--foo FOO] [bar]
- PROG: error: no such option: --bar
-
- >>> # wrong number of arguments
- >>> parser.parse_args(['spam', 'badger'])
- usage: PROG [-h] [--foo FOO] [bar]
- PROG: error: extra arguments found: badger
-
-
-Arguments containing ``"-"``
-----------------------------
-
-The ``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 attempt to specify an option or an attempt to provide a positional argument. The ``parse_args`` method is cautious here: positional 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')
- >>> parser.add_argument('-x')
- >>> parser.add_argument('foo', nargs='?')
-
- >>> # no negative number options, so -1 is a positional argument
- >>> parser.parse_args(['-x', '-1'])
- Namespace(foo=None, x='-1')
-
- >>> # no negative number options, so -1 and -5 are positional arguments
- >>> parser.parse_args(['-x', '-1', '-5'])
- Namespace(foo='-5', x='-1')
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('-1', dest='one')
- >>> parser.add_argument('foo', nargs='?')
-
- >>> # negative number options present, so -1 is an option
- >>> parser.parse_args(['-1', 'X'])
- Namespace(foo=None, one='X')
-
- >>> # negative number options present, so -2 is an option
- >>> parser.parse_args(['-2'])
- usage: PROG [-h] [-1 ONE] [foo]
- PROG: error: no such option: -2
-
- >>> # negative number options present, so both -1s are options
- >>> parser.parse_args(['-1', '-1'])
- 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 like negative numbers, you can insert the pseudo-argument ``'--'`` which tells ``parse_args`` that everything after that is a positional argument::
-
- >>> parser.parse_args(['--', '-f'])
- Namespace(foo='-f', one=None)
-
-
-Argument abbreviations
-----------------------
-
-The :meth:`parse_args` method allows you to abbreviate long options if the abbreviation is unambiguous::
-
- >>> parser = argparse.ArgumentParser(prog='PROG')
- >>> parser.add_argument('-bacon')
- >>> parser.add_argument('-badger')
- >>> parser.parse_args('-bac MMM'.split())
- Namespace(bacon='MMM', badger=None)
- >>> parser.parse_args('-bad WOOD'.split())
- Namespace(bacon=None, badger='WOOD')
- >>> parser.parse_args('-ba BA'.split())
- 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.
-
-
-Beyond ``sys.argv``
--------------------
-
-Sometimes it may be useful to have an ArgumentParser parse args other than those of ``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::
-
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument(
- ... 'integers', metavar='int', type=int, choices=xrange(10),
- ... nargs='+', help='an integer in the range 0..9')
- >>> parser.add_argument(
- ... '--sum', dest='accumulate', action='store_const', const=sum,
- ... default=max, help='sum the integers (default: find the max)')
- >>> parser.parse_args(['1', '2', '3', '4'])
- Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
- >>> parser.parse_args('1 2 3 4 --sum'.split())
- Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
-
-
-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::
-
- >>> class C(object):
- ... pass
- ...
- >>> c = C()
- >>> parser = argparse.ArgumentParser()
- >>> parser.add_argument('--foo')
- >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
- >>> c.foo
- 'BAR'
+The parse_args() method +========================= + +.. method:: parse_args([args], [namespace]) + + Convert the 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 created and how they are assigned. See the documentation for :meth:`add_argument` for details. + + By default, the arg strings are taken from ``sys.argv``, and a new empty ``Namespace`` object is created for the attributes. + +Option value syntax +------------------- + +The :meth:`parse_args` method supports several ways of specifying the value of an option (if it takes one). In the simplest case, the option and its value are passed as two separate arguments:: + + >>> parser = argparse.ArgumentParser(prog='PROG') + >>> parser.add_argument('-x') + >>> parser.add_argument('--foo') + >>> parser.parse_args('-x X'.split()) + Namespace(foo=None, x='X') + >>> 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 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:: + + >>> 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:: + + >>> parser = argparse.ArgumentParser(prog='PROG') + >>> parser.add_argument('-x', action='store_true') + >>> parser.add_argument('-y', action='store_true') + >>> parser.add_argument('-z') + >>> parser.parse_args('-xyzZ'.split()) + Namespace(x=True, y=True, z='Z') + + +Invalid arguments +----------------- + +While parsing the command-line, ``parse_args`` checks for a variety of errors, including ambiguous options, invalid types, invalid options, wrong number of positional arguments, etc. When it encounters such an error, it exits and prints the error along with a usage message:: + + >>> parser = argparse.ArgumentParser(prog='PROG') + >>> parser.add_argument('--foo', type=int) + >>> parser.add_argument('bar', nargs='?') + + >>> # invalid type + >>> parser.parse_args(['--foo', 'spam']) + usage: PROG [-h] [--foo FOO] [bar] + PROG: error: argument --foo: invalid int value: 'spam' + + >>> # invalid option + >>> parser.parse_args(['--bar']) + usage: PROG [-h] [--foo FOO] [bar] + PROG: error: no such option: --bar + + >>> # wrong number of arguments + >>> parser.parse_args(['spam', 'badger']) + usage: PROG [-h] [--foo FOO] [bar] + PROG: error: extra arguments found: badger + + +Arguments containing ``"-"`` +---------------------------- + +The ``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 attempt to specify an option or an attempt to provide a positional argument. The ``parse_args`` method is cautious here: positional 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') + >>> parser.add_argument('-x') + >>> parser.add_argument('foo', nargs='?') + + >>> # no negative number options, so -1 is a positional argument + >>> parser.parse_args(['-x', '-1']) + Namespace(foo=None, x='-1') + + >>> # no negative number options, so -1 and -5 are positional arguments + >>> parser.parse_args(['-x', '-1', '-5']) + Namespace(foo='-5', x='-1') + + >>> parser = argparse.ArgumentParser(prog='PROG') + >>> parser.add_argument('-1', dest='one') + >>> parser.add_argument('foo', nargs='?') + + >>> # negative number options present, so -1 is an option + >>> parser.parse_args(['-1', 'X']) + Namespace(foo=None, one='X') + + >>> # negative number options present, so -2 is an option + >>> parser.parse_args(['-2']) + usage: PROG [-h] [-1 ONE] [foo] + PROG: error: no such option: -2 + + >>> # negative number options present, so both -1s are options + >>> parser.parse_args(['-1', '-1']) + 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 like negative numbers, you can insert the pseudo-argument ``'--'`` which tells ``parse_args`` that everything after that is a positional argument:: + + >>> parser.parse_args(['--', '-f']) + Namespace(foo='-f', one=None) + + +Argument abbreviations +---------------------- + +The :meth:`parse_args` method allows you to abbreviate long options if the abbreviation is unambiguous:: + + >>> parser = argparse.ArgumentParser(prog='PROG') + >>> parser.add_argument('-bacon') + >>> parser.add_argument('-badger') + >>> parser.parse_args('-bac MMM'.split()) + Namespace(bacon='MMM', badger=None) + >>> parser.parse_args('-bad WOOD'.split()) + Namespace(bacon=None, badger='WOOD') + >>> parser.parse_args('-ba BA'.split()) + 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. + + +Beyond ``sys.argv`` +------------------- + +Sometimes it may be useful to have an ArgumentParser parse args other than those of ``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:: + + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument( + ... 'integers', metavar='int', type=int, choices=xrange(10), + ... nargs='+', help='an integer in the range 0..9') + >>> parser.add_argument( + ... '--sum', dest='accumulate', action='store_const', const=sum, + ... default=max, help='sum the integers (default: find the max)') + >>> parser.parse_args(['1', '2', '3', '4']) + Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4]) + >>> parser.parse_args('1 2 3 4 --sum'.split()) + Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4]) + + +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:: + + >>> class C(object): + ... pass + ... + >>> c = C() + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo') + >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c) + >>> c.foo + 'BAR' |