Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

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

## User guide

Please, note that Cloup documentation doesn’t replace Click documentation.

User guide

- Installation
  - Depending on Cloup: recommendations
- Arguments with `help`
- Option groups
  - The @option_group decorator
  - Aligned vs non-aligned groups
  - Alternative APIs
  - Reusing/modularizing option groups
  - How it works
  - Feature support
- Constraints
  - Overview
  - Implemented constraints
  - Applying constraints
  - Rephrasing constraints
  - Defining new constraints
  - *Validation protocol
  - *Feature support
- Subcommand aliases
  - Usage
  - Help output of the group
  - Help output of the subcommand
- Subcommand sections
  - Adding full sections
  - Adding subcommands one at a time
- Help formatting and themes
  - Formatting settings
  - Themes
  - Row separators
  - The linear layout for definition lists
  - Minor differences with Click
- Miscellaneous
  - Shortcuts for creating `click.Path`