Hide navigation sidebar
Hide table of contents sidebar
Back to top
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).

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

Donate with PayPal

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.

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`