summaryrefslogtreecommitdiffstats
path: root/Doc/library/argparse.rst
diff options
context:
space:
mode:
authorChris Jerdonek <chris.jerdonek@gmail.com>2013-01-12 03:28:05 (GMT)
committerChris Jerdonek <chris.jerdonek@gmail.com>2013-01-12 03:28:05 (GMT)
commit71e39fb48469c70078678cfade3196b86dec5664 (patch)
treebfbda5d616d77345a6ea7baf105e3cb62be8daae /Doc/library/argparse.rst
parented6b4c0020279c31b2c46107aac63b7a9170b907 (diff)
parent174ef67b56a8618c62852c7087ad365765f59a96 (diff)
downloadcpython-71e39fb48469c70078678cfade3196b86dec5664.zip
cpython-71e39fb48469c70078678cfade3196b86dec5664.tar.gz
cpython-71e39fb48469c70078678cfade3196b86dec5664.tar.bz2
Issue #16933 (merge from 3.2): Improve choices examples in argparse docs.
Diffstat (limited to 'Doc/library/argparse.rst')
-rw-r--r--Doc/library/argparse.rst47
1 files changed, 24 insertions, 23 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 6390264..5b725c4 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1022,32 +1022,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.