cloup._commands

Classes

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.

Functions

group([name, cls])	Decorator for creating a new Group.
command([name, cls])	Decorator that creates a new command using the wrapped function as callback.

Contents

class cloup._commands.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._commands.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._commands.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._commands.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]

cloup._commands.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]