Command heirarchy/grouping

[jaswilli]

Do we want to promote certain commands to be top-level commands? Example: "endpoint search" is currently globus transfer endpoint search. Should it be globus search?

Other commands where this would make sense?

[jaswilli]

Candidates:

transfer endpoint search -> endpoint-search
transfer endpoint ls -> endpoint-ls

[sirosen]

Just to have this on-record: I don't think it's a good idea to promote any other commands, at least for now.
The clean siloing of functionality by subservice becomes more beneficial the more services we add, and the chances for naming conflicts or confusion within a given subservice is highly unlikely.

We consider these two operations (endpoint search and ls) safe to promote because they operate in terms of one of our fundamental model objects, namely Endpoints. As such, the chances of a conflict with another service are exceedingly low.

However, getting back on my high-horse now, I think that requiring calls to a service to be done as explicit commands against that service is a very clean and natural design in the multi-service world. It also maps very well back onto the types of client objects with which a person is likely to interact if they need to move onto the SDK.

[sirosen]

It turns out that this is a lot messier than I thought it would be, for the simple reason that re-attaching commands (my original plan) does not have the right semantics.
A click.Command object has its name as an attribute.
If we re-attach globus transfer ls as a globus subcommand, it will be globus ls. We cannot rename it at that point.

There is a tutorial on aliasing MultiCommand subcommands: http://click.pocoo.org/6/advanced/
That means that re-attaching globus transfer ls to be globus endpoint-ls requires fairly deep modification of the globus command.
Given that we're already wrapping the top level command in a custom class to implement the custom excepthooks, that should be simple -- except that it results in a cyclic dependency between globus_cli.services.transfer and globus_cli.parsing. Resolving that sounds highly unattractive, especially since the "solution" in that case is an ugly hack as far as I'm concerned and will probably play havoc on the helptext.

The most realistic solution for this we can do is a pair of new commands which forward all of their options to the endpoint search and ls commands. That means setting a couple of options to forward arguments (ignore_unknown_options and allow_extra_args), and using Context.forward to pass all arguments through.
Unfortunately, the Click docs make me nervous about doing this, saying

Generally this pattern is strongly discouraged because it’s not possibly [sic] to losslessly forward all arguments

It also seems like those options might be set on the sub-context used by the new command? But it's not quite clear how context settings modified at command instantiation time get passed down, so that's not certain.
I'm also unsure about the --help output we would get in that case. Because the wrapper command doesn't do any argument processing, it should pass --help through, which might result in weird output which doesn't respect the invoking command name.

Overall, this is looking like a huge slog for something relatively minor.

[sirosen]

On a hunch, I looked at the way that the parameters themselves are stored on a command object -- as I hoped, they're just an attribute of the command.
I have a PR I'm opening now that leverages this to make aliases a new type of click.Command built off of a given target command. In my initial testing, it seems to work well.

[sirosen]

Per notes on the AliasCommand PR, marking this as blocked until we see a clear and correct path forward. Hopefully one that doesn't involve biting off completely custom helptext.

[corpulentcoffee]

See https://docs.google.com/document/d/1o4EgRsekjkmkr4LdmMY3OvEstmboE1feZyMqqtE-o2c