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

# `cloup.constraints._core`

## Classes

`Constraint`() | A constraint that can be checked against an arbitrary collection of CLI parameters with respect to a specific `click.Context` (which contains the values assigned to the parameters in `ctx.params`).
`Operator`(*constraints) | Base class for all n-ary operators defined on constraints.
`And`(*constraints) | It's satisfied if all operands are satisfied.
`Or`(*constraints) | It's satisfied if at least one of the operands is satisfied.
`ErrorFmt`() | `Rephraser` allows you to pass a `format` string as `error` argument; this class contains the "replacement fields" supported by such format string. You can use them as following::.
`Rephraser`(constraint[, help, error]) | A constraint decorator that can override the help and/or the error message of the wrapped constraint.
`WrapperConstraint`(constraint, **attrs) | Abstract class that wraps another constraint and delegates all methods to it.
`RequireAtLeast`(n) | Satisfied if the number of set parameters is >= n.
`AcceptAtMost`(n) | Satisfied if the number of set parameters is <= n.
`RequireExactly`(n) | Requires an exact number of parameters to be set.
`AcceptBetween`(min, max) | Satisfied if the number of set parameters is between `min` and `max` (included).

## Attributes

`Op` |
`HelpRephraser` |
`ErrorRephraser` |
`require_all` | Satisfied if all parameters are set.
`accept_none` | Satisfied if none of the parameters is set. Useful only in conditional constraints.
`all_or_none` | Satisfied if either all or none of the parameters are set.
`mutually_exclusive` | Satisfied if at most one of the parameters is set.
`require_any` | Alias for `RequireAtLeast(1)`.
`require_one` | Alias for `RequireExactly(1)`.

## Contents

cloup.constraints._core.Op

cloup.constraints._core.HelpRephraser

cloup.constraints._core.ErrorRephraser

class cloup.constraints._core.Constraint

  Bases: `abc.ABC`

  A constraint that can be checked against an arbitrary collection of CLI parameters with respect to a specific `click.Context` (which contains the values assigned to the parameters in `ctx.params`).

  Changed in version 0.9.0: calling a constraint, previously equivalent to `check()`, is now equivalent to calling `cloup.constrained_params()` with this constraint as first argument.

  static must_check_consistency(ctx)

    Return `True` if consistency checks are enabled.

    Changed in version 0.9.0: this method now a static method and takes a `click.Context` in input.

    Parameters:

      ctx (click.Context) –

    Return type:

      bool

  __getattr__(attr)
    Parameters:

      attr (str) –

    Return type:

      Any

  abstract help(ctx)

    A description of the constraint.

    Parameters:

      ctx (click.Context) –

    Return type:

      str

  check_consistency(params)

    Perform some sanity checks that detect inconsistencies between these constraints and the properties of the input parameters (e.g. required).

    For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options.

    These sanity checks are meant to catch developer’s mistakes and don’t depend on the values assigned to the parameters; therefore:

    - they can be performed before any parameter parsing

    - they can be disabled in production (setting `check_constraints_consistency=False` in `context_settings`)

    Parameters:

      params (Sequence[click.Parameter]) – list of `click.Parameter` instances

    Raises:

      `UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user

    Return type:

      None

  abstract check_values(params, ctx)

    Check that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in `ctx.params`.

    You probably don’t want to call this method directly. Use `check()` instead.

    Parameters:

      - params (Sequence[click.Parameter]) – list of `click.Parameter` instances

      - ctx (click.Context) – `click.Context`

    Raises:

      `ConstraintViolated`

    Return type:

      None

  check(params: Sequence[click.Parameter], ctx: click.Context | None = None) → None
  check(params: Sequence[str], ctx: click.Context | None = None) → None

    Raise an exception if the constraint is not satisfied by the input parameters in the given (or current) context.

    This method calls both `check_consistency()` (if enabled) and `check_values()`.

    Tip

    By default `check_consistency()` is called since it shouldn’t have any performance impact. Nonetheless, you can disable it in production passing `check_constraints_consistency=False` as part of your `context_settings`.

    Parameters:

      - params – an iterable of parameter names or a sequence of `click.Parameter`

      - ctx – a click.Context; if not provided, `click.get_current_context()` is used

    Raises:

      `ConstraintViolated` `UnsatisfiableConstraint`

  rephrased(help=None, error=None)

    Override the help string and/or the error message of this constraint wrapping it with a `Rephraser`.

    Parameters:

      - help (Union[None, str, HelpRephraser]) – if provided, overrides the help string of this constraint. It can be a string or a function `(ctx: click.Context, constr: Constraint) -> str`. If you want to hide this constraint from the help, pass `help=""`.

      - error (Union[None, str, ErrorRephraser]) –

        if provided, overrides the error message of this constraint. It can be:

        - a string, eventually a `format` string supporting the replacement fields described in `ErrorFmt`.

        - or a function `(err: ConstraintViolated) -> str`; note that a `ConstraintViolated` error has fields for `ctx`, `constraint` and `params`, so it’s a complete description of what happened.

    Return type:

      Rephraser

  hidden()

    Hide this constraint from the command help.

    Return type:

      Rephraser

  __call__(*param_adders)

    Equivalent to calling `cloup.constrained_params()` with this constraint as first argument.

    Changed in version 0.9.0: this method, previously equivalent to `check()`, is now equivalent to calling `cloup.constrained_params()` with this constraint as first argument.

    Parameters:

      param_adders (cloup.typing.Decorator) –

    Return type:

      Callable[[cloup.typing.F], cloup.typing.F]

  __or__(other)
    Parameters:

      other (Constraint) –

    Return type:

      Or

  __and__(other)
    Parameters:

      other (Constraint) –

    Return type:

      And

  __repr__()

    Return repr(self).

    Return type:

      str

class cloup.constraints._core.Operator(*constraints)

  Bases: `Constraint`, `abc.ABC`

  Base class for all n-ary operators defined on constraints.

  N-ary operator for constraints. :param constraints: operands

  Parameters:

    constraints (Constraint) –

  HELP_SEP :str

    Used as separator of all constraints’ help strings.

  help(ctx)

    A description of the constraint.

    Parameters:

      ctx (click.Context) –

    Return type:

      str

  check_consistency(params)

    Perform some sanity checks that detect inconsistencies between these constraints and the properties of the input parameters (e.g. required).

    For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options.

    These sanity checks are meant to catch developer’s mistakes and don’t depend on the values assigned to the parameters; therefore:

    - they can be performed before any parameter parsing

    - they can be disabled in production (setting `check_constraints_consistency=False` in `context_settings`)

    Parameters:

      params (Sequence[click.Parameter]) – list of `click.Parameter` instances

    Raises:

      `UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user

    Return type:

      None

  __repr__()

    Return repr(self).

    Return type:

      str

class cloup.constraints._core.And(*constraints)

  Bases: `Operator`

  It’s satisfied if all operands are satisfied.

  N-ary operator for constraints. :param constraints: operands

  Parameters:

    constraints (Constraint) –

  HELP_SEP = and
  check_values(params, ctx)

    Check that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in `ctx.params`.

    You probably don’t want to call this method directly. Use `check()` instead.

    Parameters:

      - params (Sequence[click.Parameter]) – list of `click.Parameter` instances

      - ctx (click.Context) – `click.Context`

    Raises:

      `ConstraintViolated`

    Return type:

      None

  __and__(other)
    Parameters:

      other (Constraint) –

    Return type:

      And

class cloup.constraints._core.Or(*constraints)

  Bases: `Operator`

  It’s satisfied if at least one of the operands is satisfied.

  N-ary operator for constraints. :param constraints: operands

  Parameters:

    constraints (Constraint) –

  HELP_SEP = or
  check_values(params, ctx)

    Check that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in `ctx.params`.

    You probably don’t want to call this method directly. Use `check()` instead.

    Parameters:

      - params (Sequence[click.Parameter]) – list of `click.Parameter` instances

      - ctx (click.Context) – `click.Context`

    Raises:

      `ConstraintViolated`

    Return type:

      None

  __or__(other)
    Parameters:

      other (Constraint) –

    Return type:

      Or

class cloup.constraints._core.ErrorFmt

  Bases: `cloup._util.FrozenSpace`

  `Rephraser` allows you to pass a `format` string as `error` argument; this class contains the “replacement fields” supported by such format string. You can use them as following:

      mutually_exclusive.rephrased(
          error=f"{ErrorFmt.error}\n"
                f"Some extra information here."
      )

  error = {error}

    Replaced by the original error message. Useful if all you want is to append or prepend some extra info to the original error message.

  param_list = {param_list}

    Replaced by a 2-space indented list of the constrained parameters.

class cloup.constraints._core.Rephraser(constraint, help=None, error=None)

  Bases: `Constraint`

  A constraint decorator that can override the help and/or the error message of the wrapped constraint.

  You’ll rarely (if ever) use this class directly. In most cases, you’ll use the method `Constraint.rephrased()`. Refer to it for more info.

  See also

  - `Constraint.rephrased()` – wraps a constraint with a `Rephraser`.

  - `WrapperConstraint` – alternative to `Rephraser`.

  - `ErrorFmt` – describes the keyword you can use in an error format string.

  Parameters:

    - constraint (Constraint) –

    - help (None | str | Callable[[Context, Constraint], str]) –

    - error (None | str | Callable[[ConstraintViolated], str]) –

  help(ctx)

    A description of the constraint.

    Parameters:

      ctx (click.Context) –

    Return type:

      str

  check_consistency(params)

    Perform some sanity checks that detect inconsistencies between these constraints and the properties of the input parameters (e.g. required).

    For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options.

    These sanity checks are meant to catch developer’s mistakes and don’t depend on the values assigned to the parameters; therefore:

    - they can be performed before any parameter parsing

    - they can be disabled in production (setting `check_constraints_consistency=False` in `context_settings`)

    Parameters:

      params (Sequence[click.Parameter]) – list of `click.Parameter` instances

    Raises:

      `UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user

    Return type:

      None

  check_values(params, ctx)

    Check that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in `ctx.params`.

    You probably don’t want to call this method directly. Use `check()` instead.

    Parameters:

      - params (Sequence[click.Parameter]) – list of `click.Parameter` instances

      - ctx (click.Context) – `click.Context`

    Raises:

      `ConstraintViolated`

    Return type:

      None

  __repr__()

    Return repr(self).

    Return type:

      str

class cloup.constraints._core.WrapperConstraint(constraint, **attrs)

  Bases: `Constraint`

  Abstract class that wraps another constraint and delegates all methods to it. Useful when you want to define a parametric constraint combining other existing constraints minimizing the boilerplate.

  This is an alternative to defining a function and using `Rephraser`. Feel free to do that in your code, but cloup will stick to the convention that parametric constraints are defined as classes and written in camel-case.

  Parameters:

    - constraint (Constraint) – the constraint to wrap

    - attrs (Any) – these are just used to generate a `__repr__` method

  help(ctx)

    A description of the constraint.

    Parameters:

      ctx (click.Context) –

    Return type:

      str

  check_consistency(params)

    Perform some sanity checks that detect inconsistencies between these constraints and the properties of the input parameters (e.g. required).

    For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options.

    These sanity checks are meant to catch developer’s mistakes and don’t depend on the values assigned to the parameters; therefore:

    - they can be performed before any parameter parsing

    - they can be disabled in production (setting `check_constraints_consistency=False` in `context_settings`)

    Parameters:

      params (Sequence[click.Parameter]) – list of `click.Parameter` instances

    Raises:

      `UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user

    Return type:

      None

  check_values(params, ctx)

    Check that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in `ctx.params`.

    You probably don’t want to call this method directly. Use `check()` instead.

    Parameters:

      - params (Sequence[click.Parameter]) – list of `click.Parameter` instances

      - ctx (click.Context) – `click.Context`

    Raises:

      `ConstraintViolated`

    Return type:

      None

  __repr__()

    Return repr(self).

    Return type:

      str

class cloup.constraints._core.RequireAtLeast(n)

  Bases: `Constraint`

  Satisfied if the number of set parameters is >= n.

  Parameters:

    n (int) –

  help(ctx)

    A description of the constraint.

    Parameters:

      ctx (click.Context) –

    Return type:

      str

  check_consistency(params)

    Perform some sanity checks that detect inconsistencies between these constraints and the properties of the input parameters (e.g. required).

    For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options.

    These sanity checks are meant to catch developer’s mistakes and don’t depend on the values assigned to the parameters; therefore:

    - they can be performed before any parameter parsing

    - they can be disabled in production (setting `check_constraints_consistency=False` in `context_settings`)

    Parameters:

      params (Sequence[click.Parameter]) – list of `click.Parameter` instances

    Raises:

      `UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user

    Return type:

      None

  check_values(params, ctx)

    Check that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in `ctx.params`.

    You probably don’t want to call this method directly. Use `check()` instead.

    Parameters:

      - params (Sequence[click.Parameter]) – list of `click.Parameter` instances

      - ctx (click.Context) – `click.Context`

    Raises:

      `ConstraintViolated`

    Return type:

      None

  __repr__()

    Return repr(self).

    Return type:

      str

class cloup.constraints._core.AcceptAtMost(n)

  Bases: `Constraint`

  Satisfied if the number of set parameters is <= n.

  Parameters:

    n (int) –

  help(ctx)

    A description of the constraint.

    Parameters:

      ctx (click.Context) –

    Return type:

      str

  check_consistency(params)

    Perform some sanity checks that detect inconsistencies between these constraints and the properties of the input parameters (e.g. required).

    For example, a constraint that requires the parameters to be mutually exclusive is not consistent with a group of parameters with multiple required options.

    These sanity checks are meant to catch developer’s mistakes and don’t depend on the values assigned to the parameters; therefore:

    - they can be performed before any parameter parsing

    - they can be disabled in production (setting `check_constraints_consistency=False` in `context_settings`)

    Parameters:

      params (Sequence[click.Parameter]) – list of `click.Parameter` instances

    Raises:

      `UnsatisfiableConstraint` if the constraint cannot be satisfied independently from the values provided by the user

    Return type:

      None

  check_values(params, ctx)

    Check that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in `ctx.params`.

    You probably don’t want to call this method directly. Use `check()` instead.

    Parameters:

      - params (Sequence[click.Parameter]) – list of `click.Parameter` instances

      - ctx (click.Context) – `click.Context`

    Raises:

      `ConstraintViolated`

    Return type:

      None

  __repr__()

    Return repr(self).

    Return type:

      str

class cloup.constraints._core.RequireExactly(n)

  Bases: `WrapperConstraint`

  Requires an exact number of parameters to be set.

  Parameters:

    - constraint – the constraint to wrap

    - attrs – these are just used to generate a `__repr__` method

    - n (int) –

  help(ctx)

    A description of the constraint.

    Parameters:

      ctx (click.Context) –

    Return type:

      str

  check_values(params, ctx)

    Check that the constraint is satisfied by the input parameters in the given context, which (among other things) contains the values assigned to the parameters in `ctx.params`.

    You probably don’t want to call this method directly. Use `check()` instead.

    Parameters:

      - params (Sequence[click.Parameter]) – list of `click.Parameter` instances

      - ctx (click.Context) – `click.Context`

    Raises:

      `ConstraintViolated`

    Return type:

      None

  __repr__()

    Return repr(self).

    Return type:

      str

class cloup.constraints._core.AcceptBetween(min, max)

  Bases: `WrapperConstraint`

  Abstract class that wraps another constraint and delegates all methods to it. Useful when you want to define a parametric constraint combining other existing constraints minimizing the boilerplate.

  This is an alternative to defining a function and using `Rephraser`. Feel free to do that in your code, but cloup will stick to the convention that parametric constraints are defined as classes and written in camel-case.

  Satisfied if the number of set parameters is between `min` and `max` (included).

  Parameters:

    - min (int) – must be an integer >= 0

    - max (int) – must be an integer > min

  help(ctx)

    A description of the constraint.

    Parameters:

      ctx (click.Context) –

    Return type:

      str

cloup.constraints._core.require_all

  Satisfied if all parameters are set.

cloup.constraints._core.accept_none

  Satisfied if none of the parameters is set. Useful only in conditional constraints.

cloup.constraints._core.all_or_none

  Satisfied if either all or none of the parameters are set.

cloup.constraints._core.mutually_exclusive

  Satisfied if at most one of the parameters is set.

cloup.constraints._core.require_any

  Alias for `RequireAtLeast(1)`.

cloup.constraints._core.require_one

  Alias for `RequireExactly(1)`.