diff options
| -rw-r--r-- | Doc/library/argparse.rst | 47 |
1 files changed, 24 insertions, 23 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index b8d14dd..16051ea 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1003,32 +1003,33 @@ choices ^^^^^^^ Some command-line arguments should be selected from a restricted set of values. -These can be handled by passing a container object as the ``choices`` keyword +These can be handled by passing a container object as the *choices* keyword argument to :meth:`~ArgumentParser.add_argument`. When the command line is -parsed, argument values will be checked, and an error message will be displayed if -the argument was not one of the acceptable values:: - - >>> parser = argparse.ArgumentParser(prog='PROG') - >>> parser.add_argument('foo', choices='abc') - >>> parser.parse_args('c'.split()) - Namespace(foo='c') - >>> parser.parse_args('X'.split()) - usage: PROG [-h] {a,b,c} - PROG: error: argument foo: invalid choice: 'X' (choose from 'a', 'b', 'c') - -Note that inclusion in the ``choices`` container is checked after any type_ -conversions have been performed, so the type of the objects in the ``choices`` +parsed, argument values will be checked, and an error message will be displayed +if the argument was not one of the acceptable values:: + + >>> parser = argparse.ArgumentParser(prog='game.py') + >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors']) + >>> parser.parse_args(['rock']) + Namespace(move='rock') + >>> parser.parse_args(['fire']) + usage: game.py [-h] {rock,paper,scissors} + game.py: error: argument move: invalid choice: 'fire' (choose from 'rock', + 'paper', 'scissors') + +Note that inclusion in the *choices* container is checked after any type_ +conversions have been performed, so the type of the objects in the *choices* container should match the type_ specified:: - >>> parser = argparse.ArgumentParser(prog='PROG') - >>> parser.add_argument('foo', type=complex, choices=[1, 1j]) - >>> parser.parse_args('1j'.split()) - Namespace(foo=1j) - >>> parser.parse_args('-- -4'.split()) - usage: PROG [-h] {1,1j} - PROG: error: argument foo: invalid choice: (-4+0j) (choose from 1, 1j) - -Any object that supports the ``in`` operator can be passed as the ``choices`` + >>> parser = argparse.ArgumentParser(prog='doors.py') + >>> parser.add_argument('door', type=int, choices=range(1, 4)) + >>> print(parser.parse_args(['3'])) + Namespace(door=3) + >>> parser.parse_args(['4']) + usage: doors.py [-h] {1,2,3} + doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3) + +Any object that supports the ``in`` operator can be passed as the *choices* value, so :class:`dict` objects, :class:`set` objects, custom containers, etc. are all supported. |