:mod:`cloup` ============ .. py:module:: cloup .. autoapi-nested-parse:: Top-level package for cloup. Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 2 constraints/index.rst Classes summary --------------- .. autosummary:: ~cloup.GroupedOption ~cloup.OptionGroup ~cloup.OptionGroupMixin ~cloup.Section ~cloup.SectionMixin ~cloup.Command ~cloup.Group ~cloup.MultiCommand ~cloup.ConstraintMixin Functions Summary ----------------- .. autosummary:: ~cloup.option ~cloup.option_group ~cloup.command ~cloup.group ~cloup.constraint Contents -------- .. data:: __author__ :annotation: = Gianluca Gippetto .. data:: __email__ :annotation: = gianluca.gippetto@gmail.com .. data:: __version__ .. data:: __version_tuple__ .. class:: GroupedOption(*args, group: Optional[OptionGroup] = None, **attrs) Bases: :class:`click.Option` A click.Option with an extra field ``group`` of type OptionGroup .. class:: OptionGroup(name: str, help: Optional[str] = None, constraint: Optional[Constraint] = None) .. method:: get_help_records(self, ctx: click.Context) .. method:: option(self, *param_decls, **attrs) .. method:: __iter__(self) .. method:: __getitem__(self, i: int) -> click.Option .. method:: __len__(self) -> int .. method:: __repr__(self) -> str Return repr(self). .. method:: __str__(self) -> str Return str(self). .. class:: OptionGroupMixin(*args, align_option_groups: bool = True, **kwargs) Implements support to option groups. .. versionadded:: 0.5.0 .. important:: In order to check the constraints defined on the option groups, a command must inherits from :class:`cloup.ConstraintMixin` too! .. method:: get_ungrouped_options(self, ctx: click.Context) -> Sequence[click.Option] .. method:: get_option_group_title(self, ctx: click.Context, opt_group: cloup._option_groups.OptionGroup) -> str .. method:: format_option_group(self, ctx: click.Context, formatter: click.HelpFormatter, opt_group: cloup._option_groups.OptionGroup, help_records: Optional[Sequence] = None) .. method:: format_options(self, ctx: click.Context, formatter: click.HelpFormatter, max_option_width: int = 30) .. function:: option(*param_decls, group: Optional[OptionGroup] = None, cls: Type[click.Option] = GroupedOption, **attrs) -> OptionGroupDecorator .. function:: option_group(name: str, help: str, *options: OptionDecorator, constraint: Optional[Constraint] = None) -> OptionGroupDecorator 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. :param name: a mandatory name/title for the group :param help: an optional help string for the group :param options: option decorators like `click.option` :param constraint: a ``Constraint`` to validate on this option group :return: a decorator that attaches the contained options to the decorated function .. class:: Section(title: str, commands: Subcommands = (), sorted: bool = 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 :class:`SectionMixin`. .. versionchanged:: 0.6.0 Removed the deprecated old name ``GroupSection``. .. versionchanged:: 0.5.0 Introduced the new name ``Section`` and deprecated the old ``GroupSection``. .. method:: sorted(cls, title: str, commands: Subcommands = ()) -> cloup._sections.Section :classmethod: .. method:: add_command(self, cmd: click.Command, name: Optional[str] = None) .. method:: list_commands(self) -> List[Tuple[str, click.Command]] .. method:: __len__(self) -> int .. method:: __repr__(self) -> str Return repr(self). .. class:: SectionMixin(*args, commands: Optional[Dict[str, click.Command]] = None, sections: Iterable[Section] = (), align_sections: bool = True, **kwargs) 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 :class:`Section` objects to the constructor setting the argument ``sections`` #. using :meth:`add_section` to add a single section #. using :meth:`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. .. versionadded:: 0.5.0 .. method:: add_section(self, section: cloup._sections.Section) Adds a :class:`Section` to this group. You can add the same section object a single time. .. method:: section(self, title: str, *commands: click.Command, **attrs) -> cloup._sections.Section Creates a new :class:`Section`, adds it to this group and returns it. .. method:: add_command(self, cmd: click.Command, name: Optional[str] = None, section: Optional[Section] = None) Adds a new command. If ``section`` is None, the command is added to the default section. .. method:: list_sections(self, ctx: click.Context, include_default_section: bool = True) -> List[Section] 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. .. method:: format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) .. method:: format_section(self, ctx: click.Context, formatter: click.HelpFormatter, section: cloup._sections.Section, command_col_width: Optional[int] = None) .. class:: Command(*args, **kwargs) Bases: :class:`cloup.constraints.ConstraintMixin`, :class:`cloup._option_groups.OptionGroupMixin`, :class:`click.Command` A ``click.Command`` supporting option groups and constraints. .. class:: Group(name: Optional[str] = None, commands: Optional[Dict[str, click.Command]] = None, sections: Iterable[Section] = (), align_sections: bool = True, **attrs) Bases: :class:`cloup._sections.SectionMixin`, :class:`click.Group` A ``click.Group`` that allows to organize its subcommands in multiple help sections and and whose subcommands are, by default, of type :class:`cloup.Command`. This class is just a :class:`click.Group` mixed with :class:`SectionMixin` that overrides the decorators :meth:`command` and :meth:`group` so that a ``section`` for the created subcommand can be specified. See the docstring of the two superclasses for more details. .. method:: command(self, name: Optional[str] = None, cls: Optional[Type[click.Command]] = None, section: Optional[Section] = None, **kwargs) -> Callable[([Callable], click.Command)] Creates a new command and adds it to this group. .. method:: group(self, name: Optional[str] = None, cls: Optional[Type[click.Group]] = None, section: Optional[Section] = None, **kwargs) A shortcut decorator for declaring and attaching a group to the group. This takes the same arguments as :func:`group` but immediately registers the created command with this instance by calling into :meth:`add_command`. .. class:: MultiCommand(*args, **kwargs) Bases: :class:`cloup._sections.SectionMixin`, :class:`click.MultiCommand` A ``click.MultiCommand`` that allows to organize its subcommands in multiple help sections and and whose subcommands are, by default, of type :class:`cloup.Command`. This class is just a :class:`click.MultiCommand` mixed with :class:`SectionMixin`. See the docstring of the two superclasses for more details. .. function:: command(name: Optional[str] = None, cls: Type[click.Command] = Command, **attrs) -> Callable[([Callable], click.Command)] 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``. :param name: name of the command :param cls: type of click.Command :param attrs: any argument you can pass to :func:`click.command` .. function:: group(name: Optional[str] = None, cls: Type[Group] = Group, **attrs) -> Callable[([Callable], Group)] Decorator for creating a new :class:`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``. :param name: name of the command :param cls: type of ``cloup.Group`` :param attrs: any argument you can pass to :func:`click.group` .. class:: ConstraintMixin(*args, constraints: Sequence[BoundConstraintSpec] = (), show_constraints: bool = False, **kwargs) Provides support to constraints. .. method:: parse_args(self, ctx, args) .. method:: get_param_by_name(self, name: str) -> click.Parameter .. method:: get_params_by_name(self, names: Iterable[str]) -> List[Parameter] .. method:: format_constraints(self, ctx, formatter) -> None .. method:: format_help(self, ctx, formatter: click.HelpFormatter) -> None .. function:: constraint(constr: cloup.constraints._core.Constraint, params: Iterable[str]) Registers a constraint.