This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Argparse documentation is slightly misleading
Type: Stage:
Components: Library (Lib) Versions: Python 3.9
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: andrei.avk, paul.j3, rhettinger, ygingras
Priority: normal Keywords:

Created on 2020-10-09 12:34 by ygingras, last changed 2022-04-11 14:59 by admin.

Messages (5)
msg378316 - (view) Author: Yannick Gingras (ygingras) * Date: 2020-10-09 12:34
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.
msg378365 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-10 05:31
That sounds likes reasonable improvement.  Would you like to submit a PR?
msg378369 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2020-10-10 07:32
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.
msg378393 - (view) Author: Yannick Gingras (ygingras) * Date: 2020-10-10 13:07
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.
msg398724 - (view) Author: Andrei Kulakov (andrei.avk) * (Python triager) Date: 2021-08-02 01:14
Yannick: the PRs are submitted via github; you can find more detail on contributions workflow / process here:
Date User Action Args
2022-04-11 14:59:36adminsetgithub: 86146
2021-08-02 01:14:38andrei.avksetnosy: + andrei.avk
messages: + msg398724
2020-10-10 13:07:37ygingrassetmessages: + msg378393
2020-10-10 07:32:11paul.j3setmessages: + msg378369
2020-10-10 05:31:20rhettingersetmessages: + msg378365
2020-10-10 04:58:01xtreaksetnosy: + rhettinger, paul.j3
2020-10-09 12:34:19ygingrascreate