Cloup — originally from “Click + option groups” — enriches Click with several features that make it more expressive and configurable:
option groups
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
additional parameter types, e.g. path types that use pathlib.Path instead of str by default.
command decorators with individually typed keyword arguments, plus typed helpers such as Context.settings() and HelpFormatter.settings(), for better IDE and static type checker support.
Cloup is statically type-checked with MyPy and Pyrefly and extensively tested against multiple versions of Python with nearly 100% coverage.
Does it replace Click?
Since version 4.0.0, Cloup makes an effort to re-export the public symbols in Click’s top-level namespace. Applications using Cloup can therefore access most Click functionality through cloup without maintaining separate top-level imports from both packages.
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
--plutoThis simple example just scratches the surface. Read more in the documentation (links below).
Links
Documentation (release | development)
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cloup-4.0.0.tar.gz.
File metadata
- Download URL: cloup-4.0.0.tar.gz
- Upload date:
- Size: 252.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
83b0870ee863bcc85129e40e1b208bcfdebe4cd2142e9ce1d0daf7d276cab038
|
|
| MD5 |
0b470768f4b963c0fdd753e39db87162
|
|
| BLAKE2b-256 |
05e2d41446c6195eff0db3b671ddb202e39f42f9ea7c0dd15cd43fbf5cf0d7f7
|
File details
Details for the file cloup-4.0.0-py3-none-any.whl.
File metadata
- Download URL: cloup-4.0.0-py3-none-any.whl
- Upload date:
- Size: 55.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0678744a3a2753e1d78dd3ea5c6e4cbbc3b41561fd7a7a7d075dbc8dad74f74f
|
|
| MD5 |
d9c8656bc763502981e7fce9c99d0e84
|
|
| BLAKE2b-256 |
2c3420224fd9d52e8ce7e3b319b5d6b7126da25e89d00cd1a5692b4b46ed2d26
|
