invoke: --help isn't discoverable / cannot give --help after task names, only before

I have a number of tools built on invoke that take a number of arguments, and these two things still trip me up when I forget them:

That the way to access the help on a task is inv --help taskname (as opposed to most *nix utiliies, where I could do inv taskname --help)
That when I get the parameters wrong, invoke tells me 'taskname' did not receive all required positional arguments!, as opposed to showing me the help output to aid in figuring out what I forgot.

For the former, my ideal way it would work is that if a someone does inv taskname --help and help isn’t an argument to the task, we show the help and exit (if it is, we treat it like any other argument). I’m thinking this would be in the Executor - is that a good place to start?

For the second, I have an idea for a PR, but it would require passing the collection to the Parser instance (to get access to the docstring). Would this be acceptable, or does that break the separation of concerns you had in mind?

About this issue

Original URL
State: closed
Created 9 years ago
Comments: 15 (10 by maintainers)

Commits related to this issue

Skel failing tests re #205 — committed to pyinvoke/invoke by bitprophet 7 years ago

Most upvoted comments

@nhoening That’s definitely a common pattern but it’s one I’ve resisted in the past - for tools like git the set of subcommands is largely “static” but for Invoke (or Make or etc) the entire point is for that set to be user-defined and highly dynamic.

In that case, the core program itself automatically injecting entries into the set of tasks/subcommands - entries that the user didn’t themselves define - is “magic” and in my experience it’s best to avoid magical behavior when reasonable alternatives exist.

All that said, this is the same argument for not injecting --help after task names, so my earlier counter-argument stands: the number of users who will be unpleasantly surprised by the magic, is probably much lower than the number expecting Invoke to work like other tools they’ve encountered.

And, in this particular case the total frustration level for the former group should be low, vs other “magic” features like Fabric 1’s automatic slash/dollar escaping.

Especially since we can always throw exceptions if users accidentally ‘shadow’ the magic flag/task (i.e. def help() or def foo(help=xxx)) which eliminates one of the most frustrating corner cases that comes up when one has magic around.

bitprophet on Nov 14, 2016