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
$

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

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

Duh. Sorry about that.

Also applies to 3.2.

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?

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

Or "parameters:"?

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

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

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

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.

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

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

*This* bug is a behavior bug (required flags are mis-labelled as being optional in the help text).  The referenced bug is a feature request, but it may make sense to consider it while fixing this one.

I think this is still really a feature request. We can't just change the text from "optional" - that would silently change a large number of help messages without any warning. So to fix this "bug", we're going to have to add an API to explicitly set the group names - which can only be done as a new feature. People using 2.7 will have to use the workaround using parser._optionals I posted here.

So it strikes me that there already exists an officially supported way to rename your option groups. Just only create your own option groups (never use the default ones) and only put arguments there, e.g.:

------------------------- temp.py --------------------------
parser = argparse.ArgumentParser(description = 'Do something', add_help=False)
flags = parser.add_argument_group('flag arguments')
flags.add_argument('-h', '--help', action='help')
flags.add_argument('--reqarg', '-r', help='This is required', required=True)
flags.add_argument('--optarg','-o', help="This is optional", required=False)
args = parser.parse_args()
------------------------------------------------------------
$ python temp.py --help
usage: temp.py [-h] --reqarg REQARG [--optarg OPTARG]

Do something

flag arguments:
  -h, --help
  --reqarg REQARG, -r REQARG
                        This is required
  --optarg OPTARG, -o OPTARG
                        This is optional
------------------------------------------------------------

The documentation for action='help' needs to be added, as pointed out in Issue# 10772.

So basically, the API for customizing group names is already there. So I'm changing this to a documentation request - there should be an example in the docs showing how to change the default group names as above.