[docs] [issue20598] argparse docs: '7'.split() is confusing magic

paul j3 report at bugs.python.org
Thu Jan 28 13:38:50 EST 2016


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 at bugs.python.org>
<http://bugs.python.org/issue20598>
_______________________________________


More information about the docs mailing list