{"id":4478,"library":"cloup","title":"Cloup","description":"Cloup — originally from 'Click + option groups' — enriches the popular Click library with several features that make command-line interfaces more expressive and configurable. These include option groups, constraints (e.g., mutually exclusive parameters), subcommand aliases, subcommand sections, and a themeable help formatter. The library, currently at version 3.0.9, is under active development, statically type-checked with MyPy, and extensively tested.","status":"active","version":"3.0.9","language":"en","source_language":"en","source_url":"https://github.com/janLuke/cloup","tags":["click","cli","command-line interface","option groups","constraints","help formatter"],"install":[{"cmd":"pip install cloup","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Cloup is an extension of Click and builds upon its core functionalities.","package":"click"}],"imports":[{"symbol":"command","correct":"from cloup import command"},{"symbol":"option","correct":"from cloup import option"},{"symbol":"option_group","correct":"from cloup import option_group"},{"symbol":"HelpFormatter","correct":"from cloup import HelpFormatter"},{"symbol":"HelpTheme","correct":"from cloup import HelpTheme"},{"symbol":"Style","correct":"from cloup import Style"},{"symbol":"RequireAtLeast","correct":"from cloup.constraints import RequireAtLeast"},{"symbol":"mutually_exclusive","correct":"from cloup.constraints import mutually_exclusive"}],"quickstart":{"code":"import cloup\nfrom cloup import command, option, option_group, HelpFormatter, HelpTheme, Style\nfrom cloup.constraints import RequireAtLeast, mutually_exclusive\n\n# Configure a custom help theme for better readability\nformatter_settings = HelpFormatter.settings(\n    theme=HelpTheme(\n        invoked_command=Style(fg='bright_yellow'),\n        heading=Style(fg='bright_white', bold=True),\n        constraint=Style(fg='magenta'),\n        col1=Style(fg='bright_yellow'),\n    )\n)\n\n@command(formatter_settings=formatter_settings)\n@option_group(\n    \"Cool options\",\n    option('--foo', help='This text describes the option --foo.'),\n    option('--bar', help='This text describes the option --bar.'),\n    constraint=mutually_exclusive,\n)\n@option_group(\n    \"Other cool options\",\n    \"This is an optional description for this option group.\",\n    option('--pippo', help='This text describes the option --pippo.'),\n    option('--pluto', help='This text describes the option --pluto.'),\n    constraint=RequireAtLeast(1),\n)\n@option('--verbose', '-v', is_flag=True, help='Enable verbose output.')\ndef cli(foo, bar, pippo, pluto, verbose):\n    \"\"\"A simple CLI demonstrating Cloup's features.\"\"\"\n    if verbose:\n        cloup.echo('Verbose mode enabled.')\n    cloup.echo(f'Foo: {foo}, Bar: {bar}, Pippo: {pippo}, Pluto: {pluto}')\n\nif __name__ == '__main__':\n    cli(prog_name='my-app')","lang":"python","description":"This quickstart demonstrates how to define a command with custom help formatting, option groups, and constraints. It uses `option_group` to logically group related options and applies `mutually_exclusive` and `RequireAtLeast` constraints."},"warnings":[{"fix":"Review any code directly interacting with `HelpTheme`'s internal structure or inheritance. Adapt to `dataclass` behavior if necessary.","message":"In Cloup v3.0.0, `HelpTheme` was changed from a `NamedTuple` to a `dataclass`. While the change was noted as unlikely to affect most users, it is a structural modification that could impact direct instantiation or introspection of `HelpTheme` objects.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade Python to 3.8 or newer, or pin Cloup to a version `<=3.0.5`.","message":"Cloup v3.0.6 dropped support for Python 3.7. Users on Python 3.7 must use an older version of Cloup.","severity":"breaking","affected_versions":">=3.0.6"},{"fix":"Ensure consistent use of `cloup.Context` where Cloup features are utilized, or upgrade to `cloup>=3.0.3` which aims to improve compatibility.","message":"Cloup v3.0.3 redefined `click.pass_context` and `click.get_current_context` to internally use `cloup.Context` instead of `click.Context`. Directly mixing explicit `click.Context` usage with `cloup.Context` in earlier versions could lead to unexpected behavior.","severity":"gotcha","affected_versions":"<3.0.3"},{"fix":"Upgrade to Cloup v3.0.9 or newer to resolve the `click.__version__` deprecation warning.","message":"Prior to v3.0.9, Cloup might have triggered a `click.__version__` deprecation warning due to changes in how Click's version was accessed. This was fixed in v3.0.9.","severity":"gotcha","affected_versions":"<3.0.9"},{"fix":"Upgrade to Cloup v3.0.7 or newer to ensure constraints function correctly with all option name configurations.","message":"In versions prior to 3.0.7, constraints might not have worked correctly with options that had more than two names (e.g., `--one -o --option-one`). This bug was fixed in v3.0.7.","severity":"gotcha","affected_versions":"<3.0.7"},{"fix":"If option groups or constraints are needed for a `cloup.Group`, consider using `cloup.Command` for the top-level CLI or explicitly subclass `cloup.Group` and add the necessary mixins (e.g., `OptionGroupMixin`, `ConstraintMixin`) as described in Cloup's advanced documentation.","message":"Cloup's `Group` class (e.g., used with `@cloup.group`) does not natively support option groups or constraints by default, unlike `cloup.Command`. This is an intentional design choice for simpler groups.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}