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(*args, **kwargs)

A click.Command supporting option groups.

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, **kwargs)

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: Optional[OptionGroup] = 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: str, help: Optional[str] = None, constraint: Optional[Constraint] = None)[source]
Parameters
get_help_records(self, ctx: click.Context)[source]
option(self, *param_decls, **attrs)[source]
__iter__(self)[source]
__getitem__(self, i: int) → click.Option[source]
__len__(self) → int[source]
__repr__(self) → str[source]

Return repr(self).

__str__(self) → str[source]

Return str(self).

class cloup.OptionGroupMixin(*args, align_option_groups: bool = 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: click.Context) → Sequence[click.Option][source]
get_option_group_title(self, ctx: click.Context, opt_group: cloup._option_groups.OptionGroup) → str[source]
format_option_group(self, ctx: click.Context, formatter: click.HelpFormatter, opt_group: cloup._option_groups.OptionGroup, help_records: Optional[Sequence] = None)[source]
format_options(self, ctx: click.Context, formatter: click.HelpFormatter, max_option_width: int = 30)[source]
cloup.option(*param_decls, group: Optional[OptionGroup] = None, cls: Type[click.Option] = GroupedOption, **attrs) → OptionDecorator[source]
Parameters
Return type

Callable[[C], C]

cloup.option_group(name: str, help: str, *options: OptionDecorator, constraint: Optional[Constraint] = None) → OptionGroupDecorator[source]
cloup.option_group(name: str, *options: OptionDecorator, help: Optional[str] = None, constraint: Optional[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 (str) – 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

Return type

Callable[[C], C]

class cloup.Section(title: str, commands: Subcommands = (), sorted: bool = 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: str, commands: Subcommands = ()) → cloup._sections.Section[source]
add_command(self, cmd: click.Command, name: Optional[str] = None)[source]
list_commands(self) → List[Tuple[str, click.Command]][source]
__len__(self) → int[source]
__repr__(self) → str[source]

Return repr(self).

class cloup.SectionMixin(*args, commands: Optional[Dict[str, click.Command]] = None, sections: Iterable[Section] = (), align_sections: bool = 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: cloup._sections.Section)[source]

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

section(self, title: str, *commands: click.Command, **attrs) → cloup._sections.Section[source]

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

add_command(self, cmd: click.Command, name: Optional[str] = None, section: Optional[Section] = None)[source]

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

list_sections(self, ctx: click.Context, include_default_section: bool = True) → List[Section][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.

format_commands(self, ctx: click.Context, formatter: click.HelpFormatter)[source]
format_section(self, ctx: click.Context, formatter: click.HelpFormatter, section: cloup._sections.Section, command_col_width: Optional[int] = None)[source]
class cloup.Command(*args, **kwargs)[source]

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

A click.Command supporting option groups. This class is obtained by mixing click.Command with cloup.OptionGroupMixin.

class cloup.Group(name: Optional[str] = None, commands: Optional[Dict[str, click.Command]] = None, sections: Iterable[Section] = (), align_sections: bool = 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: Optional[str] = None, cls: Optional[Type[click.Command]] = None, section: Optional[Section] = None, **kwargs) → Callable[[Callable], click.Command][source]

Creates a new command and adds it to this group.

group(self, name: Optional[str] = None, cls: Optional[Type[click.Group]] = None, section: Optional[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().

class cloup.MultiCommand(*args, **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.

cloup.command(name: Optional[str] = None, cls: Type[click.Command] = Command, **attrs) → Callable[[Callable], click.Command][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: Optional[str] = None, cls: Type[Group] = Group, **attrs) → Callable[[Callable], Group][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: Sequence[BoundConstraintSpec] = (), show_constraints: bool = False, **kwargs)[source]

Provides support to constraints.

Parameters
parse_args(self, ctx, args)[source]
get_param_by_name(self, name: str) → click.Parameter[source]
get_params_by_name(self, names: Iterable[str]) → List[Parameter][source]
format_constraints(self, ctx, formatter) → None[source]
format_help(self, ctx, formatter: click.HelpFormatter) → None[source]
cloup.constraint(constr: cloup.constraints._core.Constraint, params: Iterable[str])[source]

Registers a constraint.

Parameters
Subcommand sections cloup.constraints