Docopt extreemly unintuitive opions usage

Question

Docopt loves to write lots of documentation, by I can't seem to find a single actual command line call inside their many pages of how to write the comments section. I have this very simple file:

"""Main.py
Usage:
  main.py controller
  main.py model
  main.py form
  main.py -h | --help
  main.py --version
Options:
  -h --help     Show this screen.
  --version     Show version.
  --outfile     Output file.
"""
from docopt import docopt


if __name__ == '__main__':
    arguments = docopt(__doc__, version='Main.py 1.0')
    print(arguments)

I get the first part:

adams-mbp:Aut adam$ python main.py model
{'--help': 0,
 '--outfile': None,
 '--version': 0,
 'Options:': False,
 'Show': 0,
 'controller': False,
 'file.': False,
 'form': False,
 'model': True,
 'screen.': False,
 'this': False,
 'version.': False}

But I can't seem to figure out how to pass an --outfile parameter. Here's what I've tried:

adams-mbp:Aut adam$ python main.py main.py --outfile thing
Usage:
  main.py controller
  main.py model
  main.py form
  main.py -h | --help
  main.py --version
Options:
  -h --help     Show this screen.
  --version     Show version.
  --outfile     Output file.

adams-mbp:Aut adam$ python main.py main.py --outfile=thing
Usage:
  main.py controller
  main.py model
  main.py form
  main.py -h | --help
  main.py --version
Options:
  -h --help     Show this screen.
  --version     Show version.
  --outfile     Output file.

adams-mbp:Aut adam$ python --outfile thing main.py main.py
Unknown option: --
usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ...
Try `python -h' for more information.

adams-mbp:Aut adam$ python --outfile=thing main.py main.py
Unknown option: --
usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ...
Try `python -h' for more information.

adams-mbp:Aut adam$ python main.py main.py -outfile thing
Usage:
  main.py controller
  main.py model
  main.py form
  main.py -h | --help
  main.py --version
Options:
  -h --help     Show this screen.
  --version     Show version.
  --outfile     Output file.

adams-mbp:Aut adam$ python main.py main.py -outfile=thing
Naval Fate.
Usage:
  main.py controller
  main.py model
  main.py form
  main.py -h | --help
  main.py --version
Options:
  -h --help     Show this screen.
  --version     Show version.
  --outfile         Output file.

adams-mbp:Aut adam$ python main.py main.py outfile=thing
Usage:
  main.py controller
  main.py model
  main.py form
  main.py -h | --help
  main.py --version
Options:
  -h --help     Show this screen.
  --version     Show version.
  --outfile     Output file.

Seriously?

score 1 · Answer 1 · answered Jan 11 '19 at 14:35

First of all, why are you calling your script twice?

python main.py main.py --outfile thing  # Will not work
python main.py --outfile thing  # This will be enough

Secondly, the usage section of docopt show you the different way to call your script.

Usage:
  main.py controller
  main.py model
  main.py form
  main.py -h | --help
  main.py --version

main.py model work because it's described here. But --outfile appears nowhere in this Usage section so docopt consider it as a false input. And that's why the script always return the help.

If you want to use this option you have to describe it in "Usage".

You can do this like that :

Usage:
  main.py controller
  main.py model [--outfile]

The bracket tell that the option is not mandatory, use () for mandatory options.

Another point, even you first call show errors, options should not appear in the dictionnary, maybe you should leave a blank before in the documentation. Neither screen, or this. an so on... Try something like that :

"""Main.py

Usage:
    main.py controller [--outfile]
    main.py model [--outfile]
    main.py form [--outfile]
    main.py (-h | --help)
    main.py --version

Options:
    -h, --help     Show this screen.
    --version      Show version.
    --outfile      Output file.
"""
from docopt import docopt


if __name__ == '__main__':
    arguments = docopt(__doc__, version='Main.py 1.0')
    print(arguments)

Docopt extreemly unintuitive opions usage

1 Answers1