Overview

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

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!

Thanks

JetBrains logo

A big thank to JetBrains for providing me with a free license for their IDEs. If you’re developing a non-commercial open-source project, you may consider applying for a free license too. You find all details at this link. Note that this license can be used only to develop non-commercial projects.

Metadata

Release files for cloup 2.1.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 2.1.1
File	Size	Uploaded
cloup-2.1.1.tar.gz	225.0 kB	Jun 3, 2023	Details

Built distribution (wheel)

Table of built distributions (wheels) for cloup 2.1.1
File	Interpreter	ABI	Platform	Reset
cloup-2.1.1-py2.py3-none-any.whl 53.9 kB Jun 3, 2023	Python 3, Python 2	none	any	Details

Total release size: 278.9 kB

Release files / cloup-2.1.1.tar.gz

Download URL	cloup-2.1.1.tar.gz
Size	225.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`bbfe11686334309b3fbe876af7db9bc265d4eaea93b562fd13472767af648615`
BLAKE2b-256 checksum How to use checksums	`5bba8506757f2d6096ad3d23e4ee7a428ca468f0b72ec8b1741ff8f1f25484e3`
Upload date	Jun 3, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.9.16`

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

Download URL	cloup-2.1.1-py2.py3-none-any.whl
Size	53.9 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`09084e54b3397d31171d6b0a5dac00e676eb0718e59251030a5b4afc19c013e3`
BLAKE2b-256 checksum How to use checksums	`40d5f632981e03444251c2f50e48cd0e478366dcd10c01f97c9d45b2aa1c8e42`
Upload date	Jun 3, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.2 CPython/3.9.16`