I prefer the idea of help=SUPPRESSED resulting in a "hidden" subcommand. That is, one that does not show up at all in the usage/help output:

    import argparse

    parser = argparse.ArgumentParser(prog='myapp')
    parser.add_argument('--foo', action=CustomAction)
    sub_parsers = parser.add_subparsers(dest='commands', title='subcommands')
    sub_parser = sub_parsers.add_parser('sub-command-1', help='sub-command-1 help')
    sub_parser = sub_parsers.add_parser('sub-command-2', help=argparse.SUPPRESS)
    sub_parser = sub_parsers.add_parser('sub-command-3')

    parser.parse_args(['-h'])

Would result in:

usage: myapp [-h] [--foo FOO] {sub-command-1,sub-command-3} ...

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

subcommands:
  {sub-command-1,sub-command-3}
    sub-command-1       normal subcommand help


Assuming this behavior, what should happen if you request help for a subparser with help=SUPPRESSED? That is, you know the subcommand exists even though it's not mentioned in the usage. I would assume it would show usage as normal (note the description kwarg for sub-command-2):

    import argparse

    parser = argparse.ArgumentParser(prog='myapp')
    parser.add_argument('--foo', action='store_true')
    sub_parsers = parser.add_subparsers(dest='commands', title='subcommands')
    sub_parser = sub_parsers.add_parser('sub-command-1', help='sub-command-1 help')
    sub_parser = sub_parsers.add_parser('sub-command-2',
                                        help=argparse.SUPPRESS,
                                        description='description of suppressed sub-command-2')
    sub_parser = sub_parsers.add_parser('sub-command-3')

    parser.parse_args(['sub-command-2', '-h'])

Would result in:

usage: myapp sub-command-2 [-h]

description of suppressed sub-command-2

optional arguments:
  -h, --help  show this help message and exit


An edge case to consider: what should top-level help look like if ALL subparsers are suppressed? It seems like a degenerate scenario, but complete is important, right? The one that feels most correct to me is to follow the current behavior when you call add_subparsers but never call add_parser:

    import argparse

    parser = argparse.ArgumentParser(prog='myapp')
    parser.add_argument('--foo', action='store_true')
    sub_parsers = parser.add_subparsers(dest='commands', title='subcommands')
    parser.parse_args(['-h'])

Currently results in:
usage: myapp [-h] [--foo] {} ...

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

subcommands:
  {}

Another possibility would be to follow the current behavior when you never even call add_subparsers which would of course remove all notion that subcommands are accepted, but that doesn't feel right to me.