CLI task arguments

[bitprophet]

See also: Fabric #69

Problem

Need to allow parameterization of tasks as invoked via the CLI (tasks invoked via Python are simply passing regular args/kwargs or their list/dict counterparts.) Sub-problem: translating strings/flag existence into Python types such as lists, booleans etc.

Current implementation in Fabric is fab taskname:positional_arg_value,keyword_arg=kwarg_value,.... Some other tools use "regular" CLI flags, e.g. paver taskname -F value.

"Custom"/"attached" args

Pluses:

• Works great for multi-task invokes, zero ambiguity about which param values go to which tasks
• Supports positional arguments well

Minuses:

• Requires custom parsing, which may lead to bugs and at the very least increases code maintenance burden
• Slight documentation burden -- requires users to learn how that custom parsing works, re: need for escaping (esp. how that meshes with normal shell escapes) and etc.

"Regular" flag args

Pluses:

• Can (probably) just use argparse
• Many users already familiar with it

Minuses:

• Doesn't mesh well with multi-task invokes unless we:
  • enforce BSD-style "order matters" (not even sure argparse can do this? EDIT: perhaps with subcommands, if >1 subcommand can be invoked at a time)
  • or use an ugly "task delimiter" syntax like invoke task1 --arg1 --next task2 --arg2 (again, can argparse do this?)
  • or hope/pray that all simultaneously-invoked tasks have zero overlap in their kwargs and no positional args are ever needed.
    • How common is this? If we assume flags nix any possibility of positional args and that this is OK, it could be reasonable to assume two or three tasks called together would all have different names for their kwargs. Maybe.
• Namespace clashes with core (non task related) flags such as -c/--collection
  • This also requires order-matters, or simply limiting the user-allowed namespace
  • Limiting the namespace also presents backwards compatibility problems -- if version 1.1 lacks a --foo flag and a user declares mytask(foo='bar'), and then we unknowingly add --foo to core in 1.2, that user's code will break.
• May require more setup on the user side, re: explicitly declaring each task's args/kwargs via decorators or whatnot
  • Though we could introspect the function signature and automatically create some, if needed
• Doesn't allow for positional arguments unless we go the delimiter route.

Potential solutions

• Continue using Fabric's "custom parsing" solution pretty much as-is
  • See above re: pluses/minuses
• Try coming up with a "better" custom parsing solution/syntax, if there are any
  • What do other tools like Make, Rake, Thor etc use?
    • Thor uses regular flags + positional arguments, seems to simply ignore the "multiple tasks vs one task + positional args" problem, and uses "pass all flags to all tasks" to handle multi-task invocation.
      • Don't like this very much -- it "works" but has the "all tasks invoked must have different args" requirement mentioned above.
    • make uses shell environment variables, which is similar to how Thor treats flags -- every task is going to get the same values for any overlapping names.
    • Rake uses custom parsing like we do, but uses taskname[args, here] instead of taskname:args,here. I find this actually worse than the colon we use, because some shells like zsh treat square-brackets specially and need extra escaping/quoting.
• Allow custom parsing everywhere, but also allow use of flag args in single-task invocations
  • Plus: gives flag lovers what they want
  • Minus: "more than one way to do it" and its problems (newbie confusion, more code/bugs, more docs to write.)
• Use flags 100% of the time, relying on ordering or delimiting flags to handle multi-task invocations
  • See above re: pluses/minuses
  • Possibly use argparse subcommands, but AFAIK those are again targeted at using a single subcommand per invoke.

[bitprophet]

Iteration time:

• A few folks on IRC have mentioned they dislike the custom style for the reasons I anticipated and have heard before -- it's just different than the usual flags, is a bit more of a pain to type, etc.
• The 'delimit' sub-solution to using flags (or another special syntax, though all the non-alpha characters seem like they have special shell meaning already) feels like a dead end -- I'm not even sure argparse can handle it, and since it already implicitly requires "order matters", we may as well just go with the implicit version. (Again, if argparse lets us.)
• Subcommands are right out, argparse definitely cannot do >1 per invoke.

Still reading over argparse to see just what it gives us -- would prefer to work within it instead of doing something totally custom (which would defeat one of the reasons to go with flags anyways.)

[bitprophet]

Looks like argparse can't do interleaved "positional arguments" (i.e. task names) and options (flags), by default.

May be able to hack something together with one of:

• custom action objects
• manually preprocessing sys.argv into core args and a collection of tasks+their args, and using a bunch of "sub" parsers
• screwing around with the '*' version of the nargs action (though this feels like the inverse of what we need, it lets you associated multiple positional values to a given flag -- we need multiple flags associated with a "positional" task name argument.)

[bitprophet]

Custom action objects seem to only work if we knew beforehand how many "options" (non-flag values) were going to be passed in (as we'd need to call add_argument for each "slot"), in which case we'd have to parse argv ourselves anyways.

Though perhaps we could simply add all discovered tasks explicitly, as optional or something, to the parser. Slightly silly but might get the job done.

Will triple check this approach and how nargs works. Might be worthwhile to do the preprocess approach -- I can't think of any real edge cases we need that would make "split things up by not-a-flag strings and optional trailing --, pass each chunk into different parser objects" not work.

Part of me wants to use PyParsing for that, but not sure it's worth the dependency.

[bitprophet]

Right. Preprocessing isn't going to work because it's impossible to distinguish a non-equals-signed flag argument (--foo bar) from a task name, especially in more subtle cases (e.g. if we ever needed to use nargs), without literally reinventing what argparse does. So AFAICT there's no foolproof way to chop things up -- argparse simply doesn't map well to what we're trying to do here.

---

We could try the custom-action route linked above, relying on how the actions get called in order to reconstruct values -- this gives us all the "per argument/flag" parsing (--foo=bar vs --foo bar vs --foo I am using nargs lol) and would let us reconstruct a richer setup, but it has the following problems:

• Aforementioned need to add in all tasks + their arguments to the parser so it actually calls the action on them
  • N.B. optional and not actioned-upon unless actually given, positional args, work best as: parser.add_argument('label', default=argparse.SUPPRESS, nargs='?', action=MyActionClass).
    • MyActionClass only gets called if the task exists (so if you give it 10 and call 2, you only see the action called 2 times)
    • No errors about "too few arguments" when you tell the parser it could accept up to N positional args and <N are given (which would be the case 99.999% of the time, nobody calls their entire fabfile in one go.)
• Have to avoid adding the same flag twice for 2 different tasks, or use ArgumentParser(conflict_handler='resolve') to make it STFU.

---

Theoretically we could go whole hog and just say "fuck it" to argparse and use PyParsing instead, but I'll only do that if bending argparse to my will fails or turns into a huge mess-o-code. And if I still think it's worth it to not use Fab-style tasks.

[bitprophet]

• PyParsing probably wouldn't work after all -- you need the knowledge about whether a given --flag is supposed to take an argument after it (or multiple arguments, or whatever) in order to parse -- parsing a command string with none of that knowledge is impossible. Thus why argparse, etc exist and require use of add_argument.
  • Though we do want to add the type conversion feature eventually -- so if we had that set up, then we could use that information to tell which flags would require arguments and which would be just boolean switches. Feels like even more wheel reinvention, but meh.
• The "messed up argparse" approach is not working -- no matter what setup I use it seems to misinterpret what I want or skip parsing some args or values. There's no way this is going to end well.

[bitprophet]

@kennethreitz had one new spin on the "custom syntax to denote tasks apart" solution, which was to 'decorate' the task names in a custom manner, e.g. invoke task1: arg arg arg task2: arg arg arg.

Benefits: aesthetically pleasing (much nicer than --task=task1 --task=task2), sidesteps the problem of telling flag arguments apart from task names (and thus also allows positional arguments).

Drawbacks: falls into the "custom, non-traditional cli syntax" trap, possibly more confusing to use (what should happen if the colons are omitted? what does invoke task1 task2 do? heck, what does invoke task1 task2: args do? etc) and/or implement.

---

If we take "it's not going to look exactly like traditional argparse style" for granted, then we could also return to the idea of using some non-special-shell-meaning character to delimit task+arg chunks. E.g. invoke task1 args --flags - task2 or invoke task1 args --flags , task2. However, none of the available characters look all that great to me, or -- while not technically special to the shell -- have implications (like - implying that it is a regular arg value meaning to use stdin.)

[bitprophet]

Wrote up a shit ton of thoughts on this yesterday/today: http://docs.pyinvoke.org/en/latest/concepts/cli.html

For now, I am leaning towards the task: version because while it's less orthodox it should (I think) be much easier to parse, also also enables positional arguments, both of which would be kinda nice. We'll see what happens.

[tswicegood]

I think this could be done by chunking up sys.argv ourselves and passing only parts of it in at a time. It would require multiple passes, but would end up with a cleaner interface.

My initial thought is something like:

• Parse for a very small subset of args and determine all tasks.
• Break sys.argv on each task and assume everything after task A and before task B is supposed to go with task A
• Parse each list of arguments for each task.

It wouldn't be pretty and requires at least two trips through argparse, but it would allow invoke --global taskA --some-opt some-opt-value taskB --other --opt value style approaches. We should encourage the use of --opt=value to avoid ambiguous task clashing.

[tswicegood]

FWIW, I'll try taking a stab at the parser and see what I can come up with.

[bitprophet]

We should encourage the use of --opt=value to avoid ambiguous task clashing.

Thanks, I knew I'd forgotten at least one of the alternative approaches. Just added to the doc.

I'm not a fan of forcing users to do this, I feel it's too much of a departure from the "orthodox" style people are used to, even though it would simplify parsing. (Rather, it departs from regular argparse style while looking like it, which is IMO more confusing than being obviously something custom like Fab 1.x style.)

---

Re: the rest of your comment: if we went the "task names have no special decorations" route, we'd pretty much have to A) obtain knowledge of which flags need arguments and B) walk over sys.argv as you said, keeping our own state. (This is the "deep knowledge" methodology I mentioned in the linked docs.)

I think it's quite possible, but we can't use argparse for it unless I missed something seriously big when I spent a day or two the other week fucking around :( I'm also not sure there's any point, in this scenario, to try and use argparse for per-task bits, because just to get to the point where we have each task and its args split apart, we've already had to parse everything. There's nothing left for argparse to do.

I think the only use of argparse possible is if we went with one of the "easy to tell task chunks apart" routes (eg task: or the no-spaces-in-flags route), used one simple manual parse over argv to break things into chunks, then fed each chunk into its own argparse parser. I am actually leaning towards this approach right now, as per earlier comment.

[myusuf3]

👍

[bitprophet]

@tswicegood BTW I was hoping to do at least a proof of concept parser myself tonight / this weekend =( probably trying the colon-decorated approach first FWIW.

[bitprophet]

@myusuf3 (or any other users) do you have any thoughts to share? Specifically, choosing between this style:

$ invoke task1 --no-positional-args-here --kwargs are_ok_though task2

where you can't do positional arguments, but the task names have no special formatting; and this style:

$ invoke task1: positional args --allowed here task2: --task2-args

where you have to do the funky task1: but you can throw in regular non-keyword arguments.

Does the 2nd one look OK, dumb, other? Would you be sad to lose positional arguments if we did the first approach? etc.

[myusuf3]

@bitprophet I like the second one better simply because you need to have positional args. It looks kind of weird when you first look at it; but I can see it easily becoming second nature after a bit of use.

maybe embracing something like task1 | would be worth investigating as a potential replacement for task1:

if majority still finds it funky looking.

[dhellmann]

I've been doing some work in a CLI framework where I want to discover subcommands implemented in plugins, without loading the entire plugin set into the process space just to determine the names of the commands. I found optparse's ability to stop when it encountered a non-flag argument (a value that did not start with "-") helpful. Maybe you should be using that instead of argparse? https://github.com/dhellmann/cliff/blob/master/cliff/app.py#L36