argparse required arguments displayed under "optional arguments"

[benschmaus]

BPO	9694
Nosy	@rhettinger, @terryjreedy, @ericvsmith, @merwok, @bitdancer, @vadmium, @mgrandi, @hroncok, @maggyero, @jacktose
PRs	bpo-9694: Fix misleading phrase "optional arguments" #23858
Files	argparse-help-says-required-args-are-optional.py alt_grouping.py helpgroups.diff alt_grouping2.py: Script demonstrating helpgroups.diff patch parrot.py: Script to test alternate wording argparse_option.patch option-internal.patch option-internal.patch argparse_option.v2.patch argparse_optional.txt: Survey of practices

^{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 = 'https://github.com/rhettinger'
closed_at = <Date 2020-12-23.17:41:40.125>
created_at = <Date 2010-08-26.18:19:17.172>
labels = ['type-bug', 'library', '3.10']
title = 'argparse required arguments displayed under "optional arguments"'
updated_at = <Date 2021-01-08.23:51:14.321>
user = 'https://bugs.python.org/benschmaus'

bugs.python.org fields:

activity = <Date 2021-01-08.23:51:14.321>
actor = 'hroncok'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2020-12-23.17:41:40.125>
closer = 'rhettinger'
components = ['Library (Lib)']
creation = <Date 2010-08-26.18:19:17.172>
creator = 'benschmaus'
dependencies = []
files = ['18654', '34065', '34073', '34074', '36528', '37200', '37461', '37505', '42370', '49692']
hgrepos = []
issue_num = 9694
keywords = ['patch']
message_count = 50.0
messages = ['115017', '115019', '115021', '115023', '115032', '115037', '115038', '115045', '115048', '115058', '115059', '115069', '115109', '115117', '115148', '132327', '166183', '208659', '210808', '211121', '211125', '211132', '211205', '226279', '226286', '226290', '231189', '232715', '232928', '243290', '262273', '262297', '262315', '262323', '262553', '262893', '327376', '345542', '345545', '357750', '373997', '383399', '383402', '383404', '383617', '383627', '383650', '384677', '384684', '384700']
nosy_count = 22.0
nosy_names = ['rhettinger', 'terry.reedy', 'bethard', 'eric.smith', 'eric.araujo', 'r.david.murray', 'docs@python', 'benschmaus', 'tshepang', 'martin.panter', 'paul.j3', 'markgrandi', "Martin.d'Anjou", 'Oliver.Smith', 'rhartkopf', 'Albert White', 'tonygaetani', 'shaharg', 'hroncok', 'maggyero', 'Jacktose', 'kkarbowiak']
pr_nums = ['23858']
priority = 'low'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue9694'
versions = ['Python 3.10']

[benschmaus]

The argparse module lists required args as optional in the default help message.

If you run the following program (also attached) you'll get the output listed below.

#!/usr/bin/env python

import argparse

parser = argparse.ArgumentParser(
    description = 'Do something'
)
parser.add_argument('--reqarg', '-r', help = 'This is required', required = True)
parser.add_argument('--optarg','-o', help = "This is optional", required = False)
args = parser.parse_args()

$ python argparse-help-says-required-args-are-optional.py -h
usage: argparse-help-says-required-args-are-optional.py [-h] --reqarg REQARG
                                                        [--optarg OPTARG]

Do something

optional arguments:
-h, --help show this help message and exit
--reqarg REQARG, -r REQARG
This is required
--optarg OPTARG, -o OPTARG
This is optional
$

[ericvsmith]

It looks to me like reqarg is marked as required, since it's not in brackets. Or am I missing something?

[bitdancer]

Yeah, the fact that it is listed under the heading "optional arguments:" :) Guess we need a new section?

[ericvsmith]

Duh. Sorry about that.

Also applies to 3.2.

[bethard]

Yeah, I guess the optional vs. positional isn't the best terminology now that you can have required flag-based arguments. Did you have a word other than "optional" that you'd prefer?

[bitdancer]

Perhaps you could just label them 'options:'? After all, even if you have several options you may be required to pick at least one :)

[ericvsmith]

Or "parameters:"?

[benschmaus]

FWIW, I like the idea of just using the label "options".

[ericvsmith]

If you add a positional parameter by adding:
parser.add_argument('foo')
then the output becomes:

$ python argparse-help-says-required-args-are-optional.py -h
usage: issue9649.py [-h] --reqarg REQARG [--optarg OPTARG] foo

Do something

positional arguments:
foo

optional arguments:
-h, --help show this help message and exit
--reqarg REQARG, -r REQARG
This is required
--optarg OPTARG, -o OPTARG
This is optional

$

So whatever replaces "optional arguments:" needs to read well with "positional arguments:". Maybe just plain "options:" is good enough, but I think a word to replace "optional" (leaving "arguments:") would be better. I just don't have any useful suggestion :)

[bethard]

I guess one possibility might be "flag arguments". It's not great, but I guess it's more accurate.

[bethard]

And I guess the bigger issue to think about is how to add this in a backwards compatible way. I guess we could just add methods like "set_positionals_group_name(name)" and then fiddle with "self._positionals.title" in there. Not sure that's a great solution though - it seems like adding one method to change just this single attribute is overkill and not very general.

In the meantime, here's a workaround:

>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', required=True)
>>> parser._optionals.title = "flag arguments"
>>> parser.print_help()
usage: PROG [-h] --foo FOO

flag arguments:
-h, --help show this help message and exit
--foo FOO

I can't promise this will continue to work, since it uses the undocumented _optionals attribute, but at least it's a way of getting something like what you want now.

[bitdancer]

Well, there's also bpo-9652, which speaks to having a more general facility, I suppose. Maybe an exposed dictionary attribute containing the constant strings?

[terryjreedy]

Is this really a behavior bug or doc bug?
Or a feature request for better message customization?