Skip to content
Back to top
View this page

# `cloup`

Top-level package for cloup.

## Subpackages

- constraints
  - common
  - conditions
  - exceptions
- formatting
  - sep

## Submodules

- styling
- types
- typing
- warnings

## Classes

`HelpTheme`([invoked_command, command_help, ...]) | A collection of styles for several elements of the help page.
`Style`([fg, bg, bold, dim, underline, ...]) | Wraps `click.style()` for a better integration with `HelpTheme`.
`Color`() | Colors accepted by `Style` and `click.style()`.
`HelpFormatter`([indent_increment, width, ...]) | A custom help formatter.
`HelpSection`(heading, definitions[, help, ...]) | A container for a help section data.
`Context`(*ctx_args[, align_option_groups, ...]) | A custom context for Cloup.
`Argument`(*args[, help]) | A `click.Argument` with help text.
`Option`(*args[, group]) | A `click.Option` with an extra field `group` of type `OptionGroup`.
`OptionGroup`(title[, help, constraint, hidden]) | Contains the information of an option group and identifies it.
`OptionGroupMixin`(*args[, align_option_groups]) | Implements support for:
`Section`(title[, commands, is_sorted]) | A group of (sub)commands to show in the same help section of a `MultiCommand`.
`SectionMixin`(*args[, commands, sections, ...]) | Adds to a `click.MultiCommand` the possibility of organizing its subcommands into multiple help sections.
`Command`(*args[, aliases, formatter_settings]) | A `click.Command` supporting option groups and constraints.
`Group`(*args[, show_subcommand_aliases, commands]) | A `click.Group` that allows to organize its subcommands in multiple help sections and whose subcommands are, by default, of type `cloup.Command`.
`ConstraintMixin`(*args[, constraints, ...]) | Provides support for constraints.

## Functions

`get_current_context`() | Equivalent to `click.get_current_context()` but casts the returned `click.Context` object to `cloup.Context` (which is safe when using cloup commands classes and decorators).
`pass_context`(f) | Marks a callback as wanting to receive the current context object as first argument.
`argument`(*param_decls[, cls]) |
`option`(*param_decls[, cls, group]) | Attach an `Option` to the command.
`option_group`() | Return a decorator that annotates a function with an option group.
`command`() | Return a decorator that creates a new command using the decorated function as callback.
`group`([align_sections, ...]) | Return a decorator that instantiates a `Group` (or a subclass of it) using the decorated function as callback.
`constrained_params`(constr, *param_adders) | Return a decorator that adds the given parameters and applies a constraint to them. Equivalent to::.
`constraint`(constr, params) | Register a constraint on a list of parameters specified by (destination) name (e.g. the default name of `--input-file` is `input_file`).
`dir_path`(*[, path_type, exists, readable, ...]) | Shortcut for `click.Path` with `file_okay=False, path_type=pathlib.Path`.
`file_path`(*[, path_type, exists, readable, ...]) | Shortcut for `click.Path` with `dir_okay=False, path_type=pathlib.Path`.
`path`(*[, path_type, exists, file_okay, ...]) | Shortcut for `click.Path` with `path_type=pathlib.Path`.

## Contents

class cloup.HelpTheme

  A collection of styles for several elements of the help page.

  A “style” is just a function or a callable that takes a string and returns a styled version of it. This means you can use your favorite styling/color library (like rich, colorful etc). Nonetheless, given that Click has some basic styling functionality built-in, Cloup provides the `Style` class, which is a wrapper of the `click.style` function.

  Parameters:

    - invoked_command (Callable[[str], str]) – Style of the invoked command name (in Usage).

    - command_help (Callable[[str], str]) – Style of the invoked command description (below Usage).

    - heading (Callable[[str], str]) – Style of help section headings.

    - constraint (Callable[[str], str]) – Style of an option group constraint description.

    - section_help (Callable[[str], str]) – Style of the help text of a section (the optional paragraph below the heading).

    - col1 (Callable[[str], str]) – Style of the first column of a definition list (options and command names).

    - col2 (Callable[[str], str]) – Style of the second column of a definition list (help text).

    - epilog (Callable[[str], str]) – Style of the epilog.

    - alias (Callable[[str], str]) – Style of subcommand aliases in a definition lists.

    - alias_secondary (Callable[[str], str] | None) – Style of separator and eventual parenthesis/brackets in subcommand alias lists. If not provided, the `alias` style will be used.

  invoked_command: IStyle

    Style of the invoked command name (in Usage).

  command_help: IStyle

    Style of the invoked command description (below Usage).

  heading: IStyle

    Style of help section headings.

  constraint: IStyle

    Style of an option group constraint description.

  section_help: IStyle

    Style of the help text of a section (the optional paragraph below the heading).

  col1: IStyle

    Style of the first column of a definition list (options and command names).

  col2: IStyle

    Style of the second column of a definition list (help text).

  alias: IStyle

    Style of subcommand aliases in a definition lists.

  alias_secondary: IStyle | None = None

    Style of separator and eventual parenthesis/brackets in subcommand alias lists. If not provided, the `alias` style will be used.

  epilog: IStyle

    Style of the epilog.

  with_(invoked_command=None, command_help=None, heading=None, constraint=None, section_help=None, col1=None, col2=None, alias=None, alias_secondary=MISSING, epilog=None)
    Parameters:

      - invoked_command (Optional[IStyle])

      - command_help (Optional[IStyle])

      - heading (Optional[IStyle])

      - constraint (Optional[IStyle])

      - section_help (Optional[IStyle])

      - col1 (Optional[IStyle])

      - col2 (Optional[IStyle])

      - alias (Optional[IStyle])

      - alias_secondary (cloup.typing.Possibly[Optional[IStyle]])

      - epilog (Optional[IStyle])

    Return type:

      HelpTheme

  static dark()

    A theme assuming a dark terminal background color.

    Return type:

      HelpTheme

  static light()

    A theme assuming a light terminal background color.

    Return type:

      HelpTheme

class cloup.Style

  Wraps `click.style()` for a better integration with `HelpTheme`.

  Available colors are defined as static constants in `Color`.

  Arguments are set to `None` by default. Passing `False` to boolean args or `Color.reset` as color causes a reset code to be inserted.

  With respect to `click.style()`, this class:

  - has an argument less, `reset`, which is always `True`

  - add the `text_transform`.

  Warning

  The arguments `overline`, `italic` and `strikethrough` are only supported in Click 8 and will be ignored if you are using Click 7.

  Parameters:

    - fg (str | None) – foreground color

    - bg (str | None) – background color

    - bold (bool | None)

    - dim (bool | None)

    - underline (bool | None)

    - overline (bool | None)

    - italic (bool | None)

    - blink (bool | None)

    - reverse (bool | None)

    - strikethrough (bool | None)

    - text_transform (Callable[[str], str] | None) – a generic string transformation; useful to apply functions like `str.upper`

  Added in version 0.8.0.

  fg: str | None = None
  bg: str | None = None
  bold: bool | None = None
  dim: bool | None = None
  underline: bool | None = None
  overline: bool | None = None
  italic: bool | None = None
  blink: bool | None = None
  reverse: bool | None = None
  strikethrough: bool | None = None
  text_transform: IStyle | None = None
  __call__(text)
    Parameters:

      text (str)

    Return type:

      str

class cloup.Color

  Bases: `cloup._util.FrozenSpace`

  Colors accepted by `Style` and `click.style()`.

  black = 'black'
  red = 'red'
  green = 'green'
  yellow = 'yellow'
  blue = 'blue'
  magenta = 'magenta'
  cyan = 'cyan'
  white = 'white'
  reset = 'reset'
  bright_black = 'bright_black'
  bright_red = 'bright_red'
  bright_green = 'bright_green'
  bright_yellow = 'bright_yellow'
  bright_blue = 'bright_blue'
  bright_magenta = 'bright_magenta'
  bright_cyan = 'bright_cyan'
  bright_white = 'bright_white'

class cloup.HelpFormatter(indent_increment=2, width=None, max_width=None, col1_max_width=30, col2_min_width=35, col_spacing=2, row_sep=None, theme=HelpTheme())

  Bases: `click.HelpFormatter`

  A custom help formatter. Features include:

  - more attributes for controlling the output of the formatter

  - a `col1_width` parameter in `write_dl()` that allows Cloup to align multiple definition lists without resorting to hacks

  - a “linear layout” for definition lists that kicks in when the available terminal width is not enough for the standard 2-column layout (see argument `col2_min_width`)

  - the first column width, when not explicitly given in `write_dl` is computed excluding the rows that exceed `col1_max_width` (called `col_max` in `write_dl` for compatibility with Click).

  Changed in version 0.9.0: the `row_sep` parameter now:

  - is set to `None` by default and `row_sep=""` corresponds to an empty line between rows

  - must not ends with `\n`; the formatter writes a newline just after it (when it’s not `None`), so a newline at the end is always enforced

  - accepts instances of `SepGenerator` and `RowSepPolicy`.

  Added in version 0.8.0.

  Parameters:

    - indent_increment (int) – width of each indentation increment.

    - width (int | None) – content line width, excluding the newline character; by default it’s initialized to `min(terminal_width - 1, max_width)` where `max_width` is another argument.

    - max_width (int | None) – maximum content line width (equivalent to `Context.max_content_width`). Used to compute `width` when it is not provided, ignored otherwise.

    - col1_max_width (int) – the maximum width of the first column of a definition list; as in Click, if the text of a row exceeds this threshold, the 2nd column is printed on a new line.

    - col2_min_width (int) – the minimum width for the second column of a definition list; if the available space is less than this value, the formatter switches from the standard 2-column layout to the “linear layout” (that this decision is taken for each definition list). If you want to always use the linear layout, you can set this argument to a very high number (or `math.inf`). If you never want it (not recommended), you can set this argument to zero.

    - col_spacing (int) – the number of spaces between the column boundaries of a definition list.

    - row_sep (None | str | SepGenerator | RowSepPolicy) – an “extra” separator to insert between the rows of a definition list (in addition to the normal newline between definitions). If you want an empty line between rows, pass `row_sep=""`. Read Row separators for more.

    - theme (HelpTheme) – an `HelpTheme` instance specifying how to style the various elements of the help page.

  width: int
  col1_max_width = 30
  col2_min_width = 35
  col_spacing = 2
  theme
  row_sep = None
  static settings(*, width=MISSING, max_width=MISSING, indent_increment=MISSING, col1_max_width=MISSING, col2_min_width=MISSING, col_spacing=MISSING, row_sep=MISSING, theme=MISSING)

    A utility method for creating a `formatter_settings` dictionary to pass as context settings or command attribute. This method exists for one only reason: it enables auto-complete for formatter options, thus improving the developer experience.

    Parameters are described in `HelpFormatter`.

    Parameters:

      - width (cloup.typing.Possibly[Optional[int]])

      - max_width (cloup.typing.Possibly[Optional[int]])

      - indent_increment (cloup.typing.Possibly[int])

      - col1_max_width (cloup.typing.Possibly[int])

      - col2_min_width (cloup.typing.Possibly[int])

      - col_spacing (cloup.typing.Possibly[int])

      - row_sep (cloup.typing.Possibly[Union[None, str, cloup.formatting.sep.SepGenerator, cloup.formatting.sep.RowSepPolicy]])

      - theme (cloup.typing.Possibly[cloup.styling.HelpTheme])

    Return type:

      Dict[str, Any]

  property available_width: int
    Return type:

      int

  write(*strings)

    Writes a unicode string into the internal buffer.

    Parameters:

      strings (str)

    Return type:

      None

  write_usage(prog, args='', prefix=None)

    Writes a usage line into the buffer.

    Parameters:

      - prog (str) – the program name.

      - args (str) – whitespace separated list of arguments.

      - prefix (Optional[str]) – The prefix for the first line. Defaults to `"Usage: "`.

    Return type:

      None

  write_aliases(aliases)
    Parameters:

      aliases (Sequence[str])

    Return type:

      None

  write_command_help_text(cmd)
    Parameters:

      cmd (click.Command)

    Return type:

      None

  write_heading(heading, newline=True)

    Writes a heading into the buffer.

    Parameters:

      - heading (str)

      - newline (bool)

    Return type:

      None

  write_many_sections(sections, aligned=True)
    Parameters:

      - sections (Sequence[HelpSection])

      - aligned (bool)

    Return type:

      None

  write_aligned_sections(sections)

    Write multiple aligned definition lists.

    Parameters:

      sections (Sequence[HelpSection])

    Return type:

      None

  write_section(s, col1_width=None)
    Parameters:

      - s (HelpSection)

      - col1_width (Optional[int])

    Return type:

      None

  write_text(text, style=identity)

    Writes re-indented text into the buffer. This rewraps and preserves paragraphs.

    Parameters:

      - text (str)

      - style (cloup.styling.IStyle)

    Return type:

      None

  compute_col1_width(rows, max_width)
    Parameters:

      - rows (Iterable[Definition])

      - max_width (int)

    Return type:

      int

  write_dl(rows, col_max=None, col_spacing=None, col1_width=None)

    Write a definition list into the buffer. This is how options and commands are usually formatted.

    If there’s enough space, definition lists are rendered as a 2-column pseudo-table: if the first column text of a row doesn’t fit in the provided/computed `col1_width`, the 2nd column is printed on the following line.

    If the available space for the 2nd column is below `self.col2_min_width`, the 2nd “column” is always printed below the 1st, indented with a minimum of 3 spaces (or one `indent_increment` if that’s greater than 3).

    Parameters:

      - rows (Sequence[Definition]) – a list of two item tuples for the terms and values.

      - col_max (Optional[int]) – the maximum width for the 1st column of a definition list; this argument is here to not break compatibility with Click; if provided, it overrides the attribute `self.col1_max_width`.

      - col_spacing (Optional[int]) – number of spaces between the first and second column; this argument is here to not break compatibility with Click; if provided, it overrides `self.col_spacing`.

      - col1_width (Optional[int]) – the width to use for the first column; if not provided, it’s computed as the length of the longest string under `self.col1_max_width`; useful when you need to align multiple definition lists.

    Return type:

      None

  write_tabular_dl(rows, col1_width, col_spacing, col2_width)

    Format a definition list as a 2-column “pseudo-table”. If the first column of a row exceeds `col1_width`, the 2nd column is written on the subsequent line. This is the standard way of formatting definition lists and it’s the default if there’s enough space.

    Parameters:

      - rows (Sequence[Definition])

      - col1_width (int)

      - col_spacing (int)

      - col2_width (int)

    Return type:

      None

  write_linear_dl(dl)

    Format a definition list as a “linear list”. This is the default when the available width for the definitions (2nd column) is below `self.col2_min_width`.

    Parameters:

      dl (Sequence[Definition])

    Return type:

      None

  write_epilog(epilog)
    Parameters:

      epilog (str)

    Return type:

      None

  __repr__()
    Return type:

      str

class cloup.HelpSection

  A container for a help section data.

  Parameters:

    - heading (str)

    - definitions (Sequence[Tuple[str, str | Callable[[int], str]]])

    - help (str | None)

    - constraint (str | None)

  heading: str

    Help section title.

  definitions: Sequence[Definition]

    Rows with 2 columns each. The 2nd element of each row can also be a function taking an integer (the available width for the 2nd column) and returning a string.

  help: str | None = None

    (Optional) long description of the section.

  constraint: str | None = None

    (Optional) option group constraint description.

class cloup.Context(*ctx_args, align_option_groups=None, align_sections=None, show_subcommand_aliases=None, show_constraints=None, check_constraints_consistency=None, formatter_settings={}, **ctx_kwargs)

  Bases: `click.Context`

  A custom context for Cloup.

  Look up `click.Context` for the list of all arguments.

  Added in version 0.9.0: added the `check_constraints_consistency` parameter.

  Added in version 0.8.0.

  Parameters:

    - ctx_args (Any) – arguments forwarded to `click.Context`.

    - align_option_groups (Optional[bool]) – if True, align the definition lists of all option groups of a command. You can override this by setting the corresponding argument of `Command` (but you probably shouldn’t: be consistent).

    - align_sections (Optional[bool]) – if True, align the definition lists of all subcommands of a group. You can override this by setting the corresponding argument of `Group` (but you probably shouldn’t: be consistent).

    - show_subcommand_aliases (Optional[bool]) – whether to show the aliases of subcommands in the help of a `cloup.Group`.

    - show_constraints (Optional[bool]) – whether to include a “Constraint” section in the command help (if at least one constraint is defined).

    - check_constraints_consistency (Optional[bool]) – enable additional checks for constraints which detects mistakes of the developer (see `cloup.Constraint.check_consistency()`).

    - formatter_settings (Dict[str, Any]) – keyword arguments forwarded to `HelpFormatter` in `make_formatter`. This args are merged with those of the (eventual) parent context and then merged again (being overridden) by those of the command. Tip: use the static method `HelpFormatter.settings()` to create this dictionary, so that you can be guided by your IDE.

    - ctx_kwargs (Any) – keyword arguments forwarded to `click.Context`.

  formatter_class: Type[cloup.formatting.HelpFormatter]
  align_option_groups
  align_sections
  show_subcommand_aliases
  show_constraints
  check_constraints_consistency
  formatter_settings
  get_formatter_settings()
    Return type:

      Dict[str, Any]

  make_formatter()

    Creates the `HelpFormatter` for the help and usage output.

    To quickly customize the formatter class used without overriding this method, set the `formatter_class` attribute.

    Changed in version 8.0: Added the `formatter_class` attribute.

    Return type:

      cloup.formatting.HelpFormatter

  static settings(*, auto_envvar_prefix=MISSING, default_map=MISSING, terminal_width=MISSING, max_content_width=MISSING, resilient_parsing=MISSING, allow_extra_args=MISSING, allow_interspersed_args=MISSING, ignore_unknown_options=MISSING, help_option_names=MISSING, token_normalize_func=MISSING, color=MISSING, show_default=MISSING, align_option_groups=MISSING, align_sections=MISSING, show_subcommand_aliases=MISSING, show_constraints=MISSING, check_constraints_consistency=MISSING, formatter_settings=MISSING)

    Utility method for creating a `context_settings` dictionary.

    Parameters:

      - auto_envvar_prefix (cloup.typing.Possibly[str]) – the prefix to use for automatic environment variables. If this is None then reading from environment variables is disabled. This does not affect manually set environment variables which are always read.

      - default_map (cloup.typing.Possibly[Dict[str, Any]]) – a dictionary (like object) with default values for parameters.

      - terminal_width (cloup.typing.Possibly[int]) – the width of the terminal. The default is inherited from parent context. If no context defines the terminal width then auto-detection will be applied.

      - max_content_width (cloup.typing.Possibly[int]) – the maximum width for content rendered by Click (this currently only affects help pages). This defaults to 80 characters if not overridden. In other words: even if the terminal is larger than that, Click will not format things wider than 80 characters by default. In addition to that, formatters might add some safety mapping on the right.

      - resilient_parsing (cloup.typing.Possibly[bool]) – if this flag is enabled then Click will parse without any interactivity or callback invocation. Default values will also be ignored. This is useful for implementing things such as completion support.

      - allow_extra_args (cloup.typing.Possibly[bool]) – if this is set to True then extra arguments at the end will not raise an error and will be kept on the context. The default is to inherit from the command.

      - allow_interspersed_args (cloup.typing.Possibly[bool]) – if this is set to False then options and arguments cannot be mixed. The default is to inherit from the command.

      - ignore_unknown_options (cloup.typing.Possibly[bool]) – instructs click to ignore options it does not know and keeps them for later processing.

      - help_option_names (cloup.typing.Possibly[List[str]]) – optionally a list of strings that define how the default help parameter is named. The default is `['--help']`.

      - token_normalize_func (cloup.typing.Possibly[Callable[[str], str]]) – an optional function that is used to normalize tokens (options, choices, etc.). This for instance can be used to implement case-insensitive behavior.

      - color (cloup.typing.Possibly[bool]) – controls if the terminal supports ANSI colors or not. The default is auto-detection. This is only needed if ANSI codes are used in texts that Click prints which is by default not the case. This for instance would affect help output.

      - show_default (cloup.typing.Possibly[bool]) – Show defaults for all options. If not set, defaults to the value from a parent context. Overrides an option’s `show_default` argument.

      - align_option_groups (cloup.typing.Possibly[bool]) – if True, align the definition lists of all option groups of a command. You can override this by setting the corresponding argument of `Command` (but you probably shouldn’t: be consistent).

      - align_sections (cloup.typing.Possibly[bool]) – if True, align the definition lists of all subcommands of a group. You can override this by setting the corresponding argument of `Group` (but you probably shouldn’t: be consistent).

      - show_subcommand_aliases (cloup.typing.Possibly[bool]) – whether to show the aliases of subcommands in the help of a `cloup.Group`.

      - show_constraints (cloup.typing.Possibly[bool]) – whether to include a “Constraint” section in the command help (if at least one constraint is defined).

      - check_constraints_consistency (cloup.typing.Possibly[bool]) – enable additional checks for constraints which detects mistakes of the developer (see `cloup.Constraint.check_consistency()`).

      - formatter_settings (cloup.typing.Possibly[Dict[str, Any]]) – keyword arguments forwarded to `HelpFormatter` in `make_formatter`. This args are merged with those of the (eventual) parent context and then merged again (being overridden) by those of the command. Tip: use the static method `HelpFormatter.settings()` to create this dictionary, so that you can be guided by your IDE.

    Return type:

      Dict[str, Any]

cloup.get_current_context() → Context
cloup.get_current_context(silent: bool = False) → Context | None

  Equivalent to `click.get_current_context()` but casts the returned `click.Context` object to `cloup.Context` (which is safe when using cloup commands classes and decorators).

cloup.pass_context(f)

  Marks a callback as wanting to receive the current context object as first argument. Equivalent to `click.pass_context()` but assumes the current context is of type `cloup.Context`.

  Parameters:

    f (Callable[Concatenate[Context, P], R])

  Return type:

    Callable[P, R]

class cloup.Argument(*args, help=None, **attrs)

  Bases: `click.Argument`

  A `click.Argument` with help text.

  help = None
  get_help_record(ctx)

class cloup.Option(*args, group=None, **attrs)

  Bases: `click.Option`

  A `click.Option` with an extra field `group` of type `OptionGroup`.

  group = None

cloup.argument(*param_decls, cls=None, **attrs)

cloup.option(*param_decls, cls=None, group=None, **attrs)

  Attach an `Option` to the command. Refer to `click.Option` and `click.Parameter` for more info about the accepted parameters.

  In your IDE, you won’t see arguments relating to shell completion, because they are different in Click 7 and 8 (both supported by Cloup):

  - in Click 7, it’s `autocompletion`

  - in Click 8, it’s `shell_complete`.

  These arguments have different semantics, refer to Click’s docs.

class cloup.OptionGroup(title, help=None, constraint=None, hidden=False)

  Contains the information of an option group and identifies it. Note that, as far as the clients of this library are concerned, an `OptionGroups` acts as a “marker” for options, not as a container for related options. When you call `@optgroup.option(...)` you are not adding an option to a container, you are just adding an option marked with this option group.

  Added in version 0.8.0: The `hidden` parameter.

  Parameters:

    - title (str)

    - help (str | None)

    - constraint (Constraint | None)

    - hidden (bool)

  title
  help = None
  constraint = None
  hidden = False
  property options: Sequence[click.Option]
    Return type:

      Sequence[click.Option]

  get_help_records(ctx)
    Parameters:

      ctx (click.Context)

    Return type:

      List[Tuple[str, str]]

  option(*param_decls, **attrs)

    Refer to `cloup.option()`.

    Parameters:

      - param_decls (str)

      - attrs (Any)

    Return type:

      Callable[[cloup.typing.F], cloup.typing.F]

  __iter__()
    Return type:

      Iterator[click.Option]

  __getitem__(i)
    Parameters:

      i (int)

    Return type:

      click.Option

  __len__()
    Return type:

      int

  __repr__()
    Return type:

      str

  __str__()
    Return type:

      str

class cloup.OptionGroupMixin(*args, align_option_groups=None, **kwargs)

  Implements support for:

  > - option groups

  > - the “Positional arguments” help section; this section is shown only if at least one of your arguments has non-empty `help`.

  Important

  In order to check the constraints defined on the option groups, a command must inherits from `cloup.ConstraintMixin` too!

  Added in version 0.14.0: added the “Positional arguments” help section.

  Changed in version 0.8.0: this mixin now relies on `cloup.HelpFormatter` to align help sections. If a `click.HelpFormatter` is used with a `TypeError` is raised.

  Changed in version 0.8.0: removed `format_option_group`. Added `get_default_option_group` and `make_option_group_help_section`.

  Added in version 0.5.0.

  Parameters:

    - align_option_groups (bool | None) – whether to align the columns of all option groups’ help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only.

    - args (Any) – positional arguments forwarded to the next class in the MRO

    - kwargs (Any) – keyword arguments forwarded to the next class in the MRO

  align_option_groups = None
  arguments = []
  option_groups

    List of all option groups, except the “default option group”.

  ungrouped_options = []

    List of options not explicitly assigned to an user-defined option group. These options will be included in the “default option group”. Note: this list does not include options added automatically by Click based on context settings, like the `--help` option; use the `get_ungrouped_options()` method if you need the real full list (which needs a `Context` object).

  get_ungrouped_options(ctx)

    Return options not explicitly assigned to an option group (eventually including the `--help` option), i.e. options that will be part of the “default option group”.

    Parameters:

      ctx (click.Context)

    Return type:

      Sequence[click.Option]

  get_argument_help_record(arg, ctx)
    Parameters:

      - arg (click.Argument)

      - ctx (click.Context)

    Return type:

      Tuple[str, str]

  get_arguments_help_section(ctx)
    Parameters:

      ctx (click.Context)

    Return type:

      Optional[cloup.formatting.HelpSection]

  make_option_group_help_section(group, ctx)

    Return a `HelpSection` for an `OptionGroup`, i.e. an object containing the title, the optional description and the options’ definitions for this option group.

    Added in version 0.8.0.

    Parameters:

      - group (OptionGroup)

      - ctx (click.Context)

    Return type:

      cloup.formatting.HelpSection

  must_align_option_groups(ctx, default=True)

    Return `True` if the help sections of all options groups should have their columns aligned.

    Added in version 0.8.0.

    Parameters:

      - ctx (Optional[click.Context])

      - default (bool)

    Return type:

      bool

  get_default_option_group(ctx, is_the_only_visible_option_group=False)

    Return an `OptionGroup` instance for the options not explicitly assigned to an option group, eventually including the `--help` option.

    Added in version 0.8.0.

    Parameters:

      - ctx (click.Context)

      - is_the_only_visible_option_group (bool)

    Return type:

      OptionGroup

  format_params(ctx, formatter)
    Parameters:

      - ctx (click.Context)

      - formatter (click.HelpFormatter)

    Return type:

      None

cloup.option_group(title: str, help: str, *options: cloup.typing.Decorator, constraint: cloup.constraints.Constraint | None = None, hidden: bool = False) → Callable[[cloup.typing.F], cloup.typing.F]
cloup.option_group(title: str, *options: cloup.typing.Decorator, help: str | None = None, constraint: cloup.constraints.Constraint | None = None, hidden: bool = False) → Callable[[cloup.typing.F], cloup.typing.F]

  Return a decorator that annotates a function with an option group.

  The `help` argument is an optional description and can be provided either as keyword argument or as 2nd positional argument after the `name` of the group:

      # help as keyword argument
      @option_group(name, *options, help=None, ...)

      # help as 2nd positional argument
      @option_group(name, help, *options, ...)

  Changed in version 0.9.0: in order to support the decorator `cloup.constrained_params()`, `@option_group` now allows each input decorators to add multiple options.

  Parameters:

    - title – title of the help section describing the option group.

    - help – an optional description shown below the name; can be provided as keyword argument or 2nd positional argument.

    - options – an arbitrary number of decorators like `click.option`, which attach one or multiple options to the decorated command function.

    - constraint – an optional instance of `Constraint` (see Constraints for more info); a description of the constraint will be shown between squared brackets aside the option group title (or below it if too long).

    - hidden – if `True`, the option group and all its options are hidden from the help page (all contained options will have their `hidden` attribute set to `True`).

class cloup.Section(title, commands=(), is_sorted=False)

  A group of (sub)commands to show in the same help section of a `MultiCommand`. You can use sections with any Command that inherits from `SectionMixin`.

  Changed in version 0.6.0: removed the deprecated old name `GroupSection`.

  Changed in version 0.5.0: introduced the new name `Section` and deprecated the old `GroupSection`.

  Parameters:

    - title (str)

    - commands (Iterable[Command] | Dict[str, Command]) – sequence of commands or dict of commands keyed by name

    - is_sorted (bool) – if True, `list_commands()` returns the commands in lexicographic order

  title
  is_sorted = False
  commands: collections.OrderedDict[str, click.Command]
  classmethod sorted(title, commands=())
    Parameters:

      - title (str)

      - commands (Subcommands)

    Return type:

      Section

  add_command(cmd, name=None)
    Parameters:

      - cmd (click.Command)

      - name (Optional[str])

    Return type:

      None

  list_commands()
    Return type:

      List[Tuple[str, click.Command]]

  __len__()
    Return type:

      int

  __repr__()
    Return type:

      str

class cloup.SectionMixin(*args, commands=None, sections=(), align_sections=None, **kwargs)

  Adds to a `click.MultiCommand` the possibility of organizing its subcommands into multiple help sections.

  Sections can be specified in the following ways:

  1. passing a list of `Section` objects to the constructor setting the argument `sections`

  2. using `add_section()` to add a single section

  3. using `add_command()` with the argument section set

  Commands not assigned to any user-defined section are added to the “default section”, whose title is “Commands” or “Other commands” depending on whether it is the only section or not. The default section is the last shown section in the help and its commands are listed in lexicographic order.

  Changed in version 0.8.0: this mixin now relies on `cloup.HelpFormatter` to align help sections. If a `click.HelpFormatter` is used with a `TypeError` is raised.

  Changed in version 0.8.0: removed `format_section`. Added `make_commands_help_section`.

  Added in version 0.5.0.

  Parameters:

    - align_sections (bool | None) – whether to align the columns of all subcommands’ help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only.

    - args (Any) – positional arguments forwarded to the next class in the MRO

    - kwargs (Any) – keyword arguments forwarded to the next class in the MRO

    - commands (Dict[str, Command] | None)

    - sections (Iterable[Section])

  align_sections = None
  add_section(section)

    Add a `Section` to this group. You can add the same section object only a single time.

    See Also:

      `section()`

    Parameters:

      section (Section)

    Return type:

      None

  section(title, *commands, **attrs)

    Create a new `Section`, adds it to this group and returns it.

    Parameters:

      - title (str)

      - commands (click.Command)

      - attrs (Any)

    Return type:

      Section

  add_command(cmd, name=None, section=None, fallback_to_default_section=True)

    Add a subcommand to this `Group`.

    Implementation note: `fallback_to_default_section` looks not very clean but, even if it’s not immediate to see (it wasn’t for me), I chose it over apparently cleaner options.

    Parameters:

      - cmd (click.Command)

      - name (Optional[str])

      - section (Optional[Section]) – a `Section` instance. The command must not be in the section already.

      - fallback_to_default_section (bool) – if `section` is None and this option is enabled, the command is added to the “default section”. If disabled, the command is not added to any section unless `section` is provided. This is useful for internal code and subclasses. Don’t disable it unless you know what you are doing.

    Return type:

      None

  list_sections(ctx, include_default_section=True)

    Return the list of all sections in the “correct order”.

    If `include_default_section=True` and the default section is non-empty, it will be included at the end of the list.

    Parameters:

      - ctx (click.Context)

      - include_default_section (bool)

    Return type:

      List[Section]

  format_subcommand_name(ctx, name, cmd)

    Used to format the name of the subcommands. This method is useful when you combine this extension with other click extensions that override `format_commands()`. Most of these, like click-default-group, just add something to the name of the subcommands, which is exactly what this method allows you to do without overriding bigger methods.

    Parameters:

      - ctx (click.Context)

      - name (str)

      - cmd (click.Command)

    Return type:

      str

  make_commands_help_section(ctx, section)
    Parameters:

      - ctx (click.Context)

      - section (Section)

    Return type:

      Optional[cloup.formatting.HelpSection]

  must_align_sections(ctx, default=True)
    Parameters:

      - ctx (Optional[click.Context])

      - default (bool)

    Return type:

      bool

  format_commands(ctx, formatter)
    Parameters:

      - ctx (click.Context)

      - formatter (click.HelpFormatter)

    Return type:

      None

class cloup.Command(*args, aliases=None, formatter_settings=None, **kwargs)

  Bases: `cloup.constraints.ConstraintMixin`, `cloup._option_groups.OptionGroupMixin`, `click.Command`

  A `click.Command` supporting option groups and constraints.

  Refer to superclasses for the documentation of all accepted parameters:

  - `ConstraintMixin`

  - `OptionGroupMixin`

  - `click.Command`

  Besides other things, this class also:

  - adds a `formatter_settings` instance attribute.

  Refer to `click.Command` for the documentation of all parameters.

  Added in version 0.8.0.

  Parameters:

    - constraints – sequence of constraints bound to specific groups of parameters. Note that constraints applied to option groups are collected from the option groups themselves, so they don’t need to be included in this argument.

    - show_constraints – whether to include a “Constraint” section in the command help. This is also available as a context setting having a lower priority than this attribute.

    - args (Any) – positional arguments forwarded to the next class in the MRO

    - kwargs (Any) – keyword arguments forwarded to the next class in the MRO

    - aliases (Iterable[str] | None)

    - formatter_settings (Dict[str, Any] | None)

  context_class: Type[cloup._context.Context]
  aliases: List[str] = []
  formatter_settings: Dict[str, Any]
  get_normalized_epilog()
    Return type:

      str

  format_epilog(ctx, formatter)

    Writes the epilog into the formatter if it exists.

    Parameters:

      - ctx (click.Context)

      - formatter (click.HelpFormatter)

    Return type:

      None

  format_help_text(ctx, formatter)

    Writes the help text to the formatter if it exists.

    Parameters:

      - ctx (click.Context)

      - formatter (click.HelpFormatter)

    Return type:

      None

  format_aliases(ctx, formatter)
    Parameters:

      - ctx (click.Context)

      - formatter (click.HelpFormatter)

    Return type:

      None

  format_help(ctx, formatter)

    Writes the help into the formatter if it exists.

    This is a low-level method called by `get_help()`.

    This calls the following methods:

    - `format_usage()`

    - `format_help_text()`

    - `format_options()`

    - `format_epilog()`

    Parameters:

      - ctx (click.Context)

      - formatter (click.HelpFormatter)

    Return type:

      None

class cloup.Group(*args, show_subcommand_aliases=None, commands=None, **kwargs)

  Bases: `cloup._sections.SectionMixin`, `Command`, `click.Group`

  A `click.Group` that allows to organize its subcommands in multiple help sections and whose subcommands are, by default, of type `cloup.Command`.

  Refer to superclasses for the documentation of all accepted parameters:

  - `SectionMixin`

  - `Command`

  - `click.Group`

  Apart from superclasses arguments, the following is the only additional parameter:

  `show_subcommand_aliases`: `Optional[bool] = None`

    whether to show subcommand aliases; aliases are shown by default and can be disabled using this argument or the homonym context setting.

  Changed in version 0.14.0: this class now supports option groups and constraints.

  Added in version 0.10.0: the “command aliases” feature, including the `show_subcommand_aliases` parameter/attribute.

  Changed in version 0.8.0: this class now inherits from `cloup.BaseCommand`.

  Parameters:

    - align_sections – whether to align the columns of all subcommands’ help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only.

    - args (Any) – positional arguments forwarded to the next class in the MRO

    - kwargs (Any) – keyword arguments forwarded to the next class in the MRO

    - show_subcommand_aliases (bool | None)

    - commands (MutableMapping[str, Command] | Sequence[Command] | None)

  SHOW_SUBCOMMAND_ALIASES: bool = False
  show_subcommand_aliases = None

    Whether to show subcommand aliases.

  alias2name: Dict[str, str]

    Dictionary mapping each alias to a command name.

  add_multiple_commands(commands)
    Parameters:

      commands (Union[Mapping[str, click.Command], Sequence[click.Command]])

    Return type:

      None

  add_command(cmd, name=None, section=None, fallback_to_default_section=True)

    Add a subcommand to this `Group`.

    Implementation note: `fallback_to_default_section` looks not very clean but, even if it’s not immediate to see (it wasn’t for me), I chose it over apparently cleaner options.

    Parameters:

      - cmd (click.Command)

      - name (Optional[str])

      - section (Optional[cloup._sections.Section]) – a `Section` instance. The command must not be in the section already.

      - fallback_to_default_section (bool) – if `section` is None and this option is enabled, the command is added to the “default section”. If disabled, the command is not added to any section unless `section` is provided. This is useful for internal code and subclasses. Don’t disable it unless you know what you are doing.

    Return type:

      None

  resolve_command_name(ctx, name)

    Map a string supposed to be a command name or an alias to a normalized command name. If no match is found, it returns `None`.

    Parameters:

      - ctx (click.Context)

      - name (str)

    Return type:

      Optional[str]

  resolve_command(ctx, args)
    Parameters:

      - ctx (click.Context)

      - args (List[str])

    Return type:

      Tuple[Optional[str], Optional[click.Command], List[str]]

  handle_bad_command_name(bad_name, valid_names, error)

    This method is called when a command name cannot be resolved. Useful to implement the “Did you mean <x>?” feature.

    Parameters:

      - bad_name (str) – the command name that could not be resolved.

      - valid_names (List[str]) – the list of valid command names, including aliases.

      - error (click.UsageError) – the original error coming from Click.

    Returns:

      the original error or a new one.

    Return type:

      click.UsageError

  must_show_subcommand_aliases(ctx)
    Parameters:

      ctx (click.Context)

    Return type:

      bool

  format_subcommand_name(ctx, name, cmd)

    Used to format the name of the subcommands. This method is useful when you combine this extension with other click extensions that override `format_commands()`. Most of these, like click-default-group, just add something to the name of the subcommands, which is exactly what this method allows you to do without overriding bigger methods.

    Parameters:

      - ctx (click.Context)

      - name (str)

      - cmd (click.Command)

    Return type:

      str

  static format_subcommand_aliases(aliases, theme)
    Parameters:

      - aliases (Sequence[str])

      - theme (cloup.HelpTheme)

    Return type:

      str

  command(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: None = None, section: cloup._sections.Section | None = None, context_settings: Dict[str, Any] | None = None, formatter_settings: Dict[str, Any] | None = None, help: str | None = None, epilog: str | None = None, short_help: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, align_option_groups: bool | None = None, show_constraints: bool | None = None, params: List[click.Parameter] | None = None) → Callable[[cloup.typing.AnyCallable], click.Command]
  command(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: Type[C], section: cloup._sections.Section | None = None, context_settings: Dict[str, Any] | None = None, help: str | None = None, epilog: str | None = None, short_help: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, params: List[click.Parameter] | None = None, **kwargs: Any) → Callable[[cloup.typing.AnyCallable], C]

    Return a decorator that creates a new subcommand of this `Group` using the decorated function as callback.

    It takes the same arguments of `command()` plus:

    `section`: `Optional[Section]`

      if provided, put the subcommand in this section.

    Changed in version 0.10.0: all arguments but `name` are now keyword-only.

  group(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: None = None, section: cloup._sections.Section | None = None, sections: Iterable[cloup._sections.Section] = (), align_sections: bool | None = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Dict[str, Any] | None = None, formatter_settings: Dict[str, Any] = {}, help: str | None = None, epilog: str | None = None, short_help: str | None = None, options_metavar: str | None = '[OPTIONS]', subcommand_metavar: str | None = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, show_subcommand_aliases: bool = False) → Callable[[cloup.typing.AnyCallable], click.Group]
  group(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: Type[G] | None = None, section: cloup._sections.Section | None = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Dict[str, Any] | None = None, help: str | None = None, epilog: str | None = None, short_help: str | None = None, options_metavar: str | None = '[OPTIONS]', subcommand_metavar: str | None = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: List[click.Parameter] | None = None, **kwargs: Any) → Callable[[cloup.typing.AnyCallable], G]

    Return a decorator that creates a new subcommand of this `Group` using the decorated function as callback.

    It takes the same argument of `group()` plus:

    `section`: `Optional[Section]`

      if provided, put the subcommand in this section.

    Changed in version 0.10.0: all arguments but `name` are now keyword-only.

cloup.command(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: None = None, context_settings: Dict[str, Any] | None = None, formatter_settings: Dict[str, Any] | None = None, help: str | None = None, short_help: str | None = None, epilog: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, align_option_groups: bool | None = None, show_constraints: bool | None = None, params: List[click.Parameter] | None = None) → Callable[[cloup.typing.AnyCallable], Command]
cloup.command(name: str | None = None, *, aliases: Iterable[str] | None = None, cls: Type[C], context_settings: Dict[str, Any] | None = None, help: str | None = None, short_help: str | None = None, epilog: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, params: List[click.Parameter] | None = None, **kwargs: Any) → Callable[[cloup.typing.AnyCallable], C]

  Return a decorator that creates a new command using the decorated function as callback.

  The only differences with respect to `click.command` are:

  - the default command class is `cloup.Command`

  - supports constraints, provided that `cls` inherits from `ConstraintMixin` like `cloup.Command` (the default)

  - this function has detailed type hints and uses generics for the `cls` argument and return type.

  Note that the following arguments are about Cloup-specific features and are not supported by all `click.Command`, so if you provide a custom `cls` make sure you don’t set these:

  - `formatter_settings`

  - `align_option_groups` (`cls` needs to inherit from `OptionGroupMixin`)

  - `show_constraints` (`cls` needs to inherit `ConstraintMixin`).

  Changed in version 0.10.0: this function is now generic: the return type depends on what you provide as `cls` argument.

  Changed in version 0.9.0: all arguments but `name` are now keyword-only arguments.

  Parameters:

    - name – the name of the command to use unless a group overrides it.

    - aliases – alternative names for this command. If `cls` is not a Cloup command class, aliases will be stored in the instantiated command by monkey-patching and aliases won’t be documented in the help page of the command.

    - cls – the command class to instantiate.

    - context_settings – an optional dictionary with defaults that are passed to the context object.

    - formatter_settings – arguments for the formatter; you can use `HelpFormatter.settings()` to build this dictionary.

    - help – the help string to use for this command.

    - epilog – like the help string but it’s printed at the end of the help page after everything else.

    - short_help – the short help to use for this command. This is shown on the command listing of the parent command.

    - options_metavar – metavar for options shown in the command’s usage string.

    - add_help_option – by default each command registers a `--help` option. This can be disabled by this parameter.

    - no_args_is_help – this controls what happens if no arguments are provided. This option is disabled by default. If enabled this will add `--help` as argument if no arguments are passed

    - hidden – hide this command from help outputs.

    - deprecated – issues a message indicating that the command is deprecated.

    - align_option_groups – whether to align the columns of all option groups’ help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only.

    - show_constraints – whether to include a “Constraint” section in the command help. This is also available as a context setting having a lower priority than this attribute.

    - params – (click >= 8.1.0) a list of parameters (`Argument` and `Option` instances). Params added with `@option` and `@argument` are appended to the end of the list if given.

    - kwargs – any other argument accepted by the instantiated command class (`cls`).

cloup.group(name: str | None = None, *, cls: None = None, aliases: Iterable[str] | None = None, sections: Iterable[cloup._sections.Section] = (), align_sections: bool | None = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Dict[str, Any] | None = None, formatter_settings: Dict[str, Any] = {}, help: str | None = None, short_help: str | None = None, epilog: str | None = None, options_metavar: str | None = '[OPTIONS]', subcommand_metavar: str | None = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: List[click.Parameter] | None = None, show_subcommand_aliases: bool = False) → Callable[[cloup.typing.AnyCallable], Group]
cloup.group(name: str | None = None, *, cls: Type[G], aliases: Iterable[str] | None = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Dict[str, Any] | None = None, help: str | None = None, short_help: str | None = None, epilog: str | None = None, options_metavar: str | None = '[OPTIONS]', subcommand_metavar: str | None = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: List[click.Parameter] | None = None, **kwargs: Any) → Callable[[cloup.typing.AnyCallable], G]

  Return a decorator that instantiates a `Group` (or a subclass of it) using the decorated function as callback.

  Changed in version 0.10.0: the `cls` argument can now be any `click.Group` (previously had to be a `cloup.Group`) and the type of the instantiated command matches it (previously, the type was `cloup.Group` even if `cls` was a subclass of it).

  Changed in version 0.9.0: all arguments but `name` are now keyword-only arguments.

  Parameters:

    - name – the name of the command to use unless a group overrides it.

    - cls – the `click.Group` (sub)class to instantiate. This is `cloup.Group` by default. Note that some of the arguments are only supported by `cloup.Group`.

    - sections – a list of Section objects containing the subcommands of this `Group`. This argument is only supported by commands inheriting from `cloup.SectionMixin`.

    - align_sections – whether to align the columns of all subcommands’ help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only.

    - context_settings – an optional dictionary with defaults that are passed to the context object.

    - formatter_settings – arguments for the formatter; you can use `HelpFormatter.settings()` to build this dictionary.

    - help – the help string to use for this command.

    - short_help – the short help to use for this command. This is shown on the command listing of the parent command.

    - epilog – like the help string but it’s printed at the end of the help page after everything else.

    - options_metavar – metavar for options shown in the command’s usage string.

    - add_help_option – by default each command registers a `--help` option. This can be disabled by this parameter.

    - hidden – hide this command from help outputs.

    - deprecated – issues a message indicating that the command is deprecated.

    - invoke_without_command – this controls how the multi command itself is invoked. By default it’s only invoked if a subcommand is provided.

    - no_args_is_help – this controls what happens if no arguments are provided. This option is enabled by default if invoke_without_command is disabled or disabled if it’s enabled. If enabled this will add `--help` as argument if no arguments are passed.

    - subcommand_metavar – string used in the command’s usage string to indicate the subcommand place.

    - chain – if this is set to True, chaining of multiple subcommands is enabled. This restricts the form of commands in that they cannot have optional arguments but it allows multiple commands to be chained together.

    - params – (click >= 8.1.0) a list of parameters (`Argument` and `Option` instances). Params added with `@option` and `@argument` are appended to the end of the list if given.

    - kwargs – any other argument accepted by the instantiated command class.

class cloup.ConstraintMixin(*args, constraints=(), show_constraints=None, **kwargs)

  Provides support for constraints.

  Parameters:

    - constraints (Sequence[BoundConstraintSpec | BoundConstraint]) – sequence of constraints bound to specific groups of parameters. Note that constraints applied to option groups are collected from the option groups themselves, so they don’t need to be included in this argument.

    - show_constraints (bool | None) – whether to include a “Constraint” section in the command help. This is also available as a context setting having a lower priority than this attribute.

    - args (Any) – positional arguments forwarded to the next class in the MRO

    - kwargs (Any) – keyword arguments forwarded to the next class in the MRO

  show_constraints = None
  optgroup_constraints

    Constraints applied to `OptionGroup` instances.

  param_constraints: Tuple[BoundConstraint, Ellipsis]

    Constraints registered using `@constraint` (or equivalent method).

  all_constraints

    All constraints applied to parameter/option groups of this command.

  parse_args(ctx, args)
    Parameters:

      - ctx (click.Context)

      - args (List[str])

    Return type:

      List[str]

  get_param_by_name(name)
    Parameters:

      name (str)

    Return type:

      click.Parameter

  get_params_by_name(names)
    Parameters:

      names (Iterable[str])

    Return type:

      Sequence[click.Parameter]

  format_constraints(ctx, formatter)
    Parameters:

      - ctx (click.Context)

      - formatter (cloup.HelpFormatter)

    Return type:

      None

  must_show_constraints(ctx)
    Parameters:

      ctx (click.Context)

    Return type:

      bool

cloup.constrained_params(constr, *param_adders)

  Return a decorator that adds the given parameters and applies a constraint to them. Equivalent to:

      @param_adders[0]
      ...
      @param_adders[-1]
      @constraint(constr, <param names>)

  This decorator saves you to manually (re)type the parameter names. It can also be used inside `@option_group`.

  Instead of using this decorator, you can also call the constraint itself:

      @constr(*param_adders)

  but remember that:

  - Python 3.9 is the first that allows arbitrary expressions on the right of `@`;

  - using a long conditional/composite constraint as decorator may be less readable.

  In these cases, you may consider using `@constrained_params`.

  Added in version 0.9.0.

  Parameters:

    - constr (Constraint) – an instance of `Constraint`

    - param_adders (Callable[[Callable[[...], Any]], Callable[[...], Any]]) – function decorators, each attaching a single parameter to the decorated function.

  Return type:

    Callable[[F], F]

cloup.constraint(constr, params)

  Register a constraint on a list of parameters specified by (destination) name (e.g. the default name of `--input-file` is `input_file`).

  Parameters:

    - constr (Constraint)

    - params (Iterable[str])

  Return type:

    Callable[[F], F]

cloup.dir_path(*, path_type=pathlib.Path, exists=False, readable=True, writable=False, executable=False, resolve_path=False, allow_dash=False)

  Shortcut for `click.Path` with `file_okay=False, path_type=pathlib.Path`.

  Parameters:

    - path_type (Type[Any])

    - exists (bool)

    - readable (bool)

    - writable (bool)

    - executable (bool)

    - resolve_path (bool)

    - allow_dash (bool)

  Return type:

    Path

cloup.file_path(*, path_type=pathlib.Path, exists=False, readable=True, writable=False, executable=False, resolve_path=False, allow_dash=False)

  Shortcut for `click.Path` with `dir_okay=False, path_type=pathlib.Path`.

  Parameters:

    - path_type (Type[Any])

    - exists (bool)

    - readable (bool)

    - writable (bool)

    - executable (bool)

    - resolve_path (bool)

    - allow_dash (bool)

  Return type:

    Path

cloup.path(*, path_type=pathlib.Path, exists=False, file_okay=True, dir_okay=True, readable=True, writable=False, executable=False, resolve_path=False, allow_dash=False)

  Shortcut for `click.Path` with `path_type=pathlib.Path`.

  Parameters:

    - path_type (Type[Any])

    - exists (bool)

    - file_okay (bool)

    - dir_okay (bool)

    - readable (bool)

    - writable (bool)

    - executable (bool)

    - resolve_path (bool)

    - allow_dash (bool)

  Return type:

    Path