Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# `cloup._context`

## Classes

`Context`(*ctx_args[, align_option_groups, ...]) | A custom context for Cloup.

## Functions

`get_current_context`([silent]) | Equivalent to `click.get_current_context()` but casts the returned `click.Context` object to `cloup.Context` (which is safe when using cloup commands classes and decorators).
`pass_context`(f) | Marks a callback as wanting to receive the current context object as first argument.

## Attributes

`P` |
`R` |

## Contents

cloup._context.P

cloup._context.R

cloup._context.get_current_context() → Context
cloup._context.get_current_context(silent: bool = False) → Context | None

  Equivalent to `click.get_current_context()` but casts the returned `click.Context` object to `cloup.Context` (which is safe when using cloup commands classes and decorators).

cloup._context.pass_context(f)

  Marks a callback as wanting to receive the current context object as first argument. Equivalent to `click.pass_context()` but assumes the current context is of type `cloup.Context`.

  Parameters:

    f (Callable[te.Concatenate[Context, P], R]) –

  Return type:

    Callable[P, R]

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)

  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()
    Return type:

      Dict[str, Any]

  make_formatter()

    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)

    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]