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

# `cloup.constraints._support`

## Classes

`BoundConstraintSpec`(constraint, param_names) | A NamedTuple storing a `Constraint` and the names of the parameters it has to check.
`BoundConstraint`(constraint, params) | Internal utility `NamedTuple` that represents a `Constraint` bound to a collection of `click.Parameter` instances.
`ConstraintMixin`(*args[, constraints, ...]) | Provides support for constraints.

## Functions

`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`).
`constrained_params`(constr, *param_adders) | Return a decorator that adds the given parameters and applies a constraint to them. Equivalent to::.
`ensure_constraints_support`(command) |

## Contents

class cloup.constraints._support.BoundConstraintSpec

  Bases: `NamedTuple`

  A NamedTuple storing a `Constraint` and the names of the parameters it has to check.

  Parameters:

    - constraint (Constraint) –

    - param_names (Sequence[str]) –

  constraint :cloup.constraints._core.Constraint
  param_names :Union[Sequence[str]]
  resolve_params(cmd)
    Parameters:

      cmd (ConstraintMixin) –

    Return type:

      BoundConstraint

cloup.constraints._support.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`).

  Parameters:

    - constr (Constraint) –

    - params (Iterable[str]) –

  Return type:

    Callable[[F], F]

cloup.constraints._support.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, <param names>)

  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`.

  New in version 0.9.0.

  Parameters:

    - constr (Constraint) – an instance of `Constraint`

    - param_adders (Callable[[Callable[[...], Any]], Callable[[...], Any]]) – function decorators, each attaching a single parameter to the decorated function.

  Return type:

    Callable[[F], F]

class cloup.constraints._support.BoundConstraint

  Bases: `NamedTuple`

  Internal utility `NamedTuple` that represents a `Constraint` bound to a collection of `click.Parameter` instances. Note: this is not a subclass of Constraint.

  Parameters:

    - constraint (Constraint) –

    - params (Sequence[Parameter]) –

  constraint :cloup.constraints._core.Constraint
  params :Sequence[click.Parameter]
  check_consistency()
    Return type:

      None

  check_values(ctx)
    Parameters:

      ctx (click.Context) –

    Return type:

      None

  get_help_record(ctx)
    Parameters:

      ctx (click.Context) –

    Return type:

      Optional[Tuple[str, str]]

class cloup.constraints._support.ConstraintMixin(*args, constraints=(), show_constraints=None, **kwargs)

  Provides support for constraints.

  Parameters:

    - constraints (Sequence[BoundConstraintSpec | BoundConstraint]) – 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.

    - show_constraints (bool | None) – 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.

    - args (Any) – positional arguments forwarded to the next class in the MRO

    - kwargs (Any) – keyword arguments forwarded to the next class in the MRO

  optgroup_constraints

    Constraints applied to `OptionGroup` instances.

  param_constraints :Tuple[BoundConstraint, Ellipsis]

    Constraints registered using `@constraint` (or equivalent method).

  all_constraints

    All constraints applied to parameter/option groups of this command.

  parse_args(ctx, args)
    Parameters:

      - ctx (click.Context) –

      - args (List[str]) –

    Return type:

      List[str]

  get_param_by_name(name)
    Parameters:

      name (str) –

    Return type:

      click.Parameter

  get_params_by_name(names)
    Parameters:

      names (Iterable[str]) –

    Return type:

      Sequence[click.Parameter]

  format_constraints(ctx, formatter)
    Parameters:

      - ctx (click.Context) –

      - formatter (cloup.HelpFormatter) –

    Return type:

      None

  must_show_constraints(ctx)
    Parameters:

      ctx (click.Context) –

    Return type:

      bool

cloup.constraints._support.ensure_constraints_support(command)
  Parameters:

    command (Command) –

  Return type:

    ConstraintMixin