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_constraints=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.8.0.

Parameters

  • ctx_args – arguments forwarded to click.Context.

  • ctx_kwargs – keyword arguments forwarded to click.Context.

  • 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).

  • 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).

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

  • formatter_settings – 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.opts() to create this dictionary, so that you can be guided by your IDE.

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=None, default_map=None, terminal_width=None, max_content_width=None, resilient_parsing=None, allow_extra_args=None, allow_interspersed_args=None, ignore_unknown_options=None, help_option_names=None, token_normalize_func=None, color=None, show_default=None, align_option_groups=None, align_sections=None, show_constraints=None, formatter_settings=None)[source]

Utility method for creating a context_settings dictionary.

Parameters

  • auto_envvar_prefix (Optional[bool]) – 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 (Optional[Dict[str, Any]]) – a dictionary (like object) with default values for parameters.

  • terminal_width (Optional[int]) – the width of the terminal. The default is inherit from parent context. If no context defines the terminal width then auto detection will be applied.

  • max_content_width (Optional[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 (Optional[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 (Optional[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 (Optional[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 (Optional[bool]) – instructs click to ignore options it does not know and keeps them for later processing.

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

  • token_normalize_func (Optional[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 (Optional[bool]) – controls if the terminal supports ANSI colors or not. The default is autodetection. 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 (Optional[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 (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_constraints (Optional[bool]) – whether to include a “Constraint” section in the command help (if at least one constraint is defined).

  • formatter_settings (Optional[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.opts() to create this dictionary, so that you can be guided by your IDE.

Return type

Dict[str, Any]