[Python-checkins] cpython (3.2): Issue #16933 (2.7 forward-port): Improve choices examples in argparse docs.

Sat Jan 12 04:31:14 CET 2013

http://hg.python.org/cpython/rev/eaa2a6074741
changeset: 81435:eaa2a6074741
branch: 3.2
parent: 81424:a9990104f728
user: Chris Jerdonek <chris.jerdonek at gmail.com>
date: Fri Jan 11 19:26:44 2013 -0800
summary:
 Issue #16933 (2.7 forward-port): 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
@@ -1003,32 +1003,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
