homepage

>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title="commands")
>>> subparser = subparsers.add_parser('make')
>>> parser.add_argument('jobs', nargs='*')
>>> parser.print_help()
usage: [-h] {make} ... [jobs [jobs ...]]
While the printed usage looks innocuous enough, argparser isn't actually able to parse this the way I expect: The positional argument never get's to handle any jobs given, as apparently everything after the command is handled by the subparser:
>>> parser.parse_args(['make', 'something'])
usage: make [-h]
 make: error: unrecognized arguments: something
It seems that argparse, upon determining that the subparser can't handle a positional argument, could break out of the subparser, and let the parent parser continue. If necessary, as further help for argparse on how to resolve such situations, a parameter could be added to add_subparsers() which would allow the user to indicate that this group of subparsers should not support positional arguments.
The usage string should then print as:
>>> parser.print_help()
usage: [-h] {make} [jobs [jobs ...]]
That is, without the "..." after the command.
Finally, if it is decided that the feature will not be added, argparse should not allow the user to add positional arguments after a subparser.

This is almost a duplicate of issue 9253. Your proposed semantics are different, but it would be better to carry on a discussion of the "correct" semantics in that ticket rather than have two separate and conflicting ones, so I'm closing this as duplicate.