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

[Berker Peksag]

Changes by Berker Peksag :


--
stage: patch review -> resolved

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[STINNER Victor]

STINNER Victor added the comment:

Thanks. The doc looks better like that.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Martin Panter]

Martin Panter added the comment:

I committed my simpler patch. I hope that is okay :)

--
resolution:  -> fixed
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Roundup Robot]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Martin Panter]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Martin Panter]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Martin Panter]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Serhiy Storchaka]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[SilentGhost]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[paul j3]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Benjamin Peterson]

Benjamin Peterson added the comment:

I don't feel that strongly about it.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Julian Berman]

Julian Berman added the comment:

+1 to lists all over, this is just confusing.

--
nosy: +Julian

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[paul j3]

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 rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Éric Araujo]

Changes by Éric Araujo mer...@netwok.org:


--
nosy: +eric.araujo

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Thomas Guettler]

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 rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[STINNER Victor]

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 rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[STINNER Victor]

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 rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Benjamin Peterson]

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 rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[Benjamin Peterson]

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 rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

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

[STINNER Victor]

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 rep...@bugs.python.org
http://bugs.python.org/issue20598
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com