Skip to main content

Adds features to Click: option groups, constraints, subcommand sections and help themes.

Project description

Latest release on PyPI Supported versions Tests status Coverage Status Documentation Status (master branch) Donate with PayPal

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 to organize 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 extensively tested and documented. Tests are run against multiple versions of Python (>=3.6) and Click (>=7.2).

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')
Basic example --help screenshot

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).

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.

Donate with PayPal

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cloup-0.14.0.tar.gz (222.8 kB view hashes)

Uploaded source

Built Distribution

cloup-0.14.0-py2.py3-none-any.whl (52.3 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page