I was suggesting a doc bug only if the current doc didn’t advertise clearly this way of combining nargs with positional arguments. Using “--” is most certainly standard and right,
Using “--” to explicitly signal positional arguments is most certainly right and standard, but people have to read about that for the first time somewhere. In a perfect world, that would be in their shell’s man page, but better add a word about it in the reference. The “--” marker is actually mentioned in one section: http://docs.python.org/dev/library/argparse#arguments-containing
I’m reopening, suggesting that a line be added to explain the standard “--” separator for use cases like Sergey’s.