Cloup

3.0.9 · active · verified Sun Apr 12

Cloup — originally from 'Click + option groups' — enriches the popular Click library with several features that make command-line interfaces more expressive and configurable. These include option groups, constraints (e.g., mutually exclusive parameters), subcommand aliases, subcommand sections, and a themeable help formatter. The library, currently at version 3.0.9, is under active development, statically type-checked with MyPy, and extensively tested.

Warnings

breaking In Cloup v3.0.0, `HelpTheme` was changed from a `NamedTuple` to a `dataclass`. While the change was noted as unlikely to affect most users, it is a structural modification that could impact direct instantiation or introspection of `HelpTheme` objects.
Fix: Review any code directly interacting with `HelpTheme`'s internal structure or inheritance. Adapt to `dataclass` behavior if necessary.
breaking Cloup v3.0.6 dropped support for Python 3.7. Users on Python 3.7 must use an older version of Cloup.
Fix: Upgrade Python to 3.8 or newer, or pin Cloup to a version `<=3.0.5`.
gotcha Cloup v3.0.3 redefined `click.pass_context` and `click.get_current_context` to internally use `cloup.Context` instead of `click.Context`. Directly mixing explicit `click.Context` usage with `cloup.Context` in earlier versions could lead to unexpected behavior.
Fix: Ensure consistent use of `cloup.Context` where Cloup features are utilized, or upgrade to `cloup>=3.0.3` which aims to improve compatibility.
gotcha Prior to v3.0.9, Cloup might have triggered a `click.__version__` deprecation warning due to changes in how Click's version was accessed. This was fixed in v3.0.9.
Fix: Upgrade to Cloup v3.0.9 or newer to resolve the `click.__version__` deprecation warning.
gotcha In versions prior to 3.0.7, constraints might not have worked correctly with options that had more than two names (e.g., `--one -o --option-one`). This bug was fixed in v3.0.7.
Fix: Upgrade to Cloup v3.0.7 or newer to ensure constraints function correctly with all option name configurations.
gotcha Cloup's `Group` class (e.g., used with `@cloup.group`) does not natively support option groups or constraints by default, unlike `cloup.Command`. This is an intentional design choice for simpler groups.
Fix: If option groups or constraints are needed for a `cloup.Group`, consider using `cloup.Command` for the top-level CLI or explicitly subclass `cloup.Group` and add the necessary mixins (e.g., `OptionGroupMixin`, `ConstraintMixin`) as described in Cloup's advanced documentation.

Install

pip install cloup Install stable version

Imports

command
```
from cloup import command
```
option
```
from cloup import option
```
option_group
```
from cloup import option_group
```
HelpFormatter
```
from cloup import HelpFormatter
```
HelpTheme
```
from cloup import HelpTheme
```
Style
```
from cloup import Style
```

RequireAtLeast

from cloup.constraints import RequireAtLeast

mutually_exclusive

from cloup.constraints import mutually_exclusive

Quickstart

This quickstart demonstrates how to define a command with custom help formatting, option groups, and constraints. It uses `option_group` to logically group related options and applies `mutually_exclusive` and `RequireAtLeast` constraints.

import cloup
from cloup import command, option, option_group, HelpFormatter, HelpTheme, Style
from cloup.constraints import RequireAtLeast, mutually_exclusive

# Configure a custom help theme for better readability
formatter_settings = HelpFormatter.settings(
    theme=HelpTheme(
        invoked_command=Style(fg='bright_yellow'),
        heading=Style(fg='bright_white', bold=True),
        constraint=Style(fg='magenta'),
        col1=Style(fg='bright_yellow'),
    )
)

@command(formatter_settings=formatter_settings)
@option_group(
    "Cool options",
    option('--foo', help='This text describes the option --foo.'),
    option('--bar', help='This text describes the option --bar.'),
    constraint=mutually_exclusive,
)
@option_group(
    "Other cool options",
    "This is an optional description for this option group.",
    option('--pippo', help='This text describes the option --pippo.'),
    option('--pluto', help='This text describes the option --pluto.'),
    constraint=RequireAtLeast(1),
)
@option('--verbose', '-v', is_flag=True, help='Enable verbose output.')
def cli(foo, bar, pippo, pluto, verbose):
    """A simple CLI demonstrating Cloup's features."""
    if verbose:
        cloup.echo('Verbose mode enabled.')
    cloup.echo(f'Foo: {foo}, Bar: {bar}, Pippo: {pippo}, Pluto: {pluto}')

if __name__ == '__main__':
    cli(prog_name='my-app')

view raw JSON →