Overview

Cloup (originally from: Click + option groups) extends Click with several features:

Option groups with the @option_group decorator.
Constraints like mutually_exclusive, RequireAtLeast(n) etc., which can be applied, even conditionally, to option groups or to any group of parameters (including positional arguments).
Possibility to organize the subcommands of a Group in multiple help sections.
A themeable HelpFormatter that:
- allows you to style several elements of the help page according to a theme
- switches to a different layout when the terminal width is small for the standard 2-column layout, so that the help page is readable in all circumstances
- has more parameters, which give you more control on the format of the help page.

Besides, Cloup is:

type-annotated and provides additional methods so that you can always be assisted by your IDE (e.g. Context.settings() for creating a context_settings dict leveraging auto-completion)
extensively tested with multiple versions of Python and Click (see Tests)
well-documented.

Basic 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 would pass formatter_settings inside context_settings
# so that settings 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

Supporting the project

Designing, testing and documenting a library takes a lot of time. The most concrete way to show your appreciation and to support future development is by donating. Any amount is appreciated.

Apart from that, you can help the project by starring it on GitHub, reporting issues, proposing improvements and contributing with your code!

Useful links

Metadata

Release files for cloup 0.8.1

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 0.8.1
File	Size	Uploaded
cloup-0.8.1.tar.gz	148.0 kB	May 25, 2021	Details

Built distribution (wheel)

Table of built distributions (wheels) for cloup 0.8.1
File	Interpreter	ABI	Platform	Reset
cloup-0.8.1-py2.py3-none-any.whl 36.8 kB May 25, 2021	Python 2, Python 3	none	any	Details

Total release size: 184.8 kB

Release files / cloup-0.8.1.tar.gz

Download URL	cloup-0.8.1.tar.gz
Size	148.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`aa565758489db6d25293fdf99fea9e069b0d7806a804e80e0d989997f2910db3`
BLAKE2b-256 checksum How to use checksums	`07cb60cf5307aa3a68682c4ebaa12a25e3ce38e4fba81a7d9cb75a6c6437aa87`
Upload date	May 25, 2021
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.8.2`

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

Download URL	cloup-0.8.1-py2.py3-none-any.whl
Size	36.8 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`24081f0ea3f8d7246e0bfc0c3b70f2bb270fcd65e14c519fd3c6eb3ccd65f5ef`
BLAKE2b-256 checksum How to use checksums	`efc11cc42baf5e63612977b4a90f3295ee19e157b08895a4274d27a69a0d039b`
Upload date	May 25, 2021
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.8.2`