classification
Title: Add argparse howto
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: bethard, docs@python, eric.araujo, ezio.melotti, georg.brandl, ncoghlan, python-dev, tshepang
Priority: normal Keywords: patch

Created on 2012-02-16 18:34 by tshepang, last changed 2012-05-07 08:03 by tshepang. This issue is now closed.

Files
File name Uploaded Description Edit
argparse_howto.patch tshepang, 2012-02-20 08:18 review
argparse_howto2.patch tshepang, 2012-03-19 11:11 review
argparse_howto3.patch tshepang, 2012-03-19 14:48 review
argparse_howto4.patch tshepang, 2012-04-29 17:40 review
argparse_howto5.patch tshepang, 2012-04-30 07:48 review
Messages (31)
msg153491 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-02-16 18:34
The argparse example (http://docs.python.org/dev/library/argparse.html#example) introduces way too many concepts too early. It's written as if targeted to existing users of optparse, instead of newcomers to Python's CLI handling.

Perhaps the example could be more gentle, or if there is insistence on showing off, maybe the page could be kept as-is, but with a link to some tutorial (as is done with logging: http://docs.python.org/dev/library/logging.html).
msg153570 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-17 17:03
I really don’t think there was any willingness to “show off”, and wouldn’t be surprised if the doc was written optparse users.  It’s just an accident of history, and we can try to make it better instead of calling people names :)

Do you have a wording idea for a gentler introduction?
msg153580 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-02-17 17:36
On Fri, Feb 17, 2012 at 19:03, Éric Araujo <report@bugs.python.org> wrote:
>
> Éric Araujo <merwok@netwok.org> added the comment:
>
> I really don’t think there was any willingness to “show off”, and wouldn’t be surprised if the doc was written optparse users.  It’s just an accident of history, and we can try to make it better instead of calling people names :)

I did not mean to sound rude. Forgive me.

> Do you have a wording idea for a gentler introduction?

I will work on something.
msg153730 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-19 22:54
I think I was rude too when I called you off, apologies.  I’ll gladly review or help with a patch.
msg153768 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-02-20 08:18
I chose to go the way of a howto. I find argparse complex enough to deserve one.

note: I have checked each example on the 3 releases that possess the module (2.7, 3.2, and 3.3), and the differences in output are very small.
msg153821 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-21 00:01
Nice.  I’ll find time to review later; Steven, do you have objections on the idea of adding an argparse howto?  Do you want to review it yourself?
msg153866 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2012-02-21 10:35
I have no objections on adding a howto, and something like the attached patch would be fine with me (though I don't have time to review it in full and trust you to).

You might want to coordinate with Issue 13850 a bit - they want a quick reference table before the first example (which would therefore mean before this howto which is replacing the first example).
msg153952 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-22 12:41
> You might want to coordinate with Issue 13850 a bit - they want a quick reference table before
> the first example (which would therefore mean before this howto which is replacing the first example).

The howto discussed here would be a new file in Doc/howto, so no conflict.
msg153967 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2012-02-22 16:22
Oh ok. Sounds good then!
msg156277 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-18 22:06
friendly ping
msg156278 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-18 22:07
I’m going to Rietveld to review the patch.
msg156310 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-19 03:30
Sorry, a burger party fell on me.  I’ll make time this week.

Nick, I just read on python-dev that you had suggestions for argparse docs; could you post the bug numbers / message IDs here or the list of suggestions?
msg156311 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-03-19 03:57
13850 (already mentioned above) is my relevant argparse docs proposal - it turns out the other argparse issues I remembered posting were actual feature requests rather than docs suggestions (FWIW, those are 14037 and 14039)
msg156313 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-03-19 04:17
A couple of thoughts on the draft HOWTO:

I like the "verbosity" example, but I'd also like to see it continue on into introducing the "action='count'" alternative that allows "-vv" to set the verbosity level to 2, etc.

I also find the idea of having higher verbosity levels that aren't supersets of lower verbosity levels to be an anti-pattern, so I'd prefer not to see it in an official HOWTO. To my mind, verbosity levels should be checked with ">=", never "==".
msg156321 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-19 08:34
> Nick Coghlan <ncoghlan@gmail.com> added the comment:
>
> A couple of thoughts on the draft HOWTO:
>
> I like the "verbosity" example, but I'd also like to see it continue on into introducing the "action='count'" alternative that allows "-vv" to set the verbosity level to 2, etc.

I wonder if this usage is common enough to get an entry in this
introductory text.

> I also find the idea of having higher verbosity levels that aren't supersets of lower verbosity levels to be an anti-pattern, so I'd prefer not to see it in an official HOWTO. To my mind, verbosity levels should be checked with ">=", never "==".

I don't really understand this paragraph. Do you have an example to
compare with any of the examples in the attached patch?
msg156323 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-19 08:49
On Mon, Mar 19, 2012 at 10:34, Tshepang Lekhonkhobe <tshepang@gmail.com> wrote:
>> Nick Coghlan <ncoghlan@gmail.com> added the comment:
>>
>> A couple of thoughts on the draft HOWTO:
>>
>> I like the "verbosity" example, but I'd also like to see it continue on into introducing the "action='count'" alternative that allows "-vv" to set the verbosity level to 2, etc.
>
> I wonder if this usage is common enough to get an entry in this
> introductory text.
>
>> I also find the idea of having higher verbosity levels that aren't supersets of lower verbosity levels to be an anti-pattern, so I'd prefer not to see it in an official HOWTO. To my mind, verbosity levels should be checked with ">=", never "==".
>
> I don't really understand this paragraph. Do you have an example to
> compare with any of the examples in the attached patch?

After playing a bit more with this and thinking about it a bit, I do
get your point. It makes a lot of sense. I will attach a patch soon,
which will also include the count keyword. Thanks for the review.
msg156325 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-19 10:50
> After playing a bit more with this and thinking about it a bit, I do
> get your point. It makes a lot of sense. I will attach a patch soon,
> which will also include the count keyword. Thanks for the review.

Find attached. Note that I kept some of those anti-pattern examples
you mentioned, and then later on introduced your preferred way of
doing things (using action="count" and ">=" checks instead of "=="
ones).
msg156326 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-19 11:02
> Find attached. Note that I kept some of those anti-pattern examples
> you mentioned, and then later on introduced your preferred way of
> doing things (using action="count" and ">=" checks instead of "=="
> ones).

Reason I kept those is to easily lead the reader into the "more
correct" way of doing things, by first doing them in a more obvious
but less ideal way.

For example, when the goal of one is to teach one to remove duplicates
from list, it's nice if you first do the process manually, and then
later on introduce the set() type, just so the user can appreciate
them more. Same applies to doing "for item in range(len(iterable))"
vs. "for item in iterable".
msg156327 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-19 11:11
Okay, there was some bad markup on my version 2. Lemme fix.
msg156338 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-03-19 13:05
Rather than "is recommended by at least one core CPython developer" I'd say "matches the way the CPython executable handles its own verbosity argument" (check the output of "python --help")

Also, a better fix for the non-orderable types problem is to use "default=0" when defining the verbosity arg rather than changing the test in the code.

Finally, the "not a superset" problem that I have with the way the running example uses its verbosity argument is that it uses it to *change* the message that gets displayed, instead of using it to *display more messages* at higher verbosity levels.

From that point of view, more idiomatic usage might look something like:

    if verbosity >= 2:
        print("Running {!r}".format(self.__file__)
    if verbosity >= 1:
        print("Calculating {}^2".format(args.square)
    print(answer)

However, I'll grant that things like test runners do use their verbosity argument to switch from shorthand progress markers to printing out the test names and results, so I can live with the examples as they are.
msg156344 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-19 14:42
> Nick Coghlan <ncoghlan@gmail.com> added the comment:
>
> Rather than "is recommended by at least one core CPython developer" I'd say "matches the way the CPython executable handles its own verbosity argument" (check the output of "python --help")

Done.

> Also, a better fix for the non-orderable types problem is to use "default=0" when defining the verbosity arg rather than changing the test in the code.

Done.

> Finally, the "not a superset" problem that I have with the way the running example uses its verbosity argument is that it uses it to *change* the message that gets displayed, instead of using it to *display more messages* at higher verbosity levels.
>
> >From that point of view, more idiomatic usage might look something like:
>
>    if verbosity >= 2:
>        print("Running {!r}".format(self.__file__)
>    if verbosity >= 1:
>        print("Calculating {}^2".format(args.square)
>    print(answer)

Yeah, I clearly didn't understand what you meant by 'superset'. I've
added one example similar to the above.

These were good suggestions. I've attached the patch.
msg156345 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-19 14:48
Fixing a markup error. Sorry for the noise.
msg157174 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-03-31 11:43
Would be nice to get another review.
msg159568 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-04-29 03:58
> Would be nice to get another review.

I left several comments on rietveld.

Overall the tutorial seems really nice and easy to follow (except a couple of parts, noted in the comments).

I would replace all the uses of pow(x, y) with x**y in the code, and possibly with x^y in the output/descriptions (x**y is probably fine there too).
msg159570 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-04-29 04:21
A few more comments:

* in the review I mentioned highlighting specific code lines (this would be really great given the incremental nature of the howto), but apparently that requires a pygment 1.1 [0].

* all the output examples could use ".. highlightlang:: sh", but:
  1. the sh highlighter is not so good imho;
  2. you would have to switch back and forth from sh and python (unless there's a better way to do it);

* the sidebar box with the tutorial looks better if you put it between the <hr> and the introductory paragraph.

Maybe Georg has something to say about the first two comments.

[0]: see last example in http://sphinx.pocoo.org/markup/code.html#line-numbers
msg159633 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-04-29 17:40
addressing the bulk of your comments

this does not address last message, where you want the lines highlighted; it will be rather tedious; to me the code snippets are short enough, removing the need for highlighting
msg159672 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-04-30 07:48
Thanks so much for your thorough attention to detail. I've addressed all your latest comments.
msg160083 - (view) Author: Roundup Robot (python-dev) Date: 2012-05-06 13:55
New changeset 48385618525b by Ezio Melotti in branch '2.7':
#14034: added the argparse tutorial.  Patch by Tshepang Lekhonkhobe.
http://hg.python.org/cpython/rev/48385618525b

New changeset 11703cb2a2f3 by Ezio Melotti in branch '3.2':
#14034: added the argparse tutorial.  Patch by Tshepang Lekhonkhobe.
http://hg.python.org/cpython/rev/11703cb2a2f3

New changeset 645969f4193b by Ezio Melotti in branch 'default':
#14034: merge argparse tutorial from 3.2.
http://hg.python.org/cpython/rev/645969f4193b
msg160084 - (view) Author: Roundup Robot (python-dev) Date: 2012-05-06 14:06
New changeset 549aa1460811 by Ezio Melotti in branch '2.7':
#14034: adapt to Python 2 and fix indentation.
http://hg.python.org/cpython/rev/549aa1460811

New changeset d5b7be0629c0 by Ezio Melotti in branch '3.2':
#14034: fix indentation.
http://hg.python.org/cpython/rev/d5b7be0629c0

New changeset e14c860f6eee by Ezio Melotti in branch 'default':
#14034: merge indentation fixes from 3.2.
http://hg.python.org/cpython/rev/e14c860f6eee
msg160085 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-05-06 14:10
Committed, thanks for the patch!

(Note that the example with "TypeError: unorderable types: NoneType() >= int()" works fine in Python 2 (by accident), and that I left it unchanged.  Some error messages are also different on Python 2, but I left the ones from Python 3.)
msg160121 - (view) Author: Tshepang Lekhonkhobe (tshepang) * Date: 2012-05-07 08:03
thanks so much for your rime in reviewing and committing
History
Date User Action Args
2012-05-07 08:03:13tshepangsetmessages: + msg160121
2012-05-06 14:10:35ezio.melottisetstatus: open -> closed
messages: + msg160085

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: needs patch -> resolved
2012-05-06 14:06:00python-devsetmessages: + msg160084
2012-05-06 13:55:26python-devsetnosy: + python-dev
messages: + msg160083
2012-04-30 07:48:13tshepangsetfiles: + argparse_howto5.patch

messages: + msg159672
2012-04-29 17:40:33tshepangsetfiles: + argparse_howto4.patch

messages: + msg159633
2012-04-29 04:21:32ezio.melottisetnosy: + georg.brandl
messages: + msg159570
2012-04-29 03:58:18ezio.melottisetmessages: + msg159568
2012-03-31 11:43:23tshepangsetmessages: + msg157174
2012-03-19 14:49:07tshepangsetfiles: - argparse_howto3.patch
2012-03-19 14:48:33tshepangsetfiles: + argparse_howto3.patch

messages: + msg156345
2012-03-19 14:42:00tshepangsetfiles: + argparse_howto3.patch

messages: + msg156344
2012-03-19 13:05:43ncoghlansetmessages: + msg156338
2012-03-19 12:20:54tshepangsetfiles: - argparse_howto2.patch
2012-03-19 11:11:02tshepangsetfiles: + argparse_howto2.patch

messages: + msg156327
2012-03-19 11:02:10tshepangsetmessages: + msg156326
2012-03-19 10:50:58tshepangsetfiles: + argparse_howto2.patch

messages: + msg156325
2012-03-19 08:49:02tshepangsetmessages: + msg156323
2012-03-19 08:34:42tshepangsetmessages: + msg156321
2012-03-19 04:17:42ncoghlansetmessages: + msg156313
2012-03-19 03:57:34ncoghlansetmessages: + msg156311
2012-03-19 03:30:47eric.araujosetnosy: + ncoghlan
messages: + msg156310
2012-03-18 22:07:47eric.araujosetmessages: + msg156278
2012-03-18 22:06:35tshepangsetmessages: + msg156277
2012-02-22 16:22:04bethardsetmessages: + msg153967
2012-02-22 12:41:04eric.araujosetmessages: + msg153952
2012-02-21 10:35:03bethardsetmessages: + msg153866
2012-02-21 00:01:42eric.araujosetnosy: + bethard

messages: + msg153821
title: first example in argparse doc is too complicated -> Add argparse howto
2012-02-20 08:18:41tshepangsetfiles: + argparse_howto.patch
keywords: + patch
messages: + msg153768
2012-02-19 22:54:12eric.araujosetmessages: + msg153730
title: the example in argparse doc is too complex -> first example in argparse doc is too complicated
2012-02-18 10:44:35ezio.melottisetnosy: + ezio.melotti

stage: needs patch
2012-02-17 17:36:04tshepangsetmessages: + msg153580
2012-02-17 17:03:56eric.araujosetnosy: + eric.araujo
messages: + msg153570
2012-02-16 18:34:21tshepangcreate