Hi colleagues I have the code (max_help_position is 2000):

formatter_class=lambda prog: argparse.HelpFormatter(prog, max_help_position=2000)
parser = argparse.ArgumentParser(formatter_class=formatter_class)


subparsers = parser.add_subparsers(title="Commands", metavar="<command>")

cmd_parser = subparsers.add_parser('long_long_long_long_long_long_long',
                                   help='- jksljdalkjda',
                                   formatter_class=formatter_class)

args = parser.parse_args(['-h'])
print args

Result:

we have

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

Commands:
  <command>
    long_long_long_long_long_long_long
                                      - jksljdalkjda
    small                             - descr

instead

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

Commands:
  <command>
    long_long_long_long_long_long_long - jksljdalkjda
    small                              - descr

The code:

class MyFormatter(argparse.HelpFormatter):
    def __init__(self, prog):
        super(MyFormatter, self).__init__(prog, max_help_position=2000, width=2000)
        self._max_help_position = 2000
        self._action_max_length += 4

got same result.

The strings like:

formatter_class = lambda prog: argparse.HelpFormatter(prog,
                  max_help_position=2000, width=2000)

formatter_class = lambda prog: argparse.HelpFormatter(prog,
                  max_help_position=1000, width=2000)

formatter_class = lambda prog: argparse.HelpFormatter(prog,
                  max_help_position=2000, width=1000)

got same result: we always have new line after command.