:mod:`cloup` ============ .. py:module:: cloup .. autoapi-nested-parse:: Top-level package for cloup. Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 2 constraints formatting Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 styling types typing warnings Classes ------- .. autosummary:: ~cloup.HelpTheme ~cloup.Style ~cloup.Color ~cloup.HelpFormatter ~cloup.HelpSection ~cloup.Context ~cloup.Argument ~cloup.Option ~cloup.OptionGroup ~cloup.OptionGroupMixin ~cloup.Section ~cloup.SectionMixin ~cloup.Command ~cloup.Group ~cloup.ConstraintMixin Functions --------- .. autosummary:: ~cloup.get_current_context ~cloup.pass_context ~cloup.argument ~cloup.option ~cloup.option_group ~cloup.command ~cloup.group ~cloup.constrained_params ~cloup.constraint ~cloup.dir_path ~cloup.file_path ~cloup.path Contents -------- .. py:class:: HelpTheme A collection of styles for several elements of the help page. A "style" is just a function or a callable that takes a string and returns a styled version of it. This means you can use your favorite styling/color library (like rich, colorful etc). Nonetheless, given that Click has some basic styling functionality built-in, Cloup provides the :class:`Style` class, which is a wrapper of the ``click.style`` function. :param invoked_command: Style of the invoked command name (in Usage). :param command_help: Style of the invoked command description (below Usage). :param heading: Style of help section headings. :param constraint: Style of an option group constraint description. :param section_help: Style of the help text of a section (the optional paragraph below the heading). :param col1: Style of the first column of a definition list (options and command names). :param col2: Style of the second column of a definition list (help text). :param epilog: Style of the epilog. :param alias: Style of subcommand aliases in a definition lists. :param alias_secondary: Style of separator and eventual parenthesis/brackets in subcommand alias lists. If not provided, the ``alias`` style will be used. .. py:attribute:: invoked_command :annotation: :IStyle Style of the invoked command name (in Usage). .. py:attribute:: command_help :annotation: :IStyle Style of the invoked command description (below Usage). .. py:attribute:: heading :annotation: :IStyle Style of help section headings. .. py:attribute:: constraint :annotation: :IStyle Style of an option group constraint description. .. py:attribute:: section_help :annotation: :IStyle Style of the help text of a section (the optional paragraph below the heading). .. py:attribute:: col1 :annotation: :IStyle Style of the first column of a definition list (options and command names). .. py:attribute:: col2 :annotation: :IStyle Style of the second column of a definition list (help text). .. py:attribute:: alias :annotation: :IStyle Style of subcommand aliases in a definition lists. .. py:attribute:: alias_secondary :annotation: :Optional[IStyle] Style of separator and eventual parenthesis/brackets in subcommand alias lists. If not provided, the ``alias`` style will be used. .. py:attribute:: epilog :annotation: :IStyle Style of the epilog. .. py:method:: with_(self, invoked_command = None, command_help = None, heading = None, constraint = None, section_help = None, col1 = None, col2 = None, alias = None, alias_secondary = MISSING, epilog = None) .. py:method:: dark() :staticmethod: A theme assuming a dark terminal background color. .. py:method:: light() :staticmethod: A theme assuming a light terminal background color. .. py:class:: Style Wraps :func:`click.style` for a better integration with :class:`HelpTheme`. Available colors are defined as static constants in :class:`Color`. Arguments are set to ``None`` by default. Passing ``False`` to boolean args or ``Color.reset`` as color causes a reset code to be inserted. With respect to :func:`click.style`, this class: - has an argument less, ``reset``, which is always ``True`` - add the ``text_transform``. .. warning:: The arguments ``overline``, ``italic`` and ``strikethrough`` are only supported in Click 8 and will be ignored if you are using Click 7. :param fg: foreground color :param bg: background color :param bold: :param dim: :param underline: :param overline: :param italic: :param blink: :param reverse: :param strikethrough: :param text_transform: a generic string transformation; useful to apply functions like ``str.upper`` .. versionadded:: 0.8.0 .. py:attribute:: fg :annotation: :Optional[str] .. py:attribute:: bg :annotation: :Optional[str] .. py:attribute:: bold :annotation: :Optional[bool] .. py:attribute:: dim :annotation: :Optional[bool] .. py:attribute:: underline :annotation: :Optional[bool] .. py:attribute:: overline :annotation: :Optional[bool] .. py:attribute:: italic :annotation: :Optional[bool] .. py:attribute:: blink :annotation: :Optional[bool] .. py:attribute:: reverse :annotation: :Optional[bool] .. py:attribute:: strikethrough :annotation: :Optional[bool] .. py:attribute:: text_transform :annotation: :Optional[IStyle] .. py:method:: __call__(self, text) .. py:class:: Color Bases: :py:obj:`cloup._util.FrozenSpace` Colors accepted by :class:`Style` and :func:`click.style`. .. py:attribute:: black :annotation: = black .. py:attribute:: red :annotation: = red .. py:attribute:: green :annotation: = green .. py:attribute:: yellow :annotation: = yellow .. py:attribute:: blue :annotation: = blue .. py:attribute:: magenta :annotation: = magenta .. py:attribute:: cyan :annotation: = cyan .. py:attribute:: white :annotation: = white .. py:attribute:: reset :annotation: = reset .. py:attribute:: bright_black :annotation: = bright_black .. py:attribute:: bright_red :annotation: = bright_red .. py:attribute:: bright_green :annotation: = bright_green .. py:attribute:: bright_yellow :annotation: = bright_yellow .. py:attribute:: bright_blue :annotation: = bright_blue .. py:attribute:: bright_magenta :annotation: = bright_magenta .. py:attribute:: bright_cyan :annotation: = bright_cyan .. py:attribute:: bright_white :annotation: = bright_white .. py:class:: HelpFormatter(indent_increment = 2, width = None, max_width = None, col1_max_width = 30, col2_min_width = 35, col_spacing = 2, row_sep = None, theme = HelpTheme()) Bases: :py:obj:`click.HelpFormatter` A custom help formatter. Features include: - more attributes for controlling the output of the formatter - a ``col1_width`` parameter in :meth:`write_dl` that allows Cloup to align multiple definition lists without resorting to hacks - a "linear layout" for definition lists that kicks in when the available terminal width is not enough for the standard 2-column layout (see argument ``col2_min_width``) - the first column width, when not explicitly given in ``write_dl`` is computed excluding the rows that exceed ``col1_max_width`` (called ``col_max`` in ``write_dl`` for compatibility with Click). .. versionchanged:: 0.9.0 the ``row_sep`` parameter now: - is set to ``None`` by default and ``row_sep=""`` corresponds to an empty line between rows - must not ends with ``\n``; the formatter writes a newline just after it (when it's not ``None``), so a newline at the end is always enforced - accepts instances of :class:`~cloup.formatting.sep.SepGenerator` and :class:`~cloup.formatting.sep.RowSepPolicy`. .. versionadded:: 0.8.0 :param indent_increment: width of each indentation increment. :param width: content line width, excluding the newline character; by default it's initialized to ``min(terminal_width - 1, max_width)`` where ``max_width`` is another argument. :param max_width: maximum content line width (equivalent to ``Context.max_content_width``). Used to compute ``width`` when it is not provided, ignored otherwise. :param col1_max_width: the maximum width of the first column of a definition list; as in Click, if the text of a row exceeds this threshold, the 2nd column is printed on a new line. :param col2_min_width: the minimum width for the second column of a definition list; if the available space is less than this value, the formatter switches from the standard 2-column layout to the "linear layout" (that this decision is taken for each definition list). If you want to always use the linear layout, you can set this argument to a very high number (or ``math.inf``). If you never want it (not recommended), you can set this argument to zero. :param col_spacing: the number of spaces between the column boundaries of a definition list. :param row_sep: an "extra" separator to insert between the rows of a definition list (in addition to the normal newline between definitions). If you want an empty line between rows, pass ``row_sep=""``. Read :ref:`Row separators ` for more. :param theme: an :class:`~cloup.HelpTheme` instance specifying how to style the various elements of the help page. .. py:method:: settings(width = MISSING, max_width = MISSING, indent_increment = MISSING, col1_max_width = MISSING, col2_min_width = MISSING, col_spacing = MISSING, row_sep = MISSING, theme = MISSING) :staticmethod: A utility method for creating a ``formatter_settings`` dictionary to pass as context settings or command attribute. This method exists for one only reason: it enables auto-complete for formatter options, thus improving the developer experience. Parameters are described in :class:`HelpFormatter`. .. py:method:: available_width(self) :property: .. py:method:: write(self, *strings) Writes a unicode string into the internal buffer. .. py:method:: write_usage(self, prog, args = '', prefix = None) Writes a usage line into the buffer. :param prog: the program name. :param args: whitespace separated list of arguments. :param prefix: The prefix for the first line. Defaults to ``"Usage: "``. .. py:method:: write_aliases(self, aliases) .. py:method:: write_command_help_text(self, cmd) .. py:method:: write_heading(self, heading, newline = True) Writes a heading into the buffer. .. py:method:: write_many_sections(self, sections, aligned = True) .. py:method:: write_aligned_sections(self, sections) Write multiple aligned definition lists. .. py:method:: write_section(self, s, col1_width = None) .. py:method:: write_text(self, text, style = identity) Writes re-indented text into the buffer. This rewraps and preserves paragraphs. .. py:method:: compute_col1_width(self, rows, max_width) .. py:method:: write_dl(self, rows, col_max = None, col_spacing = None, col1_width = None) Write a definition list into the buffer. This is how options and commands are usually formatted. If there's enough space, definition lists are rendered as a 2-column pseudo-table: if the first column text of a row doesn't fit in the provided/computed ``col1_width``, the 2nd column is printed on the following line. If the available space for the 2nd column is below ``self.col2_min_width``, the 2nd "column" is always printed below the 1st, indented with a minimum of 3 spaces (or one ``indent_increment`` if that's greater than 3). :param rows: a list of two item tuples for the terms and values. :param col_max: the maximum width for the 1st column of a definition list; this argument is here to not break compatibility with Click; if provided, it overrides the attribute ``self.col1_max_width``. :param col_spacing: number of spaces between the first and second column; this argument is here to not break compatibility with Click; if provided, it overrides ``self.col_spacing``. :param col1_width: the width to use for the first column; if not provided, it's computed as the length of the longest string under ``self.col1_max_width``; useful when you need to align multiple definition lists. .. py:method:: write_tabular_dl(self, rows, col1_width, col_spacing, col2_width) Format a definition list as a 2-column "pseudo-table". If the first column of a row exceeds ``col1_width``, the 2nd column is written on the subsequent line. This is the standard way of formatting definition lists and it's the default if there's enough space. .. py:method:: write_linear_dl(self, dl) Format a definition list as a "linear list". This is the default when the available width for the definitions (2nd column) is below ``self.col2_min_width``. .. py:method:: write_epilog(self, epilog) .. py:method:: __repr__(self) Return repr(self). .. py:class:: HelpSection A container for a help section data. .. py:attribute:: heading :annotation: :str Help section title. .. py:attribute:: definitions :annotation: :Sequence[Definition] Rows with 2 columns each. The 2nd element of each row can also be a function taking an integer (the available width for the 2nd column) and returning a string. .. py:attribute:: help :annotation: :Optional[str] (Optional) long description of the section. .. py:attribute:: constraint :annotation: :Optional[str] (Optional) option group constraint description. .. py:class:: Context(*ctx_args, align_option_groups = None, align_sections = None, show_subcommand_aliases = None, show_constraints = None, check_constraints_consistency = None, formatter_settings = {}, **ctx_kwargs) Bases: :py:obj:`click.Context` A custom context for Cloup. Look up :class:`click.Context` for the list of all arguments. .. versionadded:: 0.9.0 added the ``check_constraints_consistency`` parameter. .. versionadded:: 0.8.0 :param ctx_args: arguments forwarded to :class:`click.Context`. :param align_option_groups: if True, align the definition lists of all option groups of a command. You can override this by setting the corresponding argument of ``Command`` (but you probably shouldn't: be consistent). :param align_sections: if True, align the definition lists of all subcommands of a group. You can override this by setting the corresponding argument of ``Group`` (but you probably shouldn't: be consistent). :param show_subcommand_aliases: whether to show the aliases of subcommands in the help of a ``cloup.Group``. :param show_constraints: whether to include a "Constraint" section in the command help (if at least one constraint is defined). :param check_constraints_consistency: enable additional checks for constraints which detects mistakes of the developer (see :meth:`cloup.Constraint.check_consistency`). :param formatter_settings: keyword arguments forwarded to :class:`HelpFormatter` in ``make_formatter``. This args are merged with those of the (eventual) parent context and then merged again (being overridden) by those of the command. **Tip**: use the static method :meth:`HelpFormatter.settings` to create this dictionary, so that you can be guided by your IDE. :param ctx_kwargs: keyword arguments forwarded to :class:`click.Context`. .. py:attribute:: formatter_class :annotation: :Type[cloup.formatting.HelpFormatter] .. py:method:: get_formatter_settings(self) .. py:method:: make_formatter(self) Creates the :class:`~click.HelpFormatter` for the help and usage output. To quickly customize the formatter class used without overriding this method, set the :attr:`formatter_class` attribute. .. versionchanged:: 8.0 Added the :attr:`formatter_class` attribute. .. py:method:: settings(auto_envvar_prefix = MISSING, default_map = MISSING, terminal_width = MISSING, max_content_width = MISSING, resilient_parsing = MISSING, allow_extra_args = MISSING, allow_interspersed_args = MISSING, ignore_unknown_options = MISSING, help_option_names = MISSING, token_normalize_func = MISSING, color = MISSING, show_default = MISSING, align_option_groups = MISSING, align_sections = MISSING, show_subcommand_aliases = MISSING, show_constraints = MISSING, check_constraints_consistency = MISSING, formatter_settings = MISSING) :staticmethod: Utility method for creating a ``context_settings`` dictionary. :param auto_envvar_prefix: the prefix to use for automatic environment variables. If this is `None` then reading from environment variables is disabled. This does not affect manually set environment variables which are always read. :param default_map: a dictionary (like object) with default values for parameters. :param terminal_width: the width of the terminal. The default is inherited from parent context. If no context defines the terminal width then auto-detection will be applied. :param max_content_width: the maximum width for content rendered by Click (this currently only affects help pages). This defaults to 80 characters if not overridden. In other words: even if the terminal is larger than that, Click will not format things wider than 80 characters by default. In addition to that, formatters might add some safety mapping on the right. :param resilient_parsing: if this flag is enabled then Click will parse without any interactivity or callback invocation. Default values will also be ignored. This is useful for implementing things such as completion support. :param allow_extra_args: if this is set to `True` then extra arguments at the end will not raise an error and will be kept on the context. The default is to inherit from the command. :param allow_interspersed_args: if this is set to `False` then options and arguments cannot be mixed. The default is to inherit from the command. :param ignore_unknown_options: instructs click to ignore options it does not know and keeps them for later processing. :param help_option_names: optionally a list of strings that define how the default help parameter is named. The default is ``['--help']``. :param token_normalize_func: an optional function that is used to normalize tokens (options, choices, etc.). This for instance can be used to implement case-insensitive behavior. :param color: controls if the terminal supports ANSI colors or not. The default is auto-detection. This is only needed if ANSI codes are used in texts that Click prints which is by default not the case. This for instance would affect help output. :param show_default: Show defaults for all options. If not set, defaults to the value from a parent context. Overrides an option's ``show_default`` argument. :param align_option_groups: if True, align the definition lists of all option groups of a command. You can override this by setting the corresponding argument of ``Command`` (but you probably shouldn't: be consistent). :param align_sections: if True, align the definition lists of all subcommands of a group. You can override this by setting the corresponding argument of ``Group`` (but you probably shouldn't: be consistent). :param show_subcommand_aliases: whether to show the aliases of subcommands in the help of a ``cloup.Group``. :param show_constraints: whether to include a "Constraint" section in the command help (if at least one constraint is defined). :param check_constraints_consistency: enable additional checks for constraints which detects mistakes of the developer (see :meth:`cloup.Constraint.check_consistency`). :param formatter_settings: keyword arguments forwarded to :class:`HelpFormatter` in ``make_formatter``. This args are merged with those of the (eventual) parent context and then merged again (being overridden) by those of the command. **Tip**: use the static method :meth:`HelpFormatter.settings` to create this dictionary, so that you can be guided by your IDE. .. py:function:: get_current_context() -> Context get_current_context(silent: bool = False) -> Optional[Context] Equivalent to :func:`click.get_current_context` but casts the returned :class:`click.Context` object to :class:`cloup.Context` (which is safe when using cloup commands classes and decorators). .. py:function:: pass_context(f) Marks a callback as wanting to receive the current context object as first argument. Equivalent to :func:`click.pass_context` but assumes the current context is of type :class:`cloup.Context`. .. py:class:: Argument(*args, help=None, **attrs) Bases: :py:obj:`click.Argument` A :class:`click.Argument` with help text. .. py:method:: get_help_record(self, ctx) .. py:class:: Option(*args, group=None, **attrs) Bases: :py:obj:`click.Option` A :class:`click.Option` with an extra field ``group`` of type ``OptionGroup``. .. py:function:: argument(*param_decls, cls=None, **attrs) .. py:function:: option(*param_decls, cls=None, group=None, **attrs) Attach an ``Option`` to the command. Refer to :class:`click.Option` and :class:`click.Parameter` for more info about the accepted parameters. In your IDE, you won't see arguments relating to shell completion, because they are different in Click 7 and 8 (both supported by Cloup): - in Click 7, it's ``autocompletion`` - in Click 8, it's ``shell_complete``. These arguments have different semantics, refer to Click's docs. .. py:class:: OptionGroup(title, help = None, constraint = None, hidden = False) Contains the information of an option group and identifies it. Note that, as far as the clients of this library are concerned, an ``OptionGroups`` acts as a "marker" for options, not as a container for related options. When you call ``@optgroup.option(...)`` you are not adding an option to a container, you are just adding an option marked with this option group. .. versionadded:: 0.8.0 The ``hidden`` parameter. .. py:method:: options(self) :property: .. py:method:: get_help_records(self, ctx) .. py:method:: option(self, *param_decls, **attrs) Refer to :func:`cloup.option`. .. py:method:: __iter__(self) .. py:method:: __getitem__(self, i) .. py:method:: __len__(self) .. py:method:: __repr__(self) Return repr(self). .. py:method:: __str__(self) Return str(self). .. py:class:: OptionGroupMixin(*args, align_option_groups = None, **kwargs) Implements support for: - option groups - the "Positional arguments" help section; this section is shown only if at least one of your arguments has non-empty ``help``. .. important:: In order to check the constraints defined on the option groups, a command must inherits from :class:`cloup.ConstraintMixin` too! .. versionadded:: 0.14.0 added the "Positional arguments" help section. .. versionchanged:: 0.8.0 this mixin now relies on ``cloup.HelpFormatter`` to align help sections. If a ``click.HelpFormatter`` is used with a ``TypeError`` is raised. .. versionchanged:: 0.8.0 removed ``format_option_group``. Added ``get_default_option_group`` and ``make_option_group_help_section``. .. versionadded:: 0.5.0 :param align_option_groups: whether to align the columns of all option groups' help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only. :param args: positional arguments forwarded to the next class in the MRO :param kwargs: keyword arguments forwarded to the next class in the MRO .. py:attribute:: option_groups List of all option groups, except the "default option group". .. py:attribute:: ungrouped_options List of options not explicitly assigned to an user-defined option group. These options will be included in the "default option group". **Note:** this list does not include options added automatically by Click based on context settings, like the ``--help`` option; use the :meth:`get_ungrouped_options` method if you need the real full list (which needs a ``Context`` object). .. py:method:: get_ungrouped_options(self, ctx) Return options not explicitly assigned to an option group (eventually including the ``--help`` option), i.e. options that will be part of the "default option group". .. py:method:: get_argument_help_record(self, arg, ctx) .. py:method:: get_arguments_help_section(self, ctx) .. py:method:: make_option_group_help_section(self, group, ctx) Return a ``HelpSection`` for an ``OptionGroup``, i.e. an object containing the title, the optional description and the options' definitions for this option group. .. versionadded:: 0.8.0 .. py:method:: must_align_option_groups(self, ctx, default = True) Return ``True`` if the help sections of all options groups should have their columns aligned. .. versionadded:: 0.8.0 .. py:method:: get_default_option_group(self, ctx, is_the_only_visible_option_group = False) Return an ``OptionGroup`` instance for the options not explicitly assigned to an option group, eventually including the ``--help`` option. .. versionadded:: 0.8.0 .. py:method:: format_params(self, ctx, formatter) .. py:function:: option_group(title: str, help: str, *options: cloup.typing.Decorator, constraint: Optional[cloup.constraints.Constraint] = None, hidden: bool = False) -> Callable[[cloup.typing.F], cloup.typing.F] option_group(title: str, *options: cloup.typing.Decorator, help: Optional[str] = None, constraint: Optional[cloup.constraints.Constraint] = None, hidden: bool = False) -> Callable[[cloup.typing.F], cloup.typing.F] Return a decorator that annotates a function with an option group. The ``help`` argument is an optional description and can be provided either as keyword argument or as 2nd positional argument after the ``name`` of the group:: # help as keyword argument @option_group(name, *options, help=None, ...) # help as 2nd positional argument @option_group(name, help, *options, ...) .. versionchanged:: 0.9.0 in order to support the decorator :func:`cloup.constrained_params`, ``@option_group`` now allows each input decorators to add multiple options. :param title: title of the help section describing the option group. :param help: an optional description shown below the name; can be provided as keyword argument or 2nd positional argument. :param options: an arbitrary number of decorators like ``click.option``, which attach one or multiple options to the decorated command function. :param constraint: an optional instance of :class:`~cloup.constraints.Constraint` (see :doc:`Constraints ` for more info); a description of the constraint will be shown between squared brackets aside the option group title (or below it if too long). :param hidden: if ``True``, the option group and all its options are hidden from the help page (all contained options will have their ``hidden`` attribute set to ``True``). .. py:class:: Section(title, commands = (), is_sorted = 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``. :param title: :param commands: sequence of commands or dict of commands keyed by name :param is_sorted: if True, ``list_commands()`` returns the commands in lexicographic order .. py:method:: sorted(cls, title, commands = ()) :classmethod: .. py:method:: add_command(self, cmd, name = None) .. py:method:: list_commands(self) .. py:method:: __len__(self) .. py:method:: __repr__(self) Return repr(self). .. py:class:: SectionMixin(*args, commands = None, sections = (), align_sections = None, **kwargs) Adds to a :class:`click.MultiCommand` the possibility of organizing its subcommands into 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. .. versionchanged:: 0.8.0 this mixin now relies on ``cloup.HelpFormatter`` to align help sections. If a ``click.HelpFormatter`` is used with a ``TypeError`` is raised. .. versionchanged:: 0.8.0 removed ``format_section``. Added ``make_commands_help_section``. .. versionadded:: 0.5.0 :param align_sections: whether to align the columns of all subcommands' help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only. :param args: positional arguments forwarded to the next class in the MRO :param kwargs: keyword arguments forwarded to the next class in the MRO .. py:method:: add_section(self, section) Add a :class:`Section` to this group. You can add the same section object only a single time. See Also: :meth:`section` .. py:method:: section(self, title, *commands, **attrs) Create a new :class:`Section`, adds it to this group and returns it. .. py:method:: add_command(self, cmd, name = None, section = None, fallback_to_default_section = True) Add a subcommand to this ``Group``. **Implementation note:** ``fallback_to_default_section`` looks not very clean but, even if it's not immediate to see (it wasn't for me), I chose it over apparently cleaner options. :param cmd: :param name: :param section: a ``Section`` instance. The command must not be in the section already. :param fallback_to_default_section: if ``section`` is None and this option is enabled, the command is added to the "default section". If disabled, the command is not added to any section unless ``section`` is provided. This is useful for internal code and subclasses. Don't disable it unless you know what you are doing. .. py:method:: list_sections(self, ctx, include_default_section = True) Return 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. .. py:method:: format_subcommand_name(self, ctx, name, cmd) Used to format the name of the subcommands. This method is useful when you combine this extension with other click extensions that override :meth:`format_commands`. Most of these, like click-default-group, just add something to the name of the subcommands, which is exactly what this method allows you to do without overriding bigger methods. .. py:method:: make_commands_help_section(self, ctx, section) .. py:method:: must_align_sections(self, ctx, default = True) .. py:method:: format_commands(self, ctx, formatter) .. py:class:: Command(*args, aliases = None, formatter_settings = None, **kwargs) Bases: :py:obj:`cloup.constraints.ConstraintMixin`, :py:obj:`cloup._option_groups.OptionGroupMixin`, :py:obj:`click.Command` A ``click.Command`` supporting option groups and constraints. Refer to superclasses for the documentation of all accepted parameters: - :class:`ConstraintMixin` - :class:`OptionGroupMixin` - :class:`click.Command` Besides other things, this class also: * adds a ``formatter_settings`` instance attribute. Refer to :class:`click.Command` for the documentation of all parameters. .. versionadded:: 0.8.0 :param constraints: sequence of constraints bound to specific groups of parameters. Note that constraints applied to option groups are collected from the option groups themselves, so they don't need to be included in this argument. :param show_constraints: whether to include a "Constraint" section in the command help. This is also available as a context setting having a lower priority than this attribute. :param args: positional arguments forwarded to the next class in the MRO :param kwargs: keyword arguments forwarded to the next class in the MRO .. py:attribute:: context_class :annotation: :Type[cloup._context.Context] .. py:method:: get_normalized_epilog(self) .. py:method:: format_epilog(self, ctx, formatter) Writes the epilog into the formatter if it exists. .. py:method:: format_help_text(self, ctx, formatter) Writes the help text to the formatter if it exists. .. py:method:: format_aliases(self, ctx, formatter) .. py:method:: format_help(self, ctx, formatter) Writes the help into the formatter if it exists. This is a low-level method called by :meth:`get_help`. This calls the following methods: - :meth:`format_usage` - :meth:`format_help_text` - :meth:`format_options` - :meth:`format_epilog` .. py:class:: Group(*args, show_subcommand_aliases = None, commands = None, **kwargs) Bases: :py:obj:`cloup._sections.SectionMixin`, :py:obj:`Command`, :py:obj:`click.Group` A ``click.Group`` that allows to organize its subcommands in multiple help sections and whose subcommands are, by default, of type :class:`cloup.Command`. Refer to superclasses for the documentation of all accepted parameters: - :class:`SectionMixin` - :class:`Command` - :class:`click.Group` Apart from superclasses arguments, the following is the only additional parameter: ``show_subcommand_aliases``: ``Optional[bool] = None`` whether to show subcommand aliases; aliases are shown by default and can be disabled using this argument or the homonym context setting. .. versionchanged:: 0.14.0 this class now supports option groups and constraints. .. versionadded:: 0.10.0 the "command aliases" feature, including the ``show_subcommand_aliases`` parameter/attribute. .. versionchanged:: 0.8.0 this class now inherits from :class:`cloup.BaseCommand`. :param align_sections: whether to align the columns of all subcommands' help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only. :param args: positional arguments forwarded to the next class in the MRO :param kwargs: keyword arguments forwarded to the next class in the MRO .. py:attribute:: SHOW_SUBCOMMAND_ALIASES :annotation: :bool = False .. py:attribute:: show_subcommand_aliases Whether to show subcommand aliases. .. py:attribute:: alias2name :annotation: :Dict[str, str] Dictionary mapping each alias to a command name. .. py:method:: add_multiple_commands(self, commands) .. py:method:: add_command(self, cmd, name = None, section = None, fallback_to_default_section = True) Add a subcommand to this ``Group``. **Implementation note:** ``fallback_to_default_section`` looks not very clean but, even if it's not immediate to see (it wasn't for me), I chose it over apparently cleaner options. :param cmd: :param name: :param section: a ``Section`` instance. The command must not be in the section already. :param fallback_to_default_section: if ``section`` is None and this option is enabled, the command is added to the "default section". If disabled, the command is not added to any section unless ``section`` is provided. This is useful for internal code and subclasses. Don't disable it unless you know what you are doing. .. py:method:: resolve_command_name(self, ctx, name) Map a string supposed to be a command name or an alias to a normalized command name. If no match is found, it returns ``None``. .. py:method:: resolve_command(self, ctx, args) .. py:method:: handle_bad_command_name(self, bad_name, valid_names, error) This method is called when a command name cannot be resolved. Useful to implement the "Did you mean ?" feature. :param bad_name: the command name that could not be resolved. :param valid_names: the list of valid command names, including aliases. :param error: the original error coming from Click. :return: the original error or a new one. .. py:method:: must_show_subcommand_aliases(self, ctx) .. py:method:: format_subcommand_name(self, ctx, name, cmd) Used to format the name of the subcommands. This method is useful when you combine this extension with other click extensions that override :meth:`format_commands`. Most of these, like click-default-group, just add something to the name of the subcommands, which is exactly what this method allows you to do without overriding bigger methods. .. py:method:: format_subcommand_aliases(aliases, theme) :staticmethod: .. py:method:: command(self, name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: None = None, section: Optional[cloup._sections.Section] = None, context_settings: Optional[Dict[str, Any]] = None, formatter_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, align_option_groups: Optional[bool] = None, show_constraints: Optional[bool] = None, params: Optional[List[click.Parameter]] = None) -> Callable[[cloup.typing.AnyCallable], click.Command] command(self, name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: Type[C], section: Optional[cloup._sections.Section] = None, context_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, **kwargs: Any) -> Callable[[cloup.typing.AnyCallable], C] Return a decorator that creates a new subcommand of this ``Group`` using the decorated function as callback. It takes the same arguments of :func:`command` plus: ``section``: ``Optional[Section]`` if provided, put the subcommand in this section. .. versionchanged:: 0.10.0 all arguments but ``name`` are now keyword-only. .. py:method:: group(self, name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: None = None, section: Optional[cloup._sections.Section] = None, sections: Iterable[cloup._sections.Section] = (), align_sections: Optional[bool] = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Optional[Dict[str, Any]] = None, formatter_settings: Dict[str, Any] = {}, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', subcommand_metavar: Optional[str] = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False) -> Callable[[cloup.typing.AnyCallable], click.Group] group(self, name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: Optional[Type[G]] = None, section: Optional[cloup._sections.Section] = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', subcommand_metavar: Optional[str] = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, **kwargs: Any) -> Callable[[cloup.typing.AnyCallable], G] Return a decorator that creates a new subcommand of this ``Group`` using the decorated function as callback. It takes the same argument of :func:`group` plus: ``section``: ``Optional[Section]`` if provided, put the subcommand in this section. .. versionchanged:: 0.10.0 all arguments but ``name`` are now keyword-only. .. py:function:: command(name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: None = None, context_settings: Optional[Dict[str, Any]] = None, formatter_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, short_help: Optional[str] = None, epilog: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, align_option_groups: Optional[bool] = None, show_constraints: Optional[bool] = None, params: Optional[List[click.Parameter]] = None) -> Callable[[cloup.typing.AnyCallable], Command] command(name: Optional[str] = None, *, aliases: Optional[Iterable[str]] = None, cls: Type[C], context_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, short_help: Optional[str] = None, epilog: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, **kwargs: Any) -> Callable[[cloup.typing.AnyCallable], C] Return a decorator that creates a new command using the decorated function as callback. The only differences with respect to ``click.command`` are: - the default command class is :class:`cloup.Command` - supports constraints, provided that ``cls`` inherits from ``ConstraintMixin`` like ``cloup.Command`` (the default) - this function has detailed type hints and uses generics for the ``cls`` argument and return type. Note that the following arguments are about Cloup-specific features and are not supported by all ``click.Command``, so if you provide a custom ``cls`` make sure you don't set these: - ``formatter_settings`` - ``align_option_groups`` (``cls`` needs to inherit from ``OptionGroupMixin``) - ``show_constraints`` (``cls`` needs to inherit ``ConstraintMixin``). .. versionchanged:: 0.10.0 this function is now generic: the return type depends on what you provide as ``cls`` argument. .. versionchanged:: 0.9.0 all arguments but ``name`` are now keyword-only arguments. :param name: the name of the command to use unless a group overrides it. :param aliases: alternative names for this command. If ``cls`` is not a Cloup command class, aliases will be stored in the instantiated command by monkey-patching and aliases won't be documented in the help page of the command. :param cls: the command class to instantiate. :param context_settings: an optional dictionary with defaults that are passed to the context object. :param formatter_settings: arguments for the formatter; you can use :meth:`HelpFormatter.settings` to build this dictionary. :param help: the help string to use for this command. :param epilog: like the help string but it's printed at the end of the help page after everything else. :param short_help: the short help to use for this command. This is shown on the command listing of the parent command. :param options_metavar: metavar for options shown in the command's usage string. :param add_help_option: by default each command registers a ``--help`` option. This can be disabled by this parameter. :param no_args_is_help: this controls what happens if no arguments are provided. This option is disabled by default. If enabled this will add ``--help`` as argument if no arguments are passed :param hidden: hide this command from help outputs. :param deprecated: issues a message indicating that the command is deprecated. :param align_option_groups: whether to align the columns of all option groups' help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only. :param show_constraints: whether to include a "Constraint" section in the command help. This is also available as a context setting having a lower priority than this attribute. :param params: **(click >= 8.1.0)** a list of parameters (:class:`Argument` and :class:`Option` instances). Params added with ``@option`` and ``@argument`` are appended to the end of the list if given. :param kwargs: any other argument accepted by the instantiated command class (``cls``). .. py:function:: group(name: Optional[str] = None, *, cls: None = None, aliases: Optional[Iterable[str]] = None, sections: Iterable[cloup._sections.Section] = (), align_sections: Optional[bool] = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Optional[Dict[str, Any]] = None, formatter_settings: Dict[str, Any] = {}, help: Optional[str] = None, short_help: Optional[str] = None, epilog: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', subcommand_metavar: Optional[str] = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None) -> Callable[[cloup.typing.AnyCallable], Group] group(name: Optional[str] = None, *, cls: Type[G], aliases: Optional[Iterable[str]] = None, invoke_without_command: bool = False, no_args_is_help: bool = False, context_settings: Optional[Dict[str, Any]] = None, help: Optional[str] = None, short_help: Optional[str] = None, epilog: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', subcommand_metavar: Optional[str] = None, add_help_option: bool = True, chain: bool = False, hidden: bool = False, deprecated: bool = False, params: Optional[List[click.Parameter]] = None, **kwargs: Any) -> Callable[[cloup.typing.AnyCallable], G] Return a decorator that instantiates a ``Group`` (or a subclass of it) using the decorated function as callback. .. versionchanged:: 0.10.0 the ``cls`` argument can now be any ``click.Group`` (previously had to be a ``cloup.Group``) and the type of the instantiated command matches it (previously, the type was ``cloup.Group`` even if ``cls`` was a subclass of it). .. versionchanged:: 0.9.0 all arguments but ``name`` are now keyword-only arguments. :param name: the name of the command to use unless a group overrides it. :param cls: the ``click.Group`` (sub)class to instantiate. This is ``cloup.Group`` by default. Note that some of the arguments are only supported by ``cloup.Group``. :param sections: a list of Section objects containing the subcommands of this ``Group``. This argument is only supported by commands inheriting from :class:`cloup.SectionMixin`. :param align_sections: whether to align the columns of all subcommands' help sections. This is also available as a context setting having a lower priority than this attribute. Given that this setting should be consistent across all you commands, you should probably use the context setting only. :param context_settings: an optional dictionary with defaults that are passed to the context object. :param formatter_settings: arguments for the formatter; you can use :meth:`HelpFormatter.settings` to build this dictionary. :param help: the help string to use for this command. :param short_help: the short help to use for this command. This is shown on the command listing of the parent command. :param epilog: like the help string but it's printed at the end of the help page after everything else. :param options_metavar: metavar for options shown in the command's usage string. :param add_help_option: by default each command registers a ``--help`` option. This can be disabled by this parameter. :param hidden: hide this command from help outputs. :param deprecated: issues a message indicating that the command is deprecated. :param invoke_without_command: this controls how the multi command itself is invoked. By default it's only invoked if a subcommand is provided. :param no_args_is_help: this controls what happens if no arguments are provided. This option is enabled by default if `invoke_without_command` is disabled or disabled if it's enabled. If enabled this will add ``--help`` as argument if no arguments are passed. :param subcommand_metavar: string used in the command's usage string to indicate the subcommand place. :param chain: if this is set to `True`, chaining of multiple subcommands is enabled. This restricts the form of commands in that they cannot have optional arguments but it allows multiple commands to be chained together. :param params: **(click >= 8.1.0)** a list of parameters (:class:`Argument` and :class:`Option` instances). Params added with ``@option`` and ``@argument`` are appended to the end of the list if given. :param kwargs: any other argument accepted by the instantiated command class. .. py:class:: ConstraintMixin(*args, constraints = (), show_constraints = None, **kwargs) Provides support for constraints. :param constraints: sequence of constraints bound to specific groups of parameters. Note that constraints applied to option groups are collected from the option groups themselves, so they don't need to be included in this argument. :param show_constraints: whether to include a "Constraint" section in the command help. This is also available as a context setting having a lower priority than this attribute. :param args: positional arguments forwarded to the next class in the MRO :param kwargs: keyword arguments forwarded to the next class in the MRO .. py:attribute:: optgroup_constraints Constraints applied to ``OptionGroup`` instances. .. py:attribute:: param_constraints :annotation: :Tuple[BoundConstraint, Ellipsis] Constraints registered using ``@constraint`` (or equivalent method). .. py:attribute:: all_constraints All constraints applied to parameter/option groups of this command. .. py:method:: parse_args(self, ctx, args) .. py:method:: get_param_by_name(self, name) .. py:method:: get_params_by_name(self, names) .. py:method:: format_constraints(self, ctx, formatter) .. py:method:: must_show_constraints(self, ctx) .. py:function:: constrained_params(constr, *param_adders) Return a decorator that adds the given parameters and applies a constraint to them. Equivalent to:: @param_adders[0] ... @param_adders[-1] @constraint(constr, ) This decorator saves you to manually (re)type the parameter names. It can also be used inside ``@option_group``. Instead of using this decorator, you can also call the constraint itself:: @constr(*param_adders) but remember that: - Python 3.9 is the first that allows arbitrary expressions on the right of ``@``; - using a long conditional/composite constraint as decorator may be less readable. In these cases, you may consider using ``@constrained_params``. .. versionadded:: 0.9.0 :param constr: an instance of :class:`Constraint` :param param_adders: function decorators, each attaching a single parameter to the decorated function. .. py:function:: constraint(constr, params) Register a constraint on a list of parameters specified by (destination) name (e.g. the default name of ``--input-file`` is ``input_file``). .. py:function:: dir_path(path_type = pathlib.Path, exists = False, writable = False, readable = True, resolve_path = False, allow_dash = False) Shortcut for :class:`click.Path` with ``file_okay=False, path_type=pathlib.Path``. .. py:function:: file_path(path_type = pathlib.Path, exists = False, writable = False, readable = True, resolve_path = False, allow_dash = False) Shortcut for :class:`click.Path` with ``dir_okay=False, path_type=pathlib.Path``. .. py:function:: path(path_type = pathlib.Path, exists = False, file_okay = True, dir_okay = True, writable = False, readable = True, resolve_path = False, allow_dash = False) Shortcut for :class:`click.Path` with ``path_type=pathlib.Path``.