cloup
¶
Top-level package for cloup.
Subpackages¶
Classes summary¶
|
A click.Option with an extra field |
|
|
|
Implements support to option groups. |
|
A group of (sub)commands to show in the same help section of a |
|
Old name of Section when the implementation of the feature was hard-coded and tightly coupled to |
|
Adds to a click.MultiCommand the possibility to organize its subcommands in multiple help sections. |
|
A |
|
A |
|
A |
|
Provides support to constraints. |
Functions Summary¶
|
|
|
Attaches an option group to the command. This decorator is overloaded with two signatures::. |
|
Decorator that creates a new command using the wrapped function as callback. |
|
Creates a new |
|
Registers a constraint. |
Contents¶
-
cloup.
__email__
= gianluca.gippetto@gmail.com¶
-
cloup.
__version__
= 0.5.0¶
-
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
name (str) –
help (Optional[str]) –
constraint (Optional[cloup.constraints._core.Constraint]) –
-
get_help_records
(self, ctx: click.Context)[source]¶
-
__getitem__
(self, i: int) → click.Option[source]¶
-
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
group (Optional[cloup._option_groups.OptionGroup]) –
cls (Type[click.core.Option]) –
- 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 fromSectionMixin
.Changed in version 0.5.0: This class was renamed from
GroupSection
(deprecated) toSection
.- Parameters
-
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]¶
-
class
cloup.
GroupSection
(*args, **kwargs)[source]¶ Bases:
cloup._sections.Section
Old name of Section when the implementation of the feature was hard-coded and tightly coupled to
cloup.Group
.Deprecated since version 0.5.0: To be removed in v0.6.0. Use
Section
instead.
-
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:
passing a list of
Section
objects to the constructor setting the argumentsections
using
add_section()
to add a single sectionusing
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
commands (Optional[Dict[str, click.core.Command]]) –
sections (Iterable[cloup._sections.Section]) –
align_sections (bool) –
-
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 mixingclick.Command
withcloup.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 typecloup.Command
.This class is just a
click.Group
mixed withSectionMixin
that overrides the decoratorscommand()
andgroup()
so that asection
for the created subcommand can be specified.See the docstring of the two superclasses for more details.
- Parameters
name (Optional[str]) –
commands (Optional[Dict[str, click.core.Command]]) –
sections (Iterable[cloup._sections.Section]) –
align_sections (bool) –
-
command
(self, name: Optional[str] = None, section: Optional[Section] = None, cls: Optional[Type[click.Command]] = None, **attrs)[source]¶ Creates a new command and adds it to this group.
-
group
(self, name: Optional[str] = None, section: Optional[Section] = None, cls: Optional[Type[click.Group]] = None, **attrs)[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 intoadd_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 typecloup.Command
.This class is just a
click.MultiCommand
mixed withSectionMixin
. See the docstring of the two superclasses for more details.
-
cloup.
command
(name: Optional[str] = None, cls: Type[click.Command] = 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()
-
cloup.
group
(name: Optional[str] = None, cls: Type[click.Group] = Group, **attrs)[source]¶ Creates a new
Group
using the decorated function as callback. This is just a convenience function equivalent to:click.group(name, cls=cloup.Group, **attrs)
- Parameters
name (Optional[str]) – name of the command
cls (Type[click.core.Group]) – type of Group
attrs – any argument you can pass to
click.group()
-
class
cloup.
ConstraintMixin
(*args, constraints: Sequence[BoundConstraintSpec] = (), show_constraints: bool = False, **kwargs)[source]¶ Provides support to constraints.
- Parameters
constraints (Sequence[cloup.constraints._support.BoundConstraintSpec]) –
show_constraints (bool) –
-
get_param_by_name
(self, name: str) → click.Parameter[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
constr (cloup.constraints._core.Constraint) –
params (Iterable[str]) –