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__(self, attr)

Parameters

attr (str) –

Return type

Any

abstract help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, 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(self, 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(self, params: Sequence[click.Parameter], ctx: Optional[click.Context] = None) → None

check(self, params: Sequence[str], ctx: Optional[click.Context] = 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(self, 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(self)

Hide this constraint from the command help.

Return type

Rephraser

__call__(self, *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__(self, other)

Parameters

other (Constraint) –

Return type

Or

__and__(self, other)

Parameters

other (Constraint) –

Return type

And

__repr__(self)

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 (cloup.constraints._core.Constraint) –

HELP_SEP :str

Used as separator of all constraints’ help strings.

help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, 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__(self)

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 (cloup.constraints._core.Constraint) –

HELP_SEP =  and

check_values(self, 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__(self, 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 (cloup.constraints._core.Constraint) –

HELP_SEP =  or

check_values(self, 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__(self, 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."
)

Return type

None

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 (cloup.constraints._core.Constraint) –

• help (Union[None, str, Callable[[click.core.Context, Constraint], str]]) –

• error (Union[None, str, Callable[[cloup.constraints.exceptions.ConstraintViolated], str]]) –

help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, 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(self, 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__(self)

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 (cloup.constraints._core.Constraint) – the constraint to wrap

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

help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, 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(self, 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__(self)

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(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, 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(self, 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__(self)

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(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, 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(self, 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__(self)

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(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_values(self, 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__(self)

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(self, 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).