[doc] contradictory documentation for prog option of argparse

[asmeurer]

BPO	20970
Nosy	@merwok, @bitdancer, @asmeurer, @iritkatriel, @slateny
PRs	gh-65169: Clarify prog behavior in argparse #31602
Files	issue20970.patch: issue 20970 patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-03-18.16:42:49.127>
labels = ['easy', 'type-bug', '3.9', '3.10', '3.11', 'docs']
title = '[doc] contradictory documentation for prog option of argparse'
updated_at = <Date 2022-03-01.18:03:51.714>
user = 'https://github.com/asmeurer'

bugs.python.org fields:

activity = <Date 2022-03-01.18:03:51.714>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2014-03-18.16:42:49.127>
creator = 'Aaron.Meurer'
dependencies = []
files = ['34517']
hgrepos = []
issue_num = 20970
keywords = ['patch', 'easy']
message_count = 12.0
messages = ['213988', '213998', '214012', '214015', '214038', '214041', '214046', '214047', '214052', '214063', '214087', '414286']
nosy_count = 8.0
nosy_names = ['eric.araujo', 'r.david.murray', 'Aaron.Meurer', 'docs@python', 'paul.j3', 'lilbludot', 'iritkatriel', 'slateny']
pr_nums = ['31602']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue20970'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• [3.13] gh-65169: Clarify prog default in argparse (GH-31602) #124430
• [3.12] gh-65169: Clarify prog default in argparse (GH-31602) #124431

[asmeurer]

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.

[bitdancer]

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.

[paulj3]

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?

[bitdancer]

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.

[asmeurer]

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.

[paulj3]

The relevant code is:

    prog = _os.path.basename(_sys.argv[0])

[lilbludot]

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.

[bitdancer]

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.)

[lilbludot]

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?

[paulj3]

Cross reference for sys.argv[0] is

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

---

[bitdancer]

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".