Task-list format option

[bitprophet]

I.e. instead of just inv --list spitting out the current default flat list, allow things like inv --list nested for a nested/indented display, inv --list=foo to just list the tasks within namespace foo, etc ad infinitum.

LATER EDITS: so a lot of strongly related tickets have popped up and there seem to be two major currents:

• Formatting, i.e. flat with dots vs nested vs machine-readable
• Content, i.e. all tasks vs just namespaces vs just tasks within a given namespace

Seems unwise/impossible to shoehorn all of that under a single optional value to --list so I'm sure we'll grow some additional flags either way, with the main question being which (if any) such option deserves to live as the optional --listvalue.

Brainstorm:

• Format could be a single flag with string option, e.g. --list-format (flat|nested|machine) (what term do other tools use for "machine-readable" anyways? Can't remember offhand...LATER EDIT: actually these days we often just use JSON for that and just call it eg --list-format=json) or it could be a handful of booleans like --list-nested, --list-machine.
  • Former feels easier to implement, harder to fuck up by giving >1 at a time, and easier for users to grasp (i.e. fewer options to think about) so it seems like a no-brainer.
• Content needs levers for 'root' (though this needs to not clash with the related-but-distinct --root flag which changes where tasks files are sought from; but perhaps we should be, well, namespacing those as well so they are renamed to eg --discovery-root) and 'depth` and I think that's it, since those together can enable just about anything:
  • "Show me everything": root is the top of the namespace, depth is None
  • "Show me just the namespaces": root is top of namespace, depth is 1
  • "Show me just tasks under namespace foo"
• Might actually need another lever for the confluence of those two, i.e. "I am listing some subset of tasks and I want to tweak whether they are shown as full paths or sub-paths"?
  • Though at this point I wonder if users who want a non-full-path display (i.e. inv --namespace foo --list spitting out task names like bar and baz instead of foo.bar and foo.baz) should be relying on "each Python module can be its own standalone namespace" and doing things like inv --collection=namespace --list" instead (see Collection loading.)
    • Since, if one truly wants to 'focus' on a given sub-namespace, giving it to --collection automatically ensures that everything - display, invocation, etc - instantly works as you'd expect.
  • The main argument I can think of why one would not want to go that route is if one wanted to do nontrivial slice n dice of namespace contents within the root tasks file (such that the namespace does not reflect Python module or package structure.)
  • However it's not necessarily out of the running, we could either implement things to be depth-aware and default to stripping out parent levels on display/invocation – or (probably better) just make it possible to say "hey I know you loaded my root tasks namespace, but I'd like you to act as if I gave you foo.bar as an argument to --collection - even though, between you and me, foo.bar isn't visible on the Python import paths."
  • Rereading this later, my gut says "ugh we're making this too complex, just add another flag if people REALLY want to see non-full paths for some stupid reason". And besides, what happened to the 'nested' idea? That's another way to show the 'short' names while clearly presenting depth/parentage.
• Minor quirk: do we bother showing the root namespace when we are being asked to "show me the namespaces"? I'm leaning towards no, but might be nice to be explicit...? e.g. "your namespaces are: (root), foo and bar"

[bitprophet]

See #57 which is trying to implement this (--flag and --flag option) for the parser.

[bitprophet]

See also #104 which doesn't entirely obviate this but does intend to implement one major other "list format" (machine-readable).

[bitprophet]

#380 is another "folks definitely want this" example.

---

When I originally wrote this ticket, optional flag args weren't implemented, but #57 got done some time ago, so nothing is in the way of this besides the actual implementation of additional list formats.

[bitprophet]

See also #379 which is a strongly related request for "list just the namespaces", "show namespace docstrings when listing (vs task docstrings when doing --help)" and so on.

[bitprophet]

Starting out with the obvious approach, e.g:

• --list backwards compat
• --list foobar lists only tasks within foobar
• --list-depth N limits depth, e.g. --list --list-depth 1 shows just top level tasks/namespaces
• --list-format nested shows nested tree, --list-format json outputs JSON, etc

Still not sure how to handle namespace stripping (eg. --list foobar - is the output in normal mode foobar.task1, foobar.task2 or simply task1, task2?) but I think I'll start with the easy & clean option, which is no stripping. (Plus, as noted in the desc, --list-format nested will probably strip incidentally.)

This stuff should end up more refactored and flexible just by virtue of implementing all the rest, so adding on a strip option should be relatively painless if enough users clamor for it.

[bitprophet]

Also pondering whether use of --list-depth and/or --list-format should imply --list, it'd be a bit less typing and it's not like those flags could mean anything if given on their own otherwise. Smells like another "nice to add" later.

[bitprophet]

Also thinking the nested display option probably wants to not bother with the first-line-of-docstring column, since it degrades poorly once nesting gets too deep (e.g. trying to wrap the docstring line into a narrow column would eventually get ridiculous and take up far too much vertical space.) In an ideal world we'd just borrow a page from responsive web UX design and have the docstring column disappear at that point, but I don't have that kind of time right now :(

The base case of only a few nested levels, would look nice w/ the docstring column, but sacrifices must be made for now.

[bitprophet]

Also, the JSON format "wants" to be very rich and contain fully serialized JSON copies of Task and Collection objects (so it could be used to e.g. power external completion or presentation code that can't actually call inv --completion, etc - think Web portals.)

But in the interests of expediency (and also because serialization is never actually simple to do right, and also adds more friction re: changing these classes' APIs) I'm sticking to largely the same data that is exposed in the other formats: task and collection names, docstrings, and relationships. As always we can add more to this later if folks really need it.