classification
Title: contradictory documentation for prog option of argparse
Type: Stage:
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Aaron.Meurer, docs@python, eric.araujo, lilbludot, paul.j3, r.david.murray
Priority: normal Keywords: patch

Created on 2014-03-18 16:42 by Aaron.Meurer, last changed 2014-03-19 14:41 by lilbludot.

Files
File name Uploaded Description Edit
issue20970.patch lilbludot, 2014-03-19 14:41 issue 20970 patch review
Messages (11)
msg213988 - (view) Author: Aaron Meurer (Aaron.Meurer) Date: 2014-03-18 16:42
I hope it's OK to report documentation issues on this tracker.  Reading http://docs.python.org/3.4/library/argparse.html#prog I had to do a double take. The documentation states, "By default, ArgumentParser objects uses sys.argv[0] to determine how to display the name of the program in help messages." The example then goes on to show it *not* using sys.argv[0] (sys.argv[0] in the second example would be 'subdir\myprogram.py'). 

Furthermore, even though the commands are apparently POSIX style, with a $ prompt and using cd, they use a backslash to access a subdirectory.
msg213998 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-18 18:01
You missed the part where it says "no matter where it is called from".  That is, the path is stripped off.  The sentence could be changed to emphasize that ("the :ref:`~os.basename` of sys.argv[0]").

The backslash is indeed a bit odd and probably should be changed.
msg214012 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2014-03-18 20:14
Yes, the documentation is accurate but a bit vague.  It doesn't say how 'it uses sys.arg[0]'.  The example implies it uses 'basename'. So the question is, whether that implementation detail should be more explicit?
msg214015 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-18 20:34
I didn't mean the basename reference as exposing an implementation detail (I didn't look) but rather as a shorthand for explaining what "regardless of where the program was invoked from" means.
msg214038 - (view) Author: Aaron Meurer (Aaron.Meurer) Date: 2014-03-19 00:18
The next sentence further confuses things, "This default is almost always desirable because it will make the help messages match how the program was invoked on the command line." It makes it sound like it really did intend to use sys.argv[0] literally.
msg214041 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2014-03-19 00:36
The relevant code is:

    prog = _os.path.basename(_sys.argv[0])
msg214046 - (view) Author: Kinga Farkas (lilbludot) * Date: 2014-03-19 01:35
So, would it be helpful to rephrase the original text

"By default, ArgumentParser objects uses sys.argv[0] to determine how to display the name of the program in thehelp messages. This default is almost always desirable because it will make the help messages match how the program was invoked on the command line." 

 by 

"By default, ArgumentParser objects uses the base name of the path sys.argv[0] to determine how to display the name of the program in the help messages."

And then all that would remain is to change the backslash to a forward slash in the example that follows.
msg214047 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-19 01:43
I think 'base name' should be defined somehow (perhaps "see :ref:`os.basename`?)  And I agree that that second sentence should be made less ambiguous.  Perhaps "make the help messages use the same name that was used to invoke the program on the command line".  (Many people won't know that you can invoke the same script by more than one name on unix by using symlinks, which is what makes that statement read wrong in its current form.)
msg214052 - (view) Author: Kinga Farkas (lilbludot) * Date: 2014-03-19 04:48
Would the second sentence sound good if phrased as:
"This default is almost always desirable because it will make the help messages use the same name that was used to invoke the program on the command line, whether it be the base name or a symlink.  
 
As I am working on my first contribution here, I am not quite sure of the conventions. 
In the official documentation:
1. would you create a reference to  os.basename or os.path.basename?
2. would you use the word symlink or the term symbolic link or it does not matter?
msg214063 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2014-03-19 07:41
Cross reference for sys.argv[0] is

http://docs.python.org/3.4/library/sys.html

> _______________________________________
>
msg214087 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-19 12:38
You are correct, it is os.path.basename.

"base name or symlink" are not alternatives.  It would be the base name *of* the symlink if a symlink was used to invoke the program.  I'm not sure that introducing the concept of the symlink here is helpful...someone that knows about it will understand, someone that doesn't won't be sufficiently enlightened.  But I'm just one opinion.

Another way to clarify this would be to say "the name used by help will automatically change if the script is renamed".
History
Date User Action Args
2014-03-19 14:41:47lilbludotsetfiles: + issue20970.patch
keywords: + patch
2014-03-19 12:38:37r.david.murraysetmessages: + msg214087
2014-03-19 07:41:54paul.j3setmessages: + msg214063
2014-03-19 04:48:05lilbludotsetmessages: + msg214052
2014-03-19 01:43:14r.david.murraysetmessages: + msg214047
2014-03-19 01:35:47lilbludotsetnosy: + lilbludot
messages: + msg214046
2014-03-19 00:36:44paul.j3setmessages: + msg214041
2014-03-19 00:18:18Aaron.Meurersetmessages: + msg214038
2014-03-18 20:34:45r.david.murraysetmessages: + msg214015
2014-03-18 20:14:56paul.j3setnosy: + paul.j3
messages: + msg214012
2014-03-18 19:40:45eric.araujosetnosy: + eric.araujo
2014-03-18 18:01:59r.david.murraysetnosy: + r.david.murray

messages: + msg213998
versions: + Python 2.7, Python 3.4, Python 3.5
2014-03-18 16:42:49Aaron.Meurercreate