Implement completion of cmd line arguments and options of the command line

[KSchopmeyer]

Click provides the capability to activate shell completion for command and options in both click 7 and 8. However in click 8 the
capability was added for doing tab-completion on values of options also including files/paths, and other options where pywbemcli itself could provide the completion information. The user must add the capability to defined the tab-completion for option values and there are a couple of ways to do it in click 8:

a) adding a new attribute (shell_completion) to option definition where the value of that attribute defined a completion option for the option.
b) Create a custom ParamType for the option/argument for which custom value tab-completion is to be used.

See https://click.palletsprojects.com/en/8.1.x/shell-completion/

Click provides the capability to activate shell completion for command and options in both click 7 and 8. However in click 8 the
capability was added for doing tab-completion on values of options also including files/paths, and other options where pywbemcli itself could provide the completion information. The user must add the capability to defined the tab-completion for option values and there are a couple of ways to do it in click 8:

a) adding a new attribute (shell_completion) to option definition where the value of that attribute defined a completion option for the option.
b) Create a custom ParamType for the option/argument for which custom value tab-completion is to be used.

See https://click.palletsprojects.com/en/8.1.x/shell-completion/

The immediate goal is to implement tab completion for those option values that where the data is available locally such as choice options, the --name options, any options that access files or paths. Options that access the server itself will require that we find ways to cache information from the server and access the cached information locally and are beyond the current scope.

[KSchopmeyer]

Disussed and if it goes to a server it is beyond autocomplete. Thus pywbemcli --name could autocomplete ut not pywbemcli class get. For the class get we can use the .? wildcard. I think this means that the only real autocomplete is the --name option.

[andy-maier]

The directions issue #582 for 0.7.0 defines this as a prio 1 item for 0.7.0.

[andy-maier]

We agreed to lower the priority of this one to no longer be prio 1 in the directions issue.

[andy-maier]

Moved to 0.8.0.

[KSchopmeyer]

Karl needs to define the alternatives for tab completion and our ? selection to decide if we should use both concepts, or select one.

We noted that autocompletion does not exist on shells like cmd.exe. We may not be able to do much with the shell mode with cmd.exe because there is no support for any auto-completion except for file names. And there is no mechanism to extend the cmd.exe auto-completion (ex. bash allows defining new auto-autocompletion with a script and env variable)

We could tab on those things that we already use tabs for (commands, subcommands, option names) that are are supported by by the interactive mode using click.

RESPONSE/KS: Yes we need both capabilities since we do not plan to build capabilities to access a server into the shell tab-completion at this point. This is made even more complex in that doing completion on functionality like namespaces or the instancename will require that we set clear ordering requirements on the options themselves. Thus, for example it would not make sense to to tab completion on the the instancename argument in instance get without already having the namespace itself defined on the command name or part of the instancename. Finally, further we made the ? completion different from what is the norm for tab-completion in that it is a GLOB, not a starts-with type of completion.

CONCLUSION: KS - I think that the only possible change to cover this question would be to extend documentation so users understand the difference. We should be sure that these GLOB base completions are clearly documented as different from the tab-completion that will be part of the comand an interactive mode tabe-completion.

[KSchopmeyer]

For the initial release of any tab-completion the following are out of scope KS

List of places in pywbemcli that are logical for auto/wildcard completion.

1. Command line options
   a. --name - the data for this is available in the connection repository. This is a frequently used option so that it would be a significant user advantage and the data is local (except for any issue of the --connection-file) which modifies the location to be searched.

2. Class, instance, qualifier groups
   a. Arguments - The name of the object for the Get. (CLASSNAME, INSTANCENAME, QUALIFIERNAME Currently this is wildcarded only for the instance operations such as instance get, and instance associators. The information to auto/complete/wildcard these items is avaiable from the server. However, the choice is dependent on options for the same command, in particular, the --namespace. So pywbemcli has to know the target namespace before it can get the information. Also, getting this informtion from the server can be expensive in time. Finally, the set of information can be very large. For example, it for the CLASSNAME argument it could be a list of hundreds of names which is probably to much for a tab-autocomplete to be really useful.

   b. Options - Here is a list of possible candidates for use of the ? selector (i.e. what we call wildcard). I have not put much thought into which ones make sense in terms of implementability or real advantage to the user yet.
   i. --namespace option - This could be used to allow the user to select a particular namespace. In this case the current
   wildcard could be used ( ex. --namespace ?) would produce a select list of namespaces.
   ii. --propertylist
   iii. --resultclass and --assocclass
   iv. -- role and result role
   v. --profile, --organization
   vi. --query-language
   vi. --central-class, --scoping-class

[KSchopmeyer]

The click project is in process of a major rework of the click-auto-complete components. (see click issue #1484 and a corresponding pr in progress). We do not have a date but I would argue that any work we do on expanding auto-complete (i.e. tab-completion completion) would probably be wasted. There goals appear to be 1) rewrite the code base to make it more comphrehensible and adapt to more platforms including powershell, 2 implement more type based auto-complete (specifically file and path based tab completion) 3. apparently implement a means to offer completion tied to particular options, etc.

In light of that I propose that it is not worthwhile for us to tackle anything involving tab-based auto-completion (ex. use the click completion contribution library) until the click work settles down. Sadly we don't have any idea how long that will be.

Thus, if we were to consider our wildcard (? / select) based completion for specific options and arguments that would be logical however. But first we must define whether we want to use that means of auto-complete.

[KSchopmeyer]

We agreed to put anything involving tab completion off pending better understanding of where click is going.

[KSchopmeyer]

It is now clear that the update to click for auto-completion is primarily about:

1. Integrating auto-completion (now called tab-complete) for a number of shells (the earlier code was built around bash and sort of hacked to support fish, etc. It never did and doesn't support powershell.

2. The functionality of autocomplete for files and directories specifically

3. Extensionability of autocomplete to allow other types of data (i.e. option values and argumente values) to be included in the tab-complete definition where the option/argument is extended with a new attribute (shell_completion which defined a completer function that used the incomplete string supplied to it to attempt to return one or more completion possibilities) . I assume that this means we could include, for example) the list of connection names so that they could be chosen by tabbing.

However:

1. this is part of click 8.0. This version will NOT support python 2.7 and no statement made about python 2.4 or 3.5.

2. This may well completely break or bypass the current click contrib https://github.com/click-contrib/click-completion

[KSchopmeyer]

DISCUSSION: Where should we go and what kind of deadlines should we set with respect to supporting:

1. python 2.7

2. python 3.4 and 3.5

Setting our goals and the external forces that are driving those goals (ex. pip and python 2.7) will help us understand what paths we should take in satisfying some of the items we want to accomplish but that are limited by python versions.

Curently we have issues with:

1. The next major version of click

2. The option for grouping: click-contrib https://github.com/click-contrib/click-completion which is appears is not interested in supporting anything less thatn python 3.6 (See Andy issue in that github repo and my earlier one)

3. pip.

[andy-maier]

Proposal:

• On Python 2, stay on click<8.0 and do not provide auto-complete.
• On Python 3, use click>=8.0 and utilize its auto-complete.

The key question is can this be done without getting crazy with version dependencies in our code.

[KSchopmeyer]

This is tied to the the use of click 8 so we cannot do this until we can use click 8 (see issue # 819). Remove target release

[KSchopmeyer]

This is partly duplicated in issue #1158 that sets requirement for documenting and adding support for autocomete on the cmd line. I suggest that I combine the two issues more logically so that one covers basic implementation of the addons and documentation of autocompete on the cmd line (#1158) and that this one cover just issues around extending how autocomplete is used for getting option and parameter/option values since the concept of auto-complete for parameters values was added in click 8.0

[KSchopmeyer]

DISCUSSION This was completed with PR #1247 and PR # 1278. I propose that merging PR #1278 should complete this issue.

The only change proposed is to review the docs to be sure we separate our ? * based GLOB wildcard from tab-completion provided by the shell, click, and click-repl