classification
Title: argparse: remove magic from examples
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ramchandra Apte, bethard, chris.jerdonek, docs@python, guettli, paul.j3, python-dev, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2013-01-11 13:44 by guettli, last changed 2013-07-03 19:40 by paul.j3. This issue is now closed.

Files
File name Uploaded Description Edit
issue-16933-1.patch chris.jerdonek, 2013-01-11 20:33 review
Messages (8)
msg179679 - (view) Author: Thomas Guettler (guettli) Date: 2013-01-11 13:44
The current argparse documentation is not easy to read people new to python.

http://docs.python.org/dev/library/argparse.html#choices

{{{
current: parser.add_argument('foo', choices='abc')
}}}

Please make this more explicit:
{{{
better: parser.add_argument('foo', choices=['one', 'two', 'three'])
}}}

{{{
current: parser.parse_args('c'.split()) # looks like perl to me
}}}

{{{
better: parser.parse_args(['c'])
}}}

Next: Please use a more common type, not "complex" in the choices example. It confuses a lot of people.
msg179703 - (view) Author: Ramchandra Apte (Ramchandra Apte) * Date: 2013-01-11 16:59
+1
msg179717 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-01-11 18:18
+1.  By the way, I included a couple fixes similar to these in a patch posted to issue 16878.
msg179727 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-01-11 20:33
Patch attached.
msg179760 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-01-12 03:10
The new examples are much better and to me the patch looks ready to apply.
msg179761 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-01-12 03:31
New changeset b2bb3219d36d by Chris Jerdonek in branch '2.7':
Issue #16933: Improve choices examples in argparse documentation.
http://hg.python.org/cpython/rev/b2bb3219d36d

New changeset eaa2a6074741 by Chris Jerdonek in branch '3.2':
Issue #16933 (2.7 forward-port): Improve choices examples in argparse docs.
http://hg.python.org/cpython/rev/eaa2a6074741

New changeset de9eb3031f5a by Chris Jerdonek in branch '3.3':
Issue #16933 (merge from 3.2): Improve choices examples in argparse docs.
http://hg.python.org/cpython/rev/de9eb3031f5a

New changeset bddbaaf332d7 by Chris Jerdonek in branch 'default':
Issue #16933 (merge from 3.3): Improve choices examples in argparse docs.
http://hg.python.org/cpython/rev/bddbaaf332d7
msg179763 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-01-12 03:33
Thanks for reporting the suggestion, Thomas.  And thanks for looking over the patch, Terry.
msg192252 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2013-07-03 19:40
There still is one "choices='XYZ'" example (16.4.5.1. Sub-commands) but the focus isn't on choices.
History
Date User Action Args
2013-07-03 19:40:33paul.j3setnosy: + paul.j3
messages: + msg192252
2013-01-12 03:33:15chris.jerdoneksetstatus: open -> closed
resolution: fixed
messages: + msg179763

stage: commit review -> resolved
2013-01-12 03:31:12python-devsetnosy: + python-dev
messages: + msg179761
2013-01-12 03:10:18terry.reedysetnosy: + terry.reedy

messages: + msg179760
stage: patch review -> commit review
2013-01-11 20:33:33chris.jerdoneksetfiles: + issue-16933-1.patch

assignee: docs@python
components: + Documentation

keywords: + easy, patch
nosy: + docs@python
messages: + msg179727
stage: needs patch -> patch review
2013-01-11 18:20:32chris.jerdoneksetstage: needs patch
versions: + Python 2.7, Python 3.2, Python 3.3, Python 3.4
2013-01-11 18:18:58chris.jerdoneksetnosy: + chris.jerdonek, bethard
messages: + msg179717
2013-01-11 16:59:02Ramchandra Aptesetnosy: + Ramchandra Apte
messages: + msg179703
2013-01-11 13:44:18guettlicreate