Issue 14034: Add argparse howto (original) (raw)
Issue14034
Created on 2012-02-16 18:34 by tshepang, last changed 2022-04-11 14:57 by admin. 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) *  |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
Date: 2012-03-18 22:07 |
| I’m going to Rietveld to review the patch. | ||
| msg156310 - (view) | Author: Éric Araujo (eric.araujo) * |
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: Alyssa Coghlan (ncoghlan) * |
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: Alyssa Coghlan (ncoghlan) * |
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: Alyssa Coghlan (ncoghlan) * |
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) * |
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) * |
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 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) * |
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 |
| 2022-04-11 14:57:26 | admin | set | github: 58242 |
| 2012-05-07 08:03:13 | tshepang | set | messages: + |
| 2012-05-06 14:10:35 | ezio.melotti | set | status: open -> closedmessages: + assignee: docs@python -> ezio.melottiresolution: fixedstage: needs patch -> resolved |
| 2012-05-06 14:06:00 | python-dev | set | messages: + |
| 2012-05-06 13:55:26 | python-dev | set | nosy: + python-devmessages: + |
| 2012-04-30 07:48:13 | tshepang | set | files: + argparse_howto5.patchmessages: + |
| 2012-04-29 17:40:33 | tshepang | set | files: + argparse_howto4.patchmessages: + |
| 2012-04-29 04:21:32 | ezio.melotti | set | nosy: + georg.brandlmessages: + |
| 2012-04-29 03:58:18 | ezio.melotti | set | messages: + |
| 2012-03-31 11:43:23 | tshepang | set | messages: + |
| 2012-03-19 14:49:07 | tshepang | set | files: - argparse_howto3.patch |
| 2012-03-19 14:48:33 | tshepang | set | files: + argparse_howto3.patchmessages: + |
| 2012-03-19 14:42:00 | tshepang | set | files: + argparse_howto3.patchmessages: + |
| 2012-03-19 13:05:43 | ncoghlan | set | messages: + |
| 2012-03-19 12:20:54 | tshepang | set | files: - argparse_howto2.patch |
| 2012-03-19 11:11:02 | tshepang | set | files: + argparse_howto2.patchmessages: + |
| 2012-03-19 11:02:10 | tshepang | set | messages: + |
| 2012-03-19 10:50:58 | tshepang | set | files: + argparse_howto2.patchmessages: + |
| 2012-03-19 08:49:02 | tshepang | set | messages: + |
| 2012-03-19 08:34:42 | tshepang | set | messages: + |
| 2012-03-19 04:17:42 | ncoghlan | set | messages: + |
| 2012-03-19 03:57:34 | ncoghlan | set | messages: + |
| 2012-03-19 03:30:47 | eric.araujo | set | nosy: + ncoghlanmessages: + |
| 2012-03-18 22:07:47 | eric.araujo | set | messages: + |
| 2012-03-18 22:06:35 | tshepang | set | messages: + |
| 2012-02-22 16:22:04 | bethard | set | messages: + |
| 2012-02-22 12:41:04 | eric.araujo | set | messages: + |
| 2012-02-21 10:35:03 | bethard | set | messages: + |
| 2012-02-21 00:01:42 | eric.araujo | set | nosy: + bethardmessages: + title: first example in argparse doc is too complicated -> Add argparse howto |
| 2012-02-20 08🔞41 | tshepang | set | files: + argparse_howto.patchkeywords: + patchmessages: + |
| 2012-02-19 22:54:12 | eric.araujo | set | messages: + title: the example in argparse doc is too complex -> first example in argparse doc is too complicated |
| 2012-02-18 10:44:35 | ezio.melotti | set | nosy: + ezio.melottistage: needs patch |
| 2012-02-17 17:36:04 | tshepang | set | messages: + |
| 2012-02-17 17:03:56 | eric.araujo | set | nosy: + eric.araujomessages: + |
| 2012-02-16 18:34:21 | tshepang | create |