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.