Warning message incomprehensible for end-user

[thorstenkampe]

Wenn I run my script without a necessary subcommand, docopt-ng issues a warning - shouldn't it be an error? - which in my opinion is not suitable for the enduser (found unmatched (duplicate?) arguments [Argument(None, '...')].

Even I as the script writer, don't know what that exactly means. It looks to me like docopt-ng exposes internals from the parsing process which should not be given to the script user.

> python interpreter.py '.\10. PowerShell.ps1'
Warning: found unmatched (duplicate?) arguments [Argument(None, '.\\10. PowerShell.ps1')]
Usage:
 interpreter.py run <script> [-- <script_option> ...]
 interpreter.py doc [-s <text>] <script>

[loelkes]

I had the same issue but fixed it through trial and error. I had something like this:

Usage:
  script.py (--save | --load) FILE

Arguments:
  FILE                     

Options:
  --save FILE
  --load FILE

The error message was:

$ python script.py --save file.ini
Warning: found unmatched (duplicate?) arguments [Option(None, '--save', 1, 'file.ini')]

Removing FILE after --save in Options: did the trick for me.

[jambonrose]

The error message presented is confusing.

Provided the following:

"""CLI

Usage:
  cli <arg1> <arg2>

"""
from docopt import docopt


def main():
    """MVE of confusing error"""
    arguments = docopt(__doc__, version="1.0.0")
    print(arguments)


if __name__ == "__main__":
    main()

The command line behavior is:

$ cli 
Usage:
  cli <arg1> <arg2>

$ cli 1 2
{'<arg1>': '1',
 '<arg2>': '2'}

$ cli 1 
Warning: found unmatched (duplicate?) arguments [Argument(None, '1')]
Usage:
  cli <arg1> <arg2>

The error message provided above should instead tell the command-line user that they need to specify a second argument.

I note for clarity that the help and version features work despite being undocumented.

$ cli --help
CLI

Usage:
  cli <arg1> <arg2>

$ cli -h
CLI

Usage:
  cli <arg1> <arg2>

$ cli --version
1.0.0

[traviswaelbro]

I was running into this issue as well and it ended up being because I was calling docopt(..., options_first=True, ...) and it was evaluating differently than I expected, which was causing the unclear error message. Removing that option resolved it in my case.

[FelixSchwarz]

This is really the most annoying issue in docopt-ng for me. The warning is also shown when a user mistypes an parameter (e.g. --dryrun instead of --dry-run) and the error message is almost impossible to understand as an end user.

[NickCrews]

I agree this is an issue, I would like to see it fixed. I am unlikely to implement it myself in any immediate time frame, but I will happily review any PRs people submit! Please start them small and get feedback quickly, I don't want you to waste your time. Thanks!