Overview¶
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 any group of parameters, even conditionallysections for subcommands, i.e. the possibility to organize the subcommands of a
Group
in multiple help sectionsa 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 small, to improve readability.
Moreover, Cloup improves on IDE support providing detailed type hints for
Click decorators and adding the static methods Context.settings()
and
HelpFormatter.settings()
for creating settings dictionaries.
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')
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!
User guide¶
Please, note that Cloup documentation doesn’t replace Click documentation.