Contents

cloup

Top-level package for cloup.

Classes summary

GroupedOption(*args[, group])

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

OptionGroup(name[, help, constraint])

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.

Command(*click_args[, constraints, …])

A click.Command supporting option groups and constraints.

Group([name, commands, sections, align_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.

MultiCommand(*args[, commands, sections, …])

A click.MultiCommand 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 Summary

option(*param_decls[, group, cls])

option_group(name, *args, **kwargs)

Attaches an option group to the command. This decorator is overloaded with two signatures::.

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.

Contents

cloup.__author__ = Gianluca Gippetto
cloup.__email__ = gianluca.gippetto@gmail.com
cloup.__version__
cloup.__version_tuple__
class cloup.GroupedOption(*args, group=None, **attrs)[source]

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)[source]
Parameters
get_help_records(self, ctx)[source]
Parameters

ctx (click.Context) –

option(self, *param_decls, **attrs)[source]
__iter__(self)[source]
__getitem__(self, i)[source]
Parameters

i (int) –

Return type

click.Option

__len__(self)[source]
Return type

int

__repr__(self)[source]

Return repr(self).

Return type

str

__str__(self)[source]

Return str(self).

Return type

str

class cloup.OptionGroupMixin(*args, align_option_groups=True, **kwargs)[source]

Implements support to option groups.

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 (bool) –

get_ungrouped_options(self, ctx)[source]
Parameters

ctx (click.Context) –

Return type

Sequence[click.Option]

get_option_group_title(self, ctx, opt_group)[source]
Parameters
Return type

str

format_option_group(self, ctx, formatter, opt_group, help_records=None)[source]
Parameters
format_options(self, ctx, formatter, max_option_width=30)[source]
Parameters
cloup.option(*param_decls, group=None, cls=GroupedOption, **attrs)[source]
Parameters
Return type

Callable[[C], C]

cloup.option_group(name: str, help: str, *options: OptionDecorator, constraint: Optional[cloup.constraints.Constraint] = None) → OptionGroupDecorator[source]
cloup.option_group(name: str, *options: OptionDecorator, help: Optional[str] = None, constraint: Optional[cloup.constraints.Constraint] = None) → OptionGroupDecorator

Attaches an option group to the command. This decorator is overloaded with two signatures:

@option_group(name: str, *options, help: Optional[str] = None)
@option_group(name: str, help: str, *options)

In other words, if the second position argument is a string, it is interpreted as the “help” argument. Otherwise, it is interpreted as the first option; in this case, you can still pass the help as keyword argument.

Parameters

  • name – a mandatory name/title for the group

  • help – an optional help string for the group

  • options – option decorators like click.option

  • constraint – a Constraint to validate on this option group

Returns

a decorator that attaches the contained options to the decorated function

class cloup.Section(title, commands=(), sorted=False)[source]

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=())[source]
Parameters

  • title (str) –

  • commands (Subcommands) –

Return type

Section

add_command(self, cmd, name=None)[source]
Parameters
list_commands(self)[source]
Return type

List[Tuple[str, click.Command]]

__len__(self)[source]
Return type

int

__repr__(self)[source]

Return repr(self).

Return type

str

class cloup.SectionMixin(*args, commands=None, sections=(), align_sections=True, **kwargs)[source]

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.

New in version 0.5.0.

Parameters
add_section(self, section)[source]

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

Parameters

section (Section) –

section(self, title, *commands, **attrs)[source]

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

Parameters
Return type

Section

add_command(self, cmd, name=None, section=None)[source]

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

Parameters
list_sections(self, ctx, include_default_section=True)[source]

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
Return type

List[Section]

format_commands(self, ctx, formatter)[source]
Parameters
format_section(self, ctx, formatter, section, command_col_width=None)[source]
Parameters
class cloup.Command(*click_args, constraints=(), show_constraints=False, align_option_groups=True, **click_kwargs)[source]

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

A click.Command supporting option groups and constraints.

Parameters
class cloup.Group(name=None, commands=None, sections=(), align_sections=True, **attrs)[source]

Bases: cloup._sections.SectionMixin, 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.

Parameters
command(self, name=None, cls=None, section=None, **kwargs)[source]

Creates a new command and adds it to this group.

Parameters
Return type

Callable[[Callable], click.Command]

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

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

Parameters
class cloup.MultiCommand(*args, commands=None, sections=(), align_sections=True, **kwargs)[source]

Bases: cloup._sections.SectionMixin, click.MultiCommand

A click.MultiCommand 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.MultiCommand mixed with SectionMixin. See the docstring of the two superclasses for more details.

Parameters
cloup.command(name=None, cls=Command, **attrs)[source]

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)[source]

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
Return type

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

class cloup.ConstraintMixin(*args, constraints=(), show_constraints=False, **kwargs)[source]

Provides support to constraints.

Parameters
parse_args(self, ctx, args)[source]
get_param_by_name(self, name)[source]
Parameters

name (str) –

Return type

click.Parameter

get_params_by_name(self, names)[source]
Parameters

names (Iterable[str]) –

Return type

List[click.Parameter]

format_constraints(self, ctx, formatter)[source]
Return type

None

format_help(self, ctx, formatter)[source]
Parameters

formatter (click.HelpFormatter) –

Return type

None

cloup.constraint(constr, params)[source]

Registers a constraint.

Parameters
Subcommand sections cloup.constraints