[issue41980] Argparse documentation is slightly misleading

[Andrei Kulakov]

Andrei Kulakov  added the comment:

Yannick: the PRs are submitted via github; you can find more detail on 
contributions workflow / process here:

https://devguide.python.org/

--
nosy: +andrei.avk

___
Python tracker 

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

[issue41980] Argparse documentation is slightly misleading

[Yannick Gingras]

Yannick Gingras  added the comment:

Raymond, I would love to submit the PR if we reach a consensus on what the new 
message should be.  I'm a bit out of touch with how things work these days.  Is 
Github the best place to submit the PR?

Paul, very good digging!  Reading the coding and running a few examples, I 
understand that the ``prog`` of the subparser is always the name of the main 
program with the name of the subcommand *unless* a usage string is supplied, in 
which case it overrides prog.  I suspect that the intent is to favour the 
programmer supplied usage string and that copying the usage string in the prog 
of the subparser is an implementation detail.   I think we can reword the 
documentation to describe the expected behavior with more emphasis on the 
common cases.

--

___
Python tracker 

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

[issue41980] Argparse documentation is slightly misleading

[paul j3]

paul j3  added the comment:

For ArgumentParser, prog is defined as:

prog - The name of the program (default: sys.argv[0])

The comment in the `add_subparsers` method is:

   # prog defaults to the usage message of this parser, skipping
   # optional arguments and with no "usage:" prefix

if kwargs.get('prog') is None:
formatter = self._get_formatter()
positionals = self._get_positional_actions()
groups = self._mutually_exclusive_groups
formatter.add_usage(self.usage, positionals, groups, '')
kwargs['prog'] = formatter.format_help().strip()

and this keyword is saved as the action `self._prog_prefix.

Later in `add_parser` this is amended with:

 kwargs['prog'] = '%s %s' % (self._prog_prefix, name)

The intent is to provide the string required to run a particular subparser 
(sub-command), the `prog` of the main, positionals, and the subcommand. (It 
doesn't handle all 'required' arguments correctly.) 

The programmer has three places where they can customize this 'prog'.

So the default 'prog' as the 'add_subarsers' level is indeed just the main 
'prog' plus 'positionals'.  The default 'prog' display with the subcommand 
usage add the subcommand's name.

It's a complicated sequence, but I think the description for the 
'add_subparsers' 'prog' is enough.

--

___
Python tracker 

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

[issue41980] Argparse documentation is slightly misleading

[Raymond Hettinger]

Raymond Hettinger  added the comment:

That sounds likes reasonable improvement.  Would you like to submit a PR?

--

___
Python tracker 

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

[issue41980] Argparse documentation is slightly misleading

[Karthikeyan Singaravelan]

Change by Karthikeyan Singaravelan :


--
nosy: +paul.j3, rhettinger

___
Python tracker 

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

[issue41980] Argparse documentation is slightly misleading

[Yannick Gingras]

New submission from Yannick Gingras :

In argparse.rst, while documenting ArgumentParser.add_subparsers, ``prog`` is 
described on line 1630 as:
  usage information that will be displayed with sub-command help,
  by default the name of the program and any positional arguments 
  before the subparser argument

This is confusing since ``prog`` is actually a very small prefix of the usage 
message.  Describing this parameter as "name of the program" or event "name of 
the program with sub-commands" would be more clear.

--
components: Library (Lib)
messages: 378316
nosy: ygingras
priority: normal
severity: normal
status: open
title: Argparse documentation is slightly misleading
versions: Python 3.9

___
Python tracker 

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