argparse._SubParsersAction.add_parser should default to description matching help

[gsnedders]

Feature or enhancement

Proposal:

import argparse

# create the top-level parser
parser = argparse.ArgumentParser(prog='PROG')
parser.add_argument('--foo', action='store_true', help='foo help')
subparsers = parser.add_subparsers(help='subcommand help')

# create the parser for the "a" command
parser_a = subparsers.add_parser('a', help='a help')
parser_a.add_argument('bar', type=int, help='bar help')

# create the parser for the "b" command
parser_b = subparsers.add_parser('b', help='b help', description='b help')
parser_b.add_argument('--baz', choices=('X', 'Y', 'Z'), help='baz help')

# parse the args
print(parser.parse_args())

This currently produces:

gsnedders@gsnedders-margot tmp.IKpGQE2mE3 % python3.13 test.py --help  
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
  {a,b}       subcommand help
    a         a help
    b         b help

options:
  -h, --help  show this help message and exit
  --foo       foo help
gsnedders@gsnedders-margot tmp.IKpGQE2mE3 % python3.13 test.py a --help
usage: PROG a [-h] bar

positional arguments:
  bar         bar help

options:
  -h, --help  show this help message and exit
gsnedders@gsnedders-margot tmp.IKpGQE2mE3 % python3.13 test.py b --help
usage: PROG b [-h] [--baz {X,Y,Z}]

b help

options:
  -h, --help     show this help message and exit
  --baz {X,Y,Z}  baz help

It would be nicer, however, if add_parser's description parameter defaulted to the value of the help argument.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

#89438 considered not outputting the value of help here to be a bug, but was closed because the description parameter also exists.

Linked PRs

• gh-135227: argparse: Use help as default description in add_parser #135236

[mpkocher]

There are different semantics for description= (longer form text) and help= (short, terse text).

• argparse.ArgumentParser supports description= (help doesn't make any sense here and isn't supported).
• add_argument supports help= but not description (which doesn't make sense in this context)
• The subparser machinery gets caught up in supporting both description= and help= with each keyword has a different semantics meaning that will be interpreted by the formatter

For example:

def example() -> ArgumentParser:
    # description= is very extremely useful and is commonly used
    p = ArgumentParser(description="Long description of my CLI too.")

    # help= and description= are not particularly useful here.
    sp = p.add_subparsers(help="Help Subparsers", description="A Desc of subparsers")

    # help= means my-tool.py --help will show the help text
    # description= means my-tool.py alpha --help will show the description text
    sp0 = sp.add_parser("alpha", help="Help Alpha", description="Long description of alpha")
    
    # help= is very extremely useful and everyone uses this.
    sp0.add_argument("-i", "--input", type=Path, required=True, help="Path to input file")
    return p

The workaround would be.

    p = ArgumentParser(description="Long description of my CLI too.")
    sp = p.add_subparsers()
    # Workaround
    def _add_parser(name: str, text: str):
        return sp.add_parser(name, description=text, help=text)

    sp_beta = _add_parser("beta", "Run beta and x,y,z.")
    sp_gamma = _add_parser("gamma", "Run gamma and filter by a,b,c.")

The argparse subparser interface is a bit clunky, I always end up writing some function that glues/wires the app together. This approach also avoids having tons of local variables with minor naming differences that can create bugs.

https://gist.github.com/mpkocher/e20563d11a978692a647d20850545445#file-shtab_test-py-L34

Other comments:

• Using the default help= text as the description will probably be what most people want. However, this will make the point of having description more confusing.
• .add_supbarsers and .add_subparser need to be consistent.
• be sure to consider the implications of help=argparse.SUPPRESS
• a simple function is a reasonable workaround