Define the cmd line options into groups for the help output

[KSchopmeyer]

We had discussed grouping command line options earlier in the development process sot that they were organized within groups in the help display. However, click did not offer that capability (Note: that this exists in argparse). About 6 months ago a new click contrib (click-group-options) was added to the click contrib project and that package now appears to be stable so the capability to group the command line argumetns exists for us.

This click contrib library works by installing the click-option-group package and causes no other internal changes to pywbemcli beyond changing he decorartors on the option definitions to break them into groups.

The issue for us is what is a logical set of groupings that aids our users.

[KSchopmeyer]

The following is a first attempt, just to establish that this works (I removed all but the first line of each help description). I know this is not correct but it is a starting point for discussion

DISCUSSION What are logical groups and what items should be in each group?

General Options:
  Server definition:              The alternatives for defining a server

    -n, --name NAME               Use the WBEM server defined by the WBEM

    -m, --mock-server FILE        Use a mock WBEM server that is automatically

    -s, --server URL              Use the WBEM server at the specified URL with

  Server configuration:           The options for configuring a server with --server

    -u, --user TEXT               User name for the WBEM server. Default: EnvVar

    -p, --password TEXT           Password for the WBEM server. Default: EnvVar

    --verify / --no-verify        If --verify, client verifies the X.509 server

    --ca-certs CACERTS            Certificates used to validate the certificate

    -c, --certfile FILE           Path name of a PEM file containing a X.509

    -k, --keyfile FILE            Path name of a PEM file containing a X.509

    -t, --timeout INT             Client-side timeout in seconds for operations

  Pull operation options:         Options for configuring use of pull operations
    -U, --use-pull [yes|no|either]  Determines whether pull operations are used

    --pull-max-cnt INT            Maximum number of instances to be returned by

  Configuring pywbemcli:          Setup of pywbemcli and its display, etc.
    -T, --timestats               Show time statistics of WBEM server  operations.

    -d, --default-namespace NAMESPACE Default namespace, to be used when commands do

    -o, --output-format FORMAT    Output format for the command result. The

    -l, --log COMP[=DEST[:DETAIL]],...  Enable logging of the WBEM operations, defined

    -v, --verbose / --no-verbose  Display extra information about the    processing.

    --deprecation-warnings  --no-deprecation-warnings  Enable deprecation warnings. Default: EnvVar

    -C, --connections-file FILE PATH    File path of a YAML file containing named

    --pdb                         Pause execution in the built-in pdb debugger

[KSchopmeyer]

NOTE: This code works by adding two new decorators:

@optgroup.group('Server definition',
                help='Define the server to which pywbemcli will connect')
@optgroup.option('-n', '--name', 'connection_name', type=str, metavar='NAME',

In addition it allows defining a group with characteristics, like (require one, require all, mutually exclusive, etc as an option by using subclasses of the base optgroup class.

It does not directly offer dependency functionality (allow --user only if --server is defined) and we really do not want that since we must consider not only the options on the command line but the use of general options in interactive mode.

[KSchopmeyer]

We agreed that we will:

1. Remove the pull group as separate group and put in general options.
2. change the pywbemcli configuration to general options
3. Expand wording of the descriiptions
4. Determine what additional tests we need to assure that options that do not apply from server category for example (mock) are flagged.
5. Assure that the override (ex. user with -n name works.)

[KSchopmeyer]

I overlooked the fact that this click contribution only supports python 3.6 and above, at least partly because its setup.py uses pathlib package which only supports python 3.6 and above. Writing pr to see if we can get them to expand support to match click.

Filed issue click-contrib/click-option-group#18 on click-option-group.

Next step is to create a pr with proposed fix but that takes longer.

[KSchopmeyer]

The author is willing to consider providing compatibility back to python 3.5 or maybe 3.4 if someone else does the work but clearly stated that he will not consider compatibility with python 2.7.

At this point the initial problem with python 3.5 is the use of the use of PathLib in the setup.py. We have not explored further.

I note also that the author later pretty much said he is not interested in python 3.5 compatibility, contermanding his earlier interest if I did the conversion.

[KSchopmeyer]

There is another much more limited stand-alone library that would provide the segregation of options into groups but it is not part of the click-contrib https://github.com/janLuke/cloup/blob/master/cloup/_cloup.py which accomplishes grouping but no semantic control (exclusions, etc.)

Note that there is also a very old issue in click that discussed both of the current public implementations : pallets/click#373

[andy-maier]

Since the click-option-group package only supports Python 3.6 and above, we would either have to spend the effort to backport the function to Python 3.4 and 3.5, and we would not get it into Python 2.7. I don't think this functionality is worth it to drop support for Python 2.7, or to spend the effort to backport it to Python 3.4 and 3.5.

As a result, the only option seems to be to defer this functionality until we drop these versions for other reasons.

[KSchopmeyer]

There is one alternative, a very simple proposal that would gain the grouping of the top level group but not the other features such as choice exclusion.

[KSchopmeyer]

After a review of the code in click_ tontrib option groups it is vclear that it is comppletly committed to python 3.6 + since it include all of the type hinting that started with that version.

It is a clean model in that it uses decorators for both the group and grouped option definitions:

    @optgroup('Group 1', help='option group 1')
    @optgroup.option('--foo')
    @optgroup.option('--bar')
    @optgroup.group('Group 2', help='option group 2')
    @optgroup.option('--spam')

Doing the grouping with decorators creates a complex set of code for what should be a simple problem.

Some alternate syntax's (see click issue https://github.com/pallets/click/blob/master/src/click/core.py) might be something simpler like:

@click.command()
@click.option_group('Output options:', [
    click.option('--verbose'),
    click.option('--output')
])

or

@cli.command(cls=CustomCommand)
@click.option('--option1', cls=CustomOption, help_group="Group1")
@click.option('--option2', cls=CustomOption, help_group="Group2")
@click.option('--option3', cls=CustomOption, help_group="Group1")
def mycmnd(option1):
    pass

or even

@click.command()
@click.argument('path')
@click.section('Section A', [
    click.option('--a1'),
    click.option('--a2')
])
@click.section('Section B', [
    click.option('--b1'),
    click.option('--b2')
])
def cli(path, a1, a2, b1, b2):
    pass

because in general they avoid the new decorator on the inner option definitions and depend on either explicit user of the cls option or on python grouping to group options within a group.