cloup

Cloup — originally from “Click + option groups” — enriches Click with several features that make it more expressive and configurable:

option groups and an (optional) help section for positional arguments
constraints, like mutually_exclusive, that can be applied to option groups or to any group of parameters, even conditionally
subcommand aliases
subcommands sections, i.e. the possibility of organizing the subcommands of a Group in multiple help sections
a themeable HelpFormatter that:
- has more parameters for adjusting widths and spacing, which can be provided at the context and command level
- use a different layout when the terminal width is below a certain threshold in order to improve readability
suggestions like “did you mean <subcommand>?” when you mistype a subcommand.

Moreover, Cloup improves on IDE support providing decorators with detailed type hints and adding the static methods Context.settings() and HelpFormatter.settings() for creating dictionaries of settings.

Cloup is statically type-checked with MyPy in strict mode and extensively tested against multiple versions of Python with nearly 100% coverage.

A simple example

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

# Check the docs for all available arguments of HelpFormatter and HelpTheme.
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'),
    )
)

# In a multi-command app, you can pass formatter_settings as part
# of your context_settings so that they are propagated to subcommands.
@command(formatter_settings=formatter_settings)
@option_group(
    "Cool options",
    option('--foo', help='This text should describe the option --foo.'),
    option('--bar', help='This text should describe the option --bar.'),
    constraint=mutually_exclusive,
)
@option_group(
    "Other cool options",
    "This is the optional description of this option group.",
    option('--pippo', help='This text should describe the option --pippo.'),
    option('--pluto', help='This text should describe the option --pluto.'),
    constraint=RequireAtLeast(1),
)
def cmd(**kwargs):
    """This is the command description."""
    pass

if __name__ == '__main__':
    cmd(prog_name='invoked-command')

If you don’t provide --pippo or --pluto:

Usage: invoked-command [OPTIONS]
Try 'invoked-command --help' for help.

Error: at least 1 of the following parameters must be set:
  --pippo
  --pluto

This simple example just scratches the surface. Read more in the documentation (links below).

Metadata

Release files for cloup 3.0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cloup 3.0.6
File	Size	Uploaded
cloup-3.0.6.tar.gz	229.3 kB	Feb 20, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for cloup 3.0.6
File	Interpreter	ABI	Platform	Reset
cloup-3.0.6-py2.py3-none-any.whl 54.4 kB Feb 20, 2025	Python 2, Python 3	none	any	Details

Total release size: 283.8 kB

Release files / cloup-3.0.6.tar.gz

Download URL	cloup-3.0.6.tar.gz
Size	229.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`7a43e1b611b9f1e9cb3e1e0e02247154cb530df3d909fa184e377cdee6834b98`
BLAKE2b-256 checksum How to use checksums	`48598d1b7913dd0a4df06b864455db59da53bcc6cc99f14b84f486c170e29029`
Upload date	Feb 20, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Release files / cloup-3.0.6-py2.py3-none-any.whl

Download URL	cloup-3.0.6-py2.py3-none-any.whl
Size	54.4 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`ce46566204318e32b3e02d97d5e89bcaa9d9c3d0b8f94d1d060bc8b7a6be9179`
BLAKE2b-256 checksum How to use checksums	`96dfcce3c4b562845db6741abb520619a8b38d817a3ab4b82f2b6df3be7a7dfc`
Upload date	Feb 20, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.9`