More features for Click: option groups, constraints, subcommands sections and a custom help formatter supporting themes.
Cloup (originally from: Click + option groups) extends Click with several features:
- Option groups with the
- Constraints like
RequireAtLeast(n)etc., which can be applied, even conditionally, to option groups or to any group of parameters (including positional arguments).
- Possibility to organize the subcommands of a
Groupin multiple help sections.
- A themeable HelpFormatter that:
- allows you to style several elements of the help page according to a theme
- switches to a different layout when the terminal width is small for the standard 2-column layout, so that the help page is readable in all circumstances
- has more parameters, which give you more control on the format of the help page.
Besides, Cloup is:
- type-annotated and provides additional methods so that you can always be assisted by your IDE (e.g.
Context.settings()for creating a
context_settingsdict leveraging auto-completion)
- extensively tested with multiple versions of Python and Click (see Tests)
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 would pass formatter_settings inside context_settings # so that settings 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
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.