--help and --help-commands #40

miracle2k opened this Issue Jul 28, 2012 · 12 comments


None yet

2 participants


I see that this works better in the current master. Still, there is an issue:

 $ script.py --help

will always trigger the --help-commands action, when I would expect it to show the help.


Could you paste here the usage that is being parsed?

"""Control Onkyo A/V receivers.

  onkyo [--host <host>] [--host <port>] [--all] [--name <name>] <command>...
  onkyo --discover
  onkyo --help-commands [<zone> <command>]
  onkyo -h | --help

Selecting the receiver:

  --host, -t <host>     Connect to this host
  --port, -p <port>     Connect to this port [default: 60128]
  --all, -a             Discover receivers, send to all found
  --name, -n <name>     Discover receivers, send to those matching name.

If none of these options is given, the program searches for receivers,
and uses the first one found.

  --discover            List all discoverable receivers
  --help-commands       List available commands.

  onkyo "power on" "source pc", "volume 75"
    Turn receiver on, select "PC" source, set volume to 75.
  onkyo muting off
    If only a single command is sent, it is not necessary to wrap it in

(this issue is probably related to docopt.php one: docopt/docopt.php#2)


Right now (although undocumented) it is allowed to pass "unique prefixes" of options like:

If there is an option --version you can type just --ver instead. But if there also an option --verbose then --ver will not be a unique prefix any more.

So --help is a valid prefix for both --help and --help-commands, however --help option is handled specially when help=True is passed to docopt function, so there is a bug somewhere.

According to how the current implementation was thought: there should not be a reason for an option to be a valid prefix of another option. But it's second time when there is an issue with that (see the docopt.php issue above).

There could be a quick fix for handling this somehow, but (looks like) the bigger problem is the allowance of those unique prefixes. I'm more and more in favor of removing this feature...


To be more to the point, why not:

onkyo help [<zone> <command>]

BTW, are those typos? [--host <port>] and onkyo "power on" "source pc", "volume 75" (comma).

Also, I have seen this convention more often:

onkyo power=on source=pc volume=75

than yours:

onkyo "power on" "source pc" "volume 75"

Those are both good ideas; and I'll consider them.

Still, I think overlapping flags should be supported; in particular because except for this bug, there really isn't a reason why that feature would be incompatible with the auto-expanding of partially specified options.

I'm -0 myself on removing the unique prefixes feature (by which I assume you mean the ability to specify --he to refer to --help). It's nice to have, but I wouldn't find myself using it, and I would mind being able to disable it.

@keleshev keleshev added a commit that referenced this issue Jul 29, 2012
@keleshev keleshev Fix issue 40, #40 e5d5b5a

I just committed fix for this on master branch—your example should work.

The "unique prefixes" feature is still there, not sure, though, about it's future.

As soon as you can confirm that the bug is resolved, I will submit new version to PyPI.


Yes, it works fine now. Thanks.


You are welcome! And thanks for reporting the bug.

@keleshev keleshev closed this Jul 29, 2012

@miracle2k I just thought of another CLI suggestion, you can do this:

Usage: onkyo (<command> <value>)...
$ python onyko.py  power on  source pc  volume 75
{'<command>': ['power', 'source', 'volume'],
 '<value>': ['on', 'pc', '75']}

This usage will make sure that equal number of <command>s and <value>s is passed.


It's cool that this is possible, but in fact it's not a good fit here, because commands have an optional third part.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment