[issue20598] argparse docs: '7'.split() is confusing magic
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
New submission from Thomas Guettler: I think the docs of argparse still contain confusing magic: parser.parse_args('7'.split()) You know what it does and I know it. But a lot of people new to Python, don't understand what this should be. Please use: parser.parse_args(['7']) Close this ticket, if you don't care for people new to Python. ---------- assignee: docs@python components: Documentation messages: 210950 nosy: docs@python, guettli priority: normal severity: normal status: open title: argparse docs: '7'.split() is confusing magic versions: Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
STINNER Victor added the comment: I agree that '7'.split() looks strange, an explicit list would be more obvious and simpler: ['7']. 'X --foo Y'.split() can be replaced with ['X', '--foo', 'Y']. argparse examples: http://docs.python.org/dev/library/argparse.html#type ---------- nosy: +haypo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
STINNER Victor added the comment: @Thomas Guettler: Would you be interested to propose a patch on the source of the documentation directly? You can find the file here: http://hg.python.org/cpython/file/default/Doc/library/argparse.rst ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Benjamin Peterson added the comment: I agree that does look weird. However, it's nicely consistent with the the normal case which has multiple arguments like "-foo 3 -l".split(). I think this is an excellent thing for newcomers to try out with the interactive shell. :) ---------- nosy: +benjamin.peterson _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Benjamin Peterson added the comment: IMO, keeping the string intact is slightly better because it's easier to read than a commandline with a bunch of quotes and commas in the middle. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
STINNER Victor added the comment:
IMO, keeping the string intact is slightly better because it's easier to read than a commandline with a bunch of quotes and commas in the middle.
Many other argparse examples which use list literals. I don't see quotes in >>7<< string :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Changes by Éric Araujo <merwok@netwok.org>: ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
paul j3 added the comment: For documentation, ['this','is','a','test'] might be a bit clearer than 'this is a test'.split(). But generating a list of strings by split is, I think, a pretty basic idiom. But for testing purposes the split() version is a bit more robust because it is closer to what might appear in sys.argv. In [196]: ['this','is','a','test'][-1] is 'test' Out[196]: True In [198]: 'this is a test'.split()[-1] is 'test' Out[198]: False That is, the 'id' of a string generated by a split is not the same as that of an explicit string. sys.argv is created by a split in the shell and/or the interpreter, so it too will fail this 'is' test. ---------- nosy: +paul.j3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Julian Berman added the comment: +1 to lists all over, this is just confusing. ---------- nosy: +Julian _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Martin Panter added the comment: Here is a patch changing all the '. . .'.split() calls to lists of strings. I think the illustrations are actually less complicated to understand when you see the list directly, and they more consistent with the remaining illustrations that already use lists, but I see Benjamin disagrees. ---------- keywords: +patch nosy: +martin.panter stage: -> patch review versions: +Python 3.5, Python 3.6 Added file: http://bugs.python.org/file41739/arg-list.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Benjamin Peterson added the comment: I don't feel that strongly about it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
SilentGhost added the comment: I think it's worth saying that this wasn't a random choice intended to confuse beginners. Strings used represent input that is identical to the command-line input: if one wants to test it, one can just copy that string directly into the propmpt, it might be harder to reconstruct it from a list of strings. ---------- nosy: +SilentGhost _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Serhiy Storchaka added the comment: Using str.split() for splitting full command line on arguments is anti-idiom. More correct way is to use shlex. But this is overkill for argparse examples (and in most cases we already have a list sys.argv). Explicit lists look clear enough. The patch LGTM. ---------- assignee: docs@python -> martin.panter nosy: +serhiy.storchaka stage: patch review -> commit review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
paul j3 added the comment: I can understand changing '7'.split() but this change is IMO ugly: - >>> print(parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())) + >>> print(parser.parse_args(['--foo', 'B', 'cmd', '--arg1', 'XX', 'ZZ'])) I've answered a lot of argparse questions on Stackoverflow, and don't recall anyone being confused by the use of 'split' in the documentation. The documentation as a whole is overwealming to many users. But not this detail. Many SO answers use the split idiom. Being aware of this issue I have edited some of my answers to use lists, even if I used split when creating them in Ipython. But only in the short cases. Other times I copy-n-paste a complete (short) script, along with one or more sample runs (bash line plus printout). That kind of display is closer to what most new users expect and see. But it does not fit with the doctest format used in the argparse documentation. Come to think of it, the doctest example format might be a greater hindrance to understanding than the split idiom. New users tend to construct complete scripts, and then complain that it doesn't do what they want. Often I have to ask them to print sys.argv to see what the shell is giving the parser. And to print args to see what parser is giving back. New users aren't in habit of using interactive test inputs as illustrated in the docs. The patch proposed here may be nice in terms of consistency, but I don't think it improves readability. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Martin Panter added the comment: I don’t want to make any controversial changes. Half the purpose of the patch was to let people see what it would look like. Another option would be to only do the single or empty list changes, and leave most of the longer lists as they are with split(). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Martin Panter added the comment: Here is a more conservative patch. What do you think Paul? * Keep all the changes to single-item and empty lists * Revert many of the other changes, except where there are only a few arguments and I feel it would make the section or piece of code too inconsistent ---------- stage: commit review -> patch review Added file: http://bugs.python.org/file41915/single-arg-list.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Roundup Robot added the comment: New changeset 44f888e47ab0 by Martin Panter in branch '2.7': Issue #20598: Replace trivial split() calls with lists in argparse docs https://hg.python.org/cpython/rev/44f888e47ab0 New changeset 49561532504c by Martin Panter in branch '3.5': Issue #20598: Replace trivial split() calls with lists in argparse docs https://hg.python.org/cpython/rev/49561532504c New changeset 14cb17682831 by Martin Panter in branch 'default': Issue #20598: Merge argparse docs from 3.5 https://hg.python.org/cpython/rev/14cb17682831 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Martin Panter added the comment: I committed my simpler patch. I hope that is okay :) ---------- resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
STINNER Victor added the comment: Thanks. The doc looks better like that. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
![](https://secure.gravatar.com/avatar/fa0f7819f1825f596b384c19aa7dcf33.jpg?s=120&d=mm&r=g)
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- stage: patch review -> resolved _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20598> _______________________________________
participants (11)
-
Benjamin Peterson
-
Berker Peksag
-
Julian Berman
-
Martin Panter
-
paul j3
-
Roundup Robot
-
Serhiy Storchaka
-
SilentGhost
-
STINNER Victor
-
Thomas Guettler
-
Éric Araujo