cloup._context

Classes

Context(*ctx_args[, align_option_groups, …])

A custom context for Cloup.

Contents

class cloup._context.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)[source]

Bases: click.Context

A custom context for Cloup.

Look up click.Context for the list of all arguments.

New in version 0.9.0: added the check_constraints_consistency parameter.

New in version 0.8.0.

Parameters

  • ctx_args (Any) – arguments forwarded to click.Context.

  • align_option_groups (Optional[bool]) – 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).

  • align_sections (Optional[bool]) – 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).

  • show_subcommand_aliases (Optional[bool]) – whether to show the aliases of subcommands in the help of a cloup.Group.

  • show_constraints (Optional[bool]) – whether to include a “Constraint” section in the command help (if at least one constraint is defined).

  • check_constraints_consistency (Optional[bool]) – enable additional checks for constraints which detects mistakes of the developer (see cloup.Constraint.check_consistency()).

  • formatter_settings (Dict[str, Any]) – keyword arguments forwarded to 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 HelpFormatter.settings() to create this dictionary, so that you can be guided by your IDE.

  • ctx_kwargs (Any) – keyword arguments forwarded to click.Context.

formatter_class :Type[cloup.formatting.HelpFormatter]
get_formatter_settings(self)[source]
Return type

Dict[str, Any]

make_formatter(self)[source]

Creates the HelpFormatter for the help and usage output.

To quickly customize the formatter class used without overriding this method, set the formatter_class attribute.

Changed in version 8.0: Added the formatter_class attribute.

Return type

cloup.formatting.HelpFormatter

static 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)[source]

Utility method for creating a context_settings dictionary.

Parameters

  • auto_envvar_prefix (cloup.typing.Possibly[str]) – 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.

  • default_map (cloup.typing.Possibly[Dict[str, Any]]) – a dictionary (like object) with default values for parameters.

  • terminal_width (cloup.typing.Possibly[int]) – 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.

  • max_content_width (cloup.typing.Possibly[int]) – 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.

  • resilient_parsing (cloup.typing.Possibly[bool]) – 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.

  • allow_extra_args (cloup.typing.Possibly[bool]) – 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.

  • allow_interspersed_args (cloup.typing.Possibly[bool]) – if this is set to False then options and arguments cannot be mixed. The default is to inherit from the command.

  • ignore_unknown_options (cloup.typing.Possibly[bool]) – instructs click to ignore options it does not know and keeps them for later processing.

  • help_option_names (cloup.typing.Possibly[List[str]]) – optionally a list of strings that define how the default help parameter is named. The default is ['--help'].

  • token_normalize_func (cloup.typing.Possibly[Callable[[str], str]]) – an optional function that is used to normalize tokens (options, choices, etc.). This for instance can be used to implement case-insensitive behavior.

  • color (cloup.typing.Possibly[bool]) – 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.

  • show_default (cloup.typing.Possibly[bool]) – Show defaults for all options. If not set, defaults to the value from a parent context. Overrides an option’s show_default argument.

  • align_option_groups (cloup.typing.Possibly[bool]) – 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).

  • align_sections (cloup.typing.Possibly[bool]) – 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).

  • show_subcommand_aliases (cloup.typing.Possibly[bool]) – whether to show the aliases of subcommands in the help of a cloup.Group.

  • show_constraints (cloup.typing.Possibly[bool]) – whether to include a “Constraint” section in the command help (if at least one constraint is defined).

  • check_constraints_consistency (cloup.typing.Possibly[bool]) – enable additional checks for constraints which detects mistakes of the developer (see cloup.Constraint.check_consistency()).

  • formatter_settings (cloup.typing.Possibly[Dict[str, Any]]) – keyword arguments forwarded to 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 HelpFormatter.settings() to create this dictionary, so that you can be guided by your IDE.

Return type

Dict[str, Any]