Enriches Click with option groups, constraints, command aliases, help sections for subcommands, themes for --help and other stuff.

• cloup version: 0.7 (or latest)
• Python version: 3.7
• Operating System: OS X

Description

I am trying to create a group of options with a seemingly complex, but perhaps not, constraint system. I basically have 5 parameters that I want to house in one group, that are a combination of required and mutually exclusive, and at least x. For example, options: A, B, C, D, and E. D and E are an "all_or_none" group. C and D+E are "mutually_exclusive" group, but at least one is required. B is required with one of (C,D+E). And either A or group (B + (C or D+E)) is required. Is this possible? It's not clear to me if nested option groups are possible, i.e. if I can create one option_group with a constraint and apply a constraint on top of it as part of another option_group.

I just discovered this code and am digging into the docs, so perhaps the answer is buried in there.

something like the following...

OptionGroup(
  A,
  OptionGroup(
    B, required=True,
    OptionGroup(
      C,
      OptionGroup(
        D,
        E
        constraint=all_or_none),
    constraint=mutually_exclusive
    ),
  constraint=RequireAtLeast(1)
  ),
constraint=RequireAtLeast(1)
)

or would I do something like

OptionGroup(
  A,
  B,
  C,
  D,
  E,
  constraint="some defined complex conditional constraint"
)

This is explicitly mentioned in the documentation as not supported on purpose. But the documentation also ask for feedbacks on potential use-cases. Here is mine.

My mpm CLI has a total of 15 common options shared by 10 sub-commands. To reduce code duplication, I naturally used a cloup.group decorator, and it works great.

Now, To make things easier to apprehend to users, I'd like to group some of these common options by family. I'd like for instance to regroup --manager, --exclude, --all-managers and --xkcd options under the "Package manager selection options" banner. Unfortunately I can't because cloup.group does't support option groups.

Is this a valid case for considering adding this feature? Note that I do not need to apply any constraint (yet?), so implementation can exclude constraints.

I'd like to propose the addition of a feature that will add some configuration file loading facilities.

I developed some reusable generic code for my meta-package-manager CLI that parse a TOML file and load up its content right into the structure defined by the CLI option schema.

This code is available at: https://github.com/kdeldycke/meta-package-manager/blob/develop/meta_package_manager/config.py

With some effort I'm pretty sure it can be added as a generic feature to cloup. What's your opinion @janluke?

It would be nice to have an option to make command names and aliases case-insensitive. For now, I implemented this in my code by stealing CaseInsensitiveDict from requests, but it can probably be implemented natively without that dependency.

from requests.utils import CaseInsensitiveDict


class CaseInsensitiveGroup(cloup.Group):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.alias2name = CaseInsensitiveDict()

• cloup version: 0.7
• Python version: 3.9
• Operating System: mac arm64

Description

Dear @janLuke ,

I am currently working on a switchover for our library wetterdienst [1]. Therewith I'm currently moving our client accessor to click, however as we have certain mixing arguments for some functions I was happy to find that you are working on making this easier allowing to check for conditions. First of all thanks for your much needed work!

I'd like to add the following condition where the user can either supply rank or distance which in combination with provided longitude and latitude is used for geo filtering of some weather stations.

@cloup.option_group(
    "Latitude-Longitude rank filtering",
    cloup.option("--latitude", type=click.FLOAT),
    cloup.option("--longitude", type=click.FLOAT),
    cloup.option("--rank", type=click.INT),
    cloup.option("--distance", type=click.FLOAT),
    constraint=If(
        IsSet("latitude") & IsSet("longitude"),
        then=RequireExactly(3),
        else_=cloup.constraints.accept_none),
)

However as far as it goes it would only give me a nice help text but when running the command with arguments it ends up with

Traceback (most recent call last):
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/wetterdienst/ui/cli.py", line 736, in <module>
    wetterdienst()
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/click/core.py", line 1257, in invoke
    sub_ctx = cmd.make_context(cmd_name, args, parent=ctx)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/click/core.py", line 700, in make_context
    self.parse_args(ctx, args)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/cloup/constraints/_support.py", line 104, in parse_args
    constr.check_values(ctx)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/cloup/constraints/_support.py", line 49, in check_values
    self.constraint.check_values(self.params, ctx)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/cloup/constraints/_conditional.py", line 49, in check_values
    condition_is_true = condition(ctx)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/cloup/constraints/conditions.py", line 104, in __call__
    return all(c(ctx.params) for c in self.predicates)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/cloup/constraints/conditions.py", line 104, in <genexpr>
    return all(c(ctx.params) for c in self.predicates)
  File "/Users/benjamin/DEV/earth_observations/sources/wetterdienst/.venv/lib/python3.9/site-packages/cloup/constraints/conditions.py", line 136, in __call__
    if not isinstance(ctx.command, ConstraintMixin):
AttributeError: 'dict' object has no attribute 'command'

Is there a way to achieve what I'm planning with the current status of the library?

Again, thanks a lot for your work here! Much appreciated!

[1] https://github.com/earthobservations/wetterdienst

Edit Got it working by making the first two arguments required like

@cloup.option_group(
    "Latitude-Longitude rank filtering",
    cloup.option("--latitude", type=click.FLOAT, required=True),
    cloup.option("--longitude", type=click.FLOAT, required=True),
    cloup.option("--rank", type=click.INT),
    cloup.option("--distance", type=click.FLOAT),
    constraint=RequireExactly(3)
)

Is this the recommend way of setting the constraints?

Mypy seems to give one type-checking error (on the master branch).

cloup/_sections.py:68: error: Function "Callable[[str, Union[Iterable[Command], Dict[str, Command]]], Section]" could always be true in boolean context  [truthy-function]

This evidently arises because Section has both an instance variable named sorted (a bool) and a class method named sorted too. I very much think it would be worth renaming one of these variables, since it's only going to create confusion and type-checking complications. (You're already having to use type: ignore marker in the constructor.)

Bug description

If I create a command group that has an option group with the require_one constraint, and then add a subcommand to that group, I am unable to run --help on the subcommand without passing one of the required options at the group level.

To Reproduce

# test.py
import cloup
from cloup.constraints import require_one


@cloup.group()
@cloup.option_group(
    "credentials",
    cloup.option("--foo", help="foo"),
    cloup.option("--bar", help="bar"),
    constraint=require_one,
)
def cli(foo, bar):
    "Top level group text."


@cli.command()
def subcommand():
    """Subcommand help text."""


if __name__ == "__main__":
    cli()

python test.py subcommand --help

Expected behavior

Help text of subcommand is printed:

python test.py subcommand --help
Usage: test.py subcommand [OPTIONS]

  Subcommand help text.

Options:
  --help  Show this message and exit.

Actual behavior

An error is printed due to one of the required group options not being specified.

python test.py subcommand --help
Usage: test.py [OPTIONS] COMMAND [ARGS]...
Try 'test.py --help' for help.

Error: exactly 1 of the following parameters must be set:
  --foo
  --bar

... it's necessary to set self.chain before the rest of the code runs — otherwise you can get an error about the chain attribute not existing, in some cases.

Originally posted by @alexreg in https://github.com/janluke/cloup/pull/116#discussion_r873250465

Bug description

Mypy fails to type-check code that uses Cloup, when in strict mode. (Note, this is in contrast with Click, which Mypy has no problem with.)

To Reproduce

Steps to reproduce the behavior:

1. Install Cloup, e.g., using pip3 install cloup.
2. Create file foo.py with the following contents.

import cloup

class Context(cloup.Context):
    pass

3. Run mypy --strict foo.py.
4. Observe errors in output.5.

foo.py:4: error: Name "cloup.Context" is not defined
foo.py:4: error: Class cannot subclass "Context" (has type "Any")
Found 2 errors in 1 file (checked 1 source file)

Expected behavior

Mypy should not give any errors.

Versions

macOS 12.3.1 Python 3.9.12 Cloup 0.14.0

• Rename Argument.help_record to Argument.get_help_record, to bring the name into line with Option.get_help_record (in Click).
• Typos.
• Handle None returned by Argument.get_help_record.
• Handle case of empty sequence passed to text_rows param of HelpFormatter._get_row_sep_for.

Edited by @janluke

Thanks for this awesome package!

Bug description

I get a …

  File "cloup/_commands.py", line 87, in make_context
    self.parse_args(ctx, args)
  File "cloup/constraints/_support.py", line 178, in parse_args
    constr.check_consistency()
  File "cloup/constraints/_support.py", line 108, in check_consistency
    self.constraint.check_consistency(self.params)
AttributeError: 'AnySet' object has no attribute 'check_consistency'

… whenever I try to use the AnySet or AllSet constraint.

My env:

• Python==3.6.9
• cloup==0.14.0
• click==8.0.4 (latest for Python 3.6)

To Reproduce

Minimal example:

@cloup.constraint(
    cloup.constraints.AnySet('files1', 'filelist1'),
    ['strings1', 'files1', 'filelist1'])

What I need AnySet for:

@cloup.option('-f', '--show-files', is_flag=True, help='print file names themselves instead of indices')
@cloup.option_group(
    'list to be replaced',
    cloup.option('--strings1', cls=OptionEatAll, type=tuple, help='as strings'),
    cloup.option('--files1', cls=OptionEatAll, type=tuple, help='as file paths of strings'),
    cloup.option('--filelist1', type=cloup.File('r'), help='as text file with file paths of strings'),
    constraint=cloup.constraints.If('show_files',
                                    then=cloup.constraints.AnySet('files1', 'filelist1'),
                                    else_=cloup.constraints.require_one)
)

black is the obvious choice but I tend to dislike it, especially for CLI code, which tends to take too much vertical space when formatted with black.

The tools should be integrated with tox and github actions.

Since Click 8.1.0, we can use command and group decorators without parenthesis. See:

• https://github.com/pallets/click/pull/1896
• https://github.com/pallets/click/issues/1359

Nothing important here but a nice little nitpick. Not certain if it is worth considering for integration in cloup.

Inspired by

• https://github.com/janluke/cloup/discussions/102

In this answer, I propose a possible solution:

Give a look to this example: https://github.com/janluke/cloup/tree/lazy-loading-example/examples/lazy_loading.

The idea is that rather than extending a MultiCommand, I define proxies (LazyCommand and LazyGroup) for lazy-loaded commands. Then I use those lazy commands as if they were normal commands.

Nonetheless, I've never used lazy loading in my programs, so I'd appreciate feedback on this. Also, if you are interested in this feature, please let me know with a thumb up.

This feature can be implemented in multiple PRs but it's likely that the required changes for styling one of the elements will make easy to style the others. In that case, a single PR will probably be enough.

• [ ] metavars (including choices)
• [ ] default values
• [ ] environmnent variables.

Originally proposed in #95. Closed that one because it proposes a specific regex-based approach that I think it's not suitable for Cloup. This issue is for discussing different approaches, just in case anyone would like to.

Questions:

• is the needed work worth it or the current theming is good enough?
• given that, in theory, Click will have a new formatting system soon or later, is this the right time to implement this feature?
• wouldn't be better to change approach completely and show a web page when the user type --help and there's a browser available (similarly to git)? Command line will never be more readable :)

Cloup currently uses overloading (and a lot of ugly signature replication) to work around mypy limitations These are a couple of relevant MyPy issues that when solved may improve the situation:

• https://github.com/python/mypy/issues/3737 This would make overloading unneded

• https://github.com/python/mypy/issues/4441 This would allow me to avoid replication of kwargs annotations