cloup

Top-level package for cloup.

Subpackages

• cloup.constraints
  • cloup.constraints.common
  • cloup.constraints.conditions
  • cloup.constraints.exceptions

Submodules

• cloup.formatting
• cloup.styling
• cloup.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.
Context(*ctx_args[, align_option_groups, …])	A custom context for Cloup.
GroupedOption(*args[, group])	A click.Option with an extra field group of type OptionGroup
OptionGroup(name[, help, constraint, hidden])	Contains the information of an option group and identifies it.
OptionGroupMixin(*args[, align_option_groups])	Implements support to option groups.
Section(title[, commands, 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 to organize its subcommands in multiple help sections.
BaseCommand(*args[, formatter_settings])	Base class for cloup commands.
Command(*click_args[, formatter_settings, …])	A click.Command supporting option groups and constraints.
Group([name, commands, sections, …])	A click.Group that allows to organize its subcommands in multiple help sections and and whose subcommands are, by default, of type cloup.Command.
ConstraintMixin(*args[, constraints, …])	Provides support to constraints.

Functions

option(*param_decls[, group, cls])
option_group(name, *args, **kwargs)	Returns a decorator that annotates a function with an option group.
command([name, cls])	Decorator that creates a new command using the wrapped function as callback.
group([name, cls])	Decorator for creating a new Group.
constraint(constr, params)	Registers a constraint.

Attributes

__author__
__email__
__version__
__version_tuple__

Contents

cloup.__author__ = Gianluca Gippetto

cloup.__email__ = gianluca.gippetto@gmail.com

cloup.__version__

cloup.__version_tuple__

class cloup.HelpTheme

Bases: NamedTuple

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.

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

epilog :IStyle

Style of the epilog.

with_(self, invoked_command=None, command_help=None, heading=None, constraint=None, section_help=None, col1=None, col2=None, 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]) –

• epilog (Optional[IStyle]) –

Return type

HelpTheme

static dark()

A theme assuming a dark terminal background color.

static light()

A theme assuming a light terminal background color.

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 (Optional[str]) – foreground color

• bg (Optional[str]) – background color

• bold (Optional[bool]) –

• dim (Optional[bool]) –

• underline (Optional[bool]) –

• overline (Optional[bool]) –

• italic (Optional[bool]) –

• blink (Optional[bool]) –

• reverse (Optional[bool]) –

• strikethrough (Optional[bool]) –

• text_transform (Optional[Callable[[str], str]]) – a generic string transformation; useful to apply functions like str.upper

Return type

None

New in version 0.8.0.

fg :Optional[str]

bg :Optional[str]

bold :Optional[bool]

dim :Optional[bool]

underline :Optional[bool]

overline :Optional[bool]

italic :Optional[bool]

blink :Optional[bool]

reverse :Optional[bool]

strikethrough :Optional[bool]

text_transform :Optional[IStyle]

__call__(self, 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='', 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).

New in version 0.8.0.

Parameters

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

• width (Optional[int]) – content line width; by default it’s initialized to min(terminal_width - 1, max_width) where max_width is another argument.

• max_width (Optional[int]) – 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 (str) – a string printed after each row of a definition list (including the last).

• theme (cloup.styling.HelpTheme) – an HelpTheme instance specifying how to style the various elements of the help page.

static settings(*, width=None, max_width=None, indent_increment=None, col1_max_width=None, col2_min_width=None, col_spacing=None, row_sep=None, theme=None)

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 pretty self-explanatory. Refer to HelpFormatter in case of doubts.

Parameters

• width (Optional[int]) –

• max_width (Optional[int]) –

• indent_increment (Optional[int]) –

• col1_max_width (Optional[int]) –

• col2_min_width (Optional[int]) –

• col_spacing (Optional[int]) –

• row_sep (Optional[str]) –

• theme (Optional[cloup.styling.HelpTheme]) –

Return type

Dict[str, Any]

property available_width(self)

Return type

int

write(self, *strings)

Writes a unicode string into the internal buffer.

Parameters

strings (str) –

Return type

None

write_usage(self, prog, args='', prefix='Usage:')

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_command_help_text(self, cmd)

Parameters

cmd (click.Command) –

Return type

None

write_heading(self, heading, newline=True)

Writes a heading into the buffer.

Parameters

• heading (str) –

• newline (bool) –

Return type

None

write_many_sections(self, sections, aligned=True)

Parameters

• sections (Sequence[HelpSection]) –

• aligned (bool) –

Return type

None

write_aligned_sections(self, sections)

Writes multiple aligned definition lists.

Parameters

sections (Sequence[HelpSection]) –

Return type

None

write_section(self, s, col1_width=None)

Parameters

• s (HelpSection) –

• col1_width (Optional[int]) –

Return type

None

write_text(self, 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(self, rows, max_width)

Parameters

• rows (Iterable[Definition]) –

• max_width (int) –

Return type

int

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

Writes 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(self, rows, col1_width, col_spacing, col2_width)

Formats 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(self, dl)

Formats 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(self, epilog)

Parameters

epilog (str) –

Return type

None

__repr__(self)

Return repr(self).

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

Bases: click.Context

A custom context for Cloup.

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

New in version 0.8.0.

Parameters

• ctx_args – arguments forwarded to click.Context.

• ctx_kwargs – keyword 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_constraints (Optional[bool]) – whether to include a “Constraint” section in the command help (if at least one constraint is defined).

• 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.opts() to create this dictionary, so that you can be guided by your IDE.

formatter_class :Type[cloup.formatting.HelpFormatter]

get_formatter_settings(self)

Return type

Dict[str, Any]

make_formatter(self)

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=None, default_map=None, terminal_width=None, max_content_width=None, resilient_parsing=None, allow_extra_args=None, allow_interspersed_args=None, ignore_unknown_options=None, help_option_names=None, token_normalize_func=None, color=None, show_default=None, align_option_groups=None, align_sections=None, show_constraints=None, formatter_settings=None)

Utility method for creating a context_settings dictionary.

Parameters

• auto_envvar_prefix (Optional[bool]) – 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 (Optional[Dict[str, Any]]) – a dictionary (like object) with default values for parameters.

• terminal_width (Optional[int]) – the width of the terminal. The default is inherit from parent context. If no context defines the terminal width then auto detection will be applied.

• max_content_width (Optional[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 (Optional[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 (Optional[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 (Optional[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 (Optional[bool]) – instructs click to ignore options it does not know and keeps them for later processing.

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

• token_normalize_func (Optional[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 (Optional[bool]) – controls if the terminal supports ANSI colors or not. The default is autodetection. 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 (Optional[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 (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_constraints (Optional[bool]) – whether to include a “Constraint” section in the command help (if at least one constraint is defined).

• formatter_settings (Optional[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.opts() to create this dictionary, so that you can be guided by your IDE.

Return type

Dict[str, Any]

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

Bases: click.Option

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

Parameters

group (Optional[cloup._option_groups.OptionGroup]) –

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

Parameters

• name (str) –

• help (Optional[str]) –

• constraint (Optional[cloup.constraints._core.Constraint]) –

• hidden (bool) –

property options(self)

Return type

Sequence[click.Option]

get_help_records(self, ctx)

Parameters

ctx (click.Context) –

Return type

List[Tuple[str, str]]

option(self, *param_decls, **attrs)

__iter__(self)

__getitem__(self, i)

Parameters

i (int) –

Return type

click.Option

__len__(self)

Return type

int

__repr__(self)

Return repr(self).

Return type

str

__str__(self)

Return str(self).

Return type

str

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

Implements support to option groups.

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.

New in version 0.5.0.

Important

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

Parameters

align_option_groups (Optional[bool]) –

get_ungrouped_options(self, ctx)

Parameters

ctx (click.Context) –

Return type

Sequence[click.Option]

make_option_group_help_section(self, group, ctx)

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

New in version 0.8.0.

Parameters

• group (OptionGroup) –

• ctx (click.Context) –

Return type

cloup.formatting.HelpSection

must_align_option_groups(self, ctx, default=True)

New in version 0.8.0.

Parameters

ctx (Optional[click.Context]) –

Return type

bool

get_default_option_group(self, ctx)

New in version 0.8.0.

Parameters

ctx (click.Context) –

Return type

OptionGroup

format_options(self, ctx, formatter)

Parameters

• ctx (click.Context) –

• formatter (click.HelpFormatter) –

Return type

None

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

Parameters

• group (Optional[cloup._option_groups.OptionGroup]) –

• cls (Type[click.core.Option]) –

Return type

Callable[[C], C]

cloup.option_group(name: str, help: str, *options: OptionAdder, constraint: Optional[cloup.constraints.Constraint] = None, hidden: bool = False) → OptionGroupAdder

cloup.option_group(name: str, *options: OptionAdder, help: Optional[str] = None, constraint: Optional[cloup.constraints.Constraint] = None, hidden: bool = False) → OptionGroupAdder

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

The help 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, ...)

Parameters

• name – this is shown as heading 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 annotate the input function with one Option.

• 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=(), 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 (Union[Iterable[click.core.Command], Dict[str, click.core.Command]]) –

• sorted (bool) –

classmethod sorted(cls, title, commands=())

Parameters

• title (str) –

• commands (Subcommands) –

Return type

Section

add_command(self, cmd, name=None)

Parameters

• cmd (click.Command) –

• name (Optional[str]) –

list_commands(self)

Return type

List[Tuple[str, click.Command]]

__len__(self)

Return type

int

__repr__(self)

Return repr(self).

Return type

str

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

Adds to a click.MultiCommand the possibility to organize its subcommands in 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.

New in version 0.5.0.

Parameters

• commands (Optional[Dict[str, click.core.Command]]) –

• sections (Iterable[cloup._sections.Section]) –

• align_sections (Optional[bool]) –

add_section(self, section)

Adds a Section to this group. You can add the same section object a single time.

Parameters

section (Section) –

section(self, title, *commands, **attrs)

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

Parameters

• title (str) –

• commands (click.Command) –

Return type

Section

add_command(self, cmd, name=None, section=None)

Adds a new command. If section is None, the command is added to the default section.

Parameters

• cmd (click.Command) –

• name (Optional[str]) –

• section (Optional[Section]) –

list_sections(self, ctx, include_default_section=True)

Returns 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]

make_commands_help_section(self, section)

Parameters

section (Section) –

Return type

Optional[cloup.formatting.HelpSection]

must_align_sections(self, ctx, default=True)

Parameters

• ctx (Optional[click.Context]) –

• default (bool) –

Return type

bool

format_commands(self, ctx, formatter)

Parameters

• ctx (click.Context) –

• formatter (click.HelpFormatter) –

Return type

None

class cloup.BaseCommand(*args, formatter_settings={}, **kwargs)

Bases: click.Command

Base class for cloup commands.

• It back-ports a feature from Click v8.0-a1, i.e. the context_class class attribute, which is set to cloup.Context.

• It adds a formatter_settings instance attribute.

New in version 0.8.0.

Parameters

formatter_settings (Dict[str, Any]) –

context_class :Type[cloup._context.Context]

make_context(self, info_name, args, parent=None, **extra)

This function when given an info name and arguments will kick off the parsing and create a new Context. It does not invoke the actual command callback though.

To quickly customize the context class used without overriding this method, set the context_class attribute.

Parameters

• info_name – the info name for this invocation. Generally this is the most descriptive name for the script or command. For the toplevel script it’s usually the name of the script, for commands below it it’s the name of the command.

• args – the arguments to parse as list of strings.

• parent – the parent context if available.

• extra – extra keyword arguments forwarded to the context constructor.

Return type

cloup._context.Context

Changed in version 8.0: Added the context_class attribute.

format_epilog(self, ctx, formatter)

Writes the epilog into the formatter if it exists.

format_help_text(self, ctx, formatter)

Writes the help text to the formatter if it exists.

class cloup.Command(*click_args, formatter_settings={}, constraints=(), show_constraints=False, align_option_groups=None, **click_kwargs)

Bases: cloup.constraints.ConstraintMixin, cloup._option_groups.OptionGroupMixin, BaseCommand

A click.Command supporting option groups and constraints.

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

Parameters

• formatter_settings (Dict[str, Any]) –

• constraints (Sequence[cloup.constraints._support.BoundConstraintSpec]) –

• show_constraints (bool) –

• align_option_groups (Optional[bool]) –

class cloup.Group(name=None, commands=None, sections=(), align_sections=None, formatter_settings={}, **attrs)

Bases: cloup._sections.SectionMixin, BaseCommand, click.Group

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

This class is just a click.Group mixed with SectionMixin that overrides the decorators command() and group() so that a section for the created subcommand can be specified.

See the docstring of the two superclasses for more details.

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

Parameters

• name (Optional[str]) –

• commands (Optional[Dict[str, click.core.Command]]) –

• sections (Iterable[cloup._sections.Section]) –

• align_sections (Optional[bool]) –

• formatter_settings (Dict[str, Any]) –

command(self, name=None, cls=None, section=None, **kwargs)

Creates a new command and adds it to this group.

Parameters

• name (Optional[str]) –

• cls (Optional[Type[click.Command]]) –

• section (Optional[cloup._sections.Section]) –

Return type

Callable[[Callable], click.Command]

group(self, name=None, cls=None, section=None, **kwargs)

A shortcut decorator for declaring and attaching a group to the group. This takes the same arguments as group() and immediately registers the created group with this group by calling add_command().

To customize the group class used, set the group_class attribute.

Changed in version 8.0: Added the group_class attribute.

Parameters

• name (Optional[str]) –

• cls (Optional[Type[click.Group]]) –

• section (Optional[cloup._sections.Section]) –

cloup.command(name=None, cls=Command, **attrs)

Decorator that creates a new command using the wrapped function as callback.

The only differences with respect to click.commands are:

• this decorator creates a cloup.Command by default;

• this decorator supports @constraint.

Parameters

• name (Optional[str]) – name of the command

• cls (Type[click.core.Command]) – type of click.Command

• attrs – any argument you can pass to click.command()

Return type

Callable[[Callable], click.core.Command]

cloup.group(name=None, cls=Group, **attrs)

Decorator for creating a new Group.

Note

If you use static type checking, note that the cls optional argument of this function must be of type cloup.Group, not click.Group.

Parameters

• name (Optional[str]) – name of the command

• cls (Type[cloup._commands.Group]) – type of cloup.Group

• attrs – any argument you can pass to click.group()

Return type

Callable[[Callable], cloup._commands.Group]

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

Provides support to constraints.

Parameters

• constraints (Sequence[cloup.constraints._support.BoundConstraintSpec]) –

• show_constraints (Optional[bool]) –

parse_args(self, ctx, args)

get_param_by_name(self, name)

Parameters

name (str) –

Return type

click.Parameter

get_params_by_name(self, names)

Parameters

names (Iterable[str]) –

Return type

Sequence[click.Parameter]

format_constraints(self, ctx, formatter)

Return type

None

format_help(self, ctx, formatter)

Parameters

formatter (click.HelpFormatter) –

Return type

None

cloup.constraint(constr, params)

Registers a constraint.

Parameters

• constr (cloup.constraints._core.Constraint) –

• params (Iterable[str]) –