Overview¶
Development |
|
Latest release |
|
Cloup [originally from: Click + option groups] is a library that
extends Click with several features
– most notably, option groups – sharing the common goal of improving the
readability and customizability of the command --help.
Features¶
Option groups: use the
@option_groupdecorator to define option groups..Group constraints: apply constraints (even conditionally) to option groups or to any group of parameters (including positional arguments). Available constraints include:
mutually_exclusive,RequireAtLeast(n),AcceptAtMost(n)etc.Help sections for subcommands: organize the subcommands of a
Groupin multiple help sections.A themeable HelpFormatter that:
allows you to style several elements of the
--helpaccording to a themehas more parameters that you can change per-context and per-command
switches to a different layout when the terminal width is small for the standard 2-column layout, so that the
--helpis readable in all circumstances.
Moreover, Cloup is:
type-annotated and provides additional methods so that you can always be assisted by your IDE (e.g.
Context.settings()for creating acontext_settingsdict leveraging auto-completion)extensively tested with multiple versions of Python and Click (see Tests)
well-documented.
Basic example¶
from cloup import Context, HelpFormatter, HelpTheme, command, option, option_group
from cloup.constraints import RequireAtLeast, mutually_exclusive
SETTINGS = Context.settings(
formatter_settings=HelpFormatter.settings(
theme=HelpTheme.dark()
)
)
@command(context_settings=SETTINGS, no_args_is_help=True)
@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')
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.