I set a positional argument and an optional argument that accepts a list:
> parser = argparse.ArgumentParser()
> parser.add_argument('foo')
> parser.add_argument('-bar', nargs='*')
The usage line I get from --help is this:
> $ example.py --help
> usage: example.py [-h] [-bar [BAR [BAR ...]]] foo
Trying to actually follow the usage instructions produces this error:
> $ example.py -bar x y z
> error: too few arguments
Reversing the argument order works however:
> $ example.py z -bar x y
So the usage instructions are clearly wrong.