[Python-checkins] cpython (merge 3.2 -> 3.3): Issue #16933 (merge from 3.2): Improve choices examples in argparse docs.
chris.jerdonek
python-checkins at python.org
Sat Jan 12 04:31:16 CET 2013
http://hg.python.org/cpython/rev/de9eb3031f5a
changeset: 81436:de9eb3031f5a
branch: 3.3
parent: 81430:9c695fddd10a
parent: 81435:eaa2a6074741
user: Chris Jerdonek <chris.jerdonek at gmail.com>
date: Fri Jan 11 19:28:05 2013 -0800
summary:
Issue #16933 (merge from 3.2): Improve choices examples in argparse docs.
files:
Doc/library/argparse.rst | 41 ++++++++++++++-------------
1 files changed, 21 insertions(+), 20 deletions(-)
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1022,32 +1022,33 @@
^^^^^^^
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::
+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')
+ >>> 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``
+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)
+ >>> 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``
+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.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list