Constraints on parameters that have identical "internal" names

[Mitmischer]

Hello,
not sure if that is a feature request or if it already exists, so I'm starting it as discussion :)
Consider the following minimal example:

import cloup
import cloup.constraints

@cloup.command()
@cloup.option_group(
    "group",
    cloup.option("--a", "a"),
    cloup.option("--b", "a"),
    constraint=cloup.constraints.mutually_exclusive
)
def main(**kw):
    pass

(As it is, the CLI does not make sense. My use case is that a should contain a list of files, but the user may also specify a folder. In that case, I'll convert the folder content to a list of files. I'd personally prefer two parameters, but I'm moving from an argparse CLI to click and I want to keep changes minimal in order to sell it)

Running the example gives the following error ...

python3 main.py --a "hello"
Usage: main.py [OPTIONS]
Try 'main.py --help' for help.

Error: the following parameters are mutually exclusive:
  --a
  --b

... which is not surprising if arguments are found by name. Are there plans to get this (corner case) into cloup?

[janluke]

Hi there,
this is a limitation that has to do with how Click handles flags with the same "destination name", i.e. feature switches. The information about which specific flag was provided is lost after parsing. I have no time now for a longer answer. I will convert this discussion to an issue.

[janluke]

Cloup could introduce its own way to map different options to the same "destination name" without rewriting Click parsing. The idea is to use options with different names internally and then doing the "option to name" mapping at the end, just before providing values to the command function. I've to decide if this is clean and worth it.

My use case is that a should contain a list of files, but the user may also specify a folder. In that case, I'll convert the folder content to a list of files. I'd personally prefer two parameters, but I'm moving from an argparse CLI to click and I want to keep changes minimal in order to sell it

Using a single internal name is irrelevant with respect to making a change easier to digest. The CLI change is in using two parameters instead of one; using one or two internal names is an implementation detail, invisible to the user. For now, you could just use different internal names, let Cloup enforcing the mutually exclusiveness of the two parameters and finally post-process the two arguments to get a list of file in your command function.

If it makes sense, I'd also consider the option of having a single parameter accepting a list of paths, allowing both file and folder paths to be passed together. Then I'd just "expand" folder paths into list of files.

(Note that Click doesn't allow an option to take an arbitrary number of values, only positional arguments can.)

Hope this helps.

[janluke]

I realized I misinterpreted the following text in my previous answer:

I'd personally prefer two parameters, but I'm moving from an argparse CLI to click and I want to keep changes minimal in order to sell it

So you already have two different parameters mapped to the same destination name in argparse and you want to keep this as it is. My answer doesn't change much: my suggestions is to map the two options to two different names or to use a single option as I explained in my previous answer if it makes sense. In other words: don't use the same name for two different options, even if related.

In my opinion, the only legit usage of multiple options with the same name is that of Click's "feature switches", i.e. flags. I may decide to support mutually exclusive feature switches in the future. I'm not going to encourage the pattern of mapping different options to the same name instead.

[Smattacus]

Hi @janluke, attaching to this discussion since I have a similar use case. My use case comes around from how I am using callbacks to get objects that match an API. An example:

class OptionAction(ABC):
    pass

class FooOptionAction(OptionAction):
    pass

class BarOptionAction(OptionAction):
    pass

@option_group(
    "Cool options",
    option('--foo', help='This text should describe the option --foo.', callback=OptionActionBuilder),
    option('--bar', help='This text should describe the option --bar.', callback=OptionActionBuilder),
    constraint=mutually_exclusive,
)
def cmd(foo: FooOptionAction, bar: BarOptionAction):
    print(kwargs)
    if foo:
        action = foo
    elif bar:
        action = bar
    else:
        action = None
    BusinessLogic(action)

Both of my options are used to construct an instance of a subclasses of this ABC. This means that the object that comes from the callback, by the Liskov substitution principle, I can just plug into my business logic. This means that if I'm able to map these options down to a single parameter in cmd, I have a way I can completely remove the need for a one hot. Here's a proposal spec:

@option_group(
    "Cool options",
    option('--foo', help='This text should describe the option --foo.', callback=OptionActionBuilder),
    option('--bar', help='This text should describe the option --bar.', callback=OptionActionBuilder),
    constraint=mutually_exclusive,
    param_name="baz"    
)
def cmd(baz: OptionAction):
    print(kwargs)
    BusinessLogic(bar)  #LSP

Now, all I have to do is test my callback factory and my classes that implement OptionAction and my cli (and its tests) remains tiny. Great!

This is useful because I have created CLIs where there a mutex option group grows because it's become a heavy use point for users.

I actually sat down to create a click extension for this, but researching it I realized it may make more sense here. (Or maybe both!) I would love to contribute a PR to address this. I'm a little unsure where to start since I'm just a user of click, with some custom classes on Options. What methods would you point to to override this?