docopt not allowing optional arguments

Question

I have the following usage in docopt:

cli.py add_user <user_file> [<devices_file>] <destination_account> <token>
cli.py remove_user (--id|--username) <user_id> <source_account> <token>

Where [<devices_file>] is an optional argument.

However, when I try to use it as such, I get an error.

This works okay:

add_user user_29087.json dev_29087.json 531 token

This throws an error:

add_user user_29087.json 531 token

Error:

Traceback (most recent call last):
  File "C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\Extensio
ns\Microsoft\Python Tools for Visual Studio\2.0\visualstudio_py_util.py", line 7
6, in exec_file
    exec(code_obj, global_variables)
  File "C:\Users\mryan\Documents\Code\cli\cli_front.py", line
 49, in <module>
    arguments = docopt(__doc__, version='1.0.0rc2')
  File "C:\Users\mryan\Documents\Code\cli\common\docopt.py", l
ine 581, in docopt
    raise DocoptExit()
DocoptExit: Usage:
    cli.py get_token
    cli.py add_user <user_file> [<devices_file>] <destination_account> <token>
    cli.py remove_user (--id|--username) <user_id> <source_account> <token>
    cli.py get_users <account_id> <token>

Can anybody see what I am doing wrong?

Answer 1

From your usage in add_user, I can't see how the CLI would differentiate if there is or is not an optional devices_file.

In your second example, it appears it's assuming 531 is your optional , and you're just missing your , since it has no way to interpret that "531" entry as a device file.

Since devices_file is optional, I would write it like this:

Usage:
    add_user <user_file> <destination_account> <token> [<devices_file>]

OR

Usage:
    add_user <user_file> [-d DEVFI | --devices-file=DEVFI] <destination_account> <token>

Options:
    -d DEVFI --devices-file=DEVFI    Optional devices file for blah.

Note that in the documentation, options are pretty much always done at the end.

"""Naval Fate.

Usage:
  naval_fate.py ship new <name>...
  naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
  naval_fate.py ship shoot <x> <y>
  naval_fate.py mine (set|remove) <x> <y> [--moored | --drifting]