Skip to main content

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

Project description

Latest release on PyPI PyPI - Downloads Tests status Coverage Status Documentation Status (master branch)

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

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-3.0.7.tar.gz (229.6 kB view details)

Uploaded Source

Built Distribution

cloup-3.0.7-py2.py3-none-any.whl (54.6 kB view details)

Uploaded Python 2Python 3

File details

Details for the file cloup-3.0.7.tar.gz.

File metadata

  • Download URL: cloup-3.0.7.tar.gz
  • Upload date:
  • Size: 229.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for cloup-3.0.7.tar.gz
Algorithm Hash digest
SHA256 c852e0a0541aa433c6ab31a9b8b503f63d9881e91ddaf0384d6927965f2b421c
MD5 e703235f3346de134991960868eeba7b
BLAKE2b-256 86c93c621e0b7898403556e807244104095df1132a6094384f80c272bba4e4e4

See more details on using hashes here.

File details

Details for the file cloup-3.0.7-py2.py3-none-any.whl.

File metadata

  • Download URL: cloup-3.0.7-py2.py3-none-any.whl
  • Upload date:
  • Size: 54.6 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for cloup-3.0.7-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 d3a431cf1e14d8835fe85608e02cc6ff7216f0a39e30d5e28618aa938003ddb4
MD5 f716d076ff901e6c0bfbbb553dfc028f
BLAKE2b-256 452eccd754e473b972155f7e8ca60af373a8bc13ae951a5cb76363c43363e69d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page