cloup.constraints

Constraints for parameter groups.

New in version v0.5.0.

Submodules

• cloup.constraints.common
• cloup.constraints.conditions
• cloup.constraints.exceptions

Classes

If(condition, then[, else_])	Checks one constraint or another depending on the truth value of the condition.
AcceptAtMost(n)	Satisfied if the number of set parameters is <= n.
AcceptBetween(min, max)	Satisfied if the number of set parameters is between min and max (included).
And(*constraints)	It’s satisfied if all operands are satisfied.
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.
Or(*constraints)	It’s satisfied if at least one of the operands is satisfied.
Rephraser(constraint[, help, error])	A Constraint decorator that can override the help and/or the error message of the wrapped constraint.
RequireAtLeast(n)	Satisfied if the number of set parameters is >= n.
RequireExactly(n)	Requires an exact number of parameters to be set.
WrapperConstraint(constraint, **attrs)	Abstract class that wraps another constraint and delegates all methods to it.
ConstraintMixin(*args[, constraints, …])	Provides support to constraints.
BoundConstraintSpec(constraint, params)	A NamedTuple storing a Constraint and the names of the parameters if has check.
AllSet(*param_names)	True if all listed parameters are set.
AnySet(*param_names)	True if any of the listed parameters is set.
Equal(param_name, value)	True if the parameter value equals value.
IsSet(param_name)	True if the parameter is set.
Not(predicate)	Logical NOT of a predicate.

Functions

constraint(constr, params)

Registers a constraint.

Attributes

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_all	Satisfied if all parameters are set.

Contents

class cloup.constraints.If(condition, then, else_=None)

Bases: cloup.constraints._core.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).

Parameters

• condition (Union[str, Sequence[str], cloup.constraints.conditions.Predicate]) –

• then (cloup.constraints._core.Constraint) –

• else_ (Optional[cloup.constraints._core.Constraint]) –

help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, params)

Performs some sanity checks that detect inconsistencies between this 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 (see toggle_consistency_checks())

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)

Checks 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

__repr__(self)

Return repr(self).

Return type

str

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

Performs some sanity checks that detect inconsistencies between this 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 (see toggle_consistency_checks())

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)

Checks 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

__repr__(self)

Return repr(self).

class cloup.constraints.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.

Parameters

• min (int) –

• max (int) –

help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

class cloup.constraints.And(*constraints)

Bases: Operator

It’s satisfied if all operands are satisfied.

Parameters

constraints (cloup.constraints._core.Constraint) –

HELP_SEP =  and

check_values(self, params, ctx)

Checks 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

__and__(self, other)

Return type

And

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

classmethod must_check_consistency(cls)

Returns True if consistency checks are enabled.

Return type

bool

classmethod toggle_consistency_checks(cls, value)

Enables/disables consistency checks. Enabling means that:

• check() will call check_consistency()

• ConstraintMixin will call check_consistency on constraints it is responsible for before parsing CLI arguments.

Parameters

value (bool) –

classmethod consistency_checks_toggled(cls, value)

Parameters

value (bool) –

abstract help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, params)

Performs some sanity checks that detect inconsistencies between this 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 (see toggle_consistency_checks())

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)

Checks 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

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

check(self, params: Iterable[str], ctx: Optional[click.Context] = None) → None

Raises 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 False to toggle_consistency_checks().

Parameters

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

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

Raises

ConstraintViolated UnsatisfiableConstraint

rephrased(self, help=None, error=None)

Parameters

• help (Union[None, str, HelpRephraser]) –

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

Return type

Rephraser

hidden(self)

Hides this constraint from the command help.

Return type

Rephraser

__call__(self, param_names, ctx=None)

Parameters

• param_names (Iterable[str]) –

• ctx (Optional[click.Context]) –

Return type

None

__or__(self, other)

Parameters

other (Constraint) –

Return type

Or

__and__(self, other)

Parameters

other (Constraint) –

Return type

And

__repr__(self)

Return repr(self).

class cloup.constraints.Operator(*constraints)

Bases: Constraint, abc.ABC

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

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)

Performs some sanity checks that detect inconsistencies between this 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 (see toggle_consistency_checks())

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

class cloup.constraints.Or(*constraints)

Bases: Operator

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

Parameters

constraints (cloup.constraints._core.Constraint) –

HELP_SEP =  or

check_values(self, params, ctx)

Checks 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

__or__(self, other)

Return type

Or

class cloup.constraints.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.

This is useful also for defining new constraints. See also WrapperConstraint.

Parameters

• constraint (cloup.constraints._core.Constraint) –

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

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

help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, params)

Performs some sanity checks that detect inconsistencies between this 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 (see toggle_consistency_checks())

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)

Checks 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

__repr__(self)

Return repr(self).

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

Performs some sanity checks that detect inconsistencies between this 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 (see toggle_consistency_checks())

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)

Checks 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

__repr__(self)

Return repr(self).

class cloup.constraints.RequireExactly(n)

Bases: WrapperConstraint

Requires an exact number of parameters to be set.

Parameters

n (int) –

help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_values(self, params, ctx)

Checks 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

class cloup.constraints.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) –

help(self, ctx)

A description of the constraint.

Parameters

ctx (click.Context) –

Return type

str

check_consistency(self, params)

Performs some sanity checks that detect inconsistencies between this 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 (see toggle_consistency_checks())

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)

Checks 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

__repr__(self)

Return repr(self).

cloup.constraints.accept_none

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

cloup.constraints.all_or_none

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

cloup.constraints.mutually_exclusive

Satisfied if at most one of the parameters is set.

cloup.constraints.require_all

Satisfied if all parameters are set.

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

Provides support to constraints.

Parameters

• constraints (Sequence[cloup.constraints._support.BoundConstraintSpec]) –

• show_constraints (Optional[bool]) –

parse_args(self, ctx, args)

get_param_by_name(self, name)

Parameters

name (str) –

Return type

click.Parameter

get_params_by_name(self, names)

Parameters

names (Iterable[str]) –

Return type

Sequence[click.Parameter]

format_constraints(self, ctx, formatter)

Return type

None

format_help(self, ctx, formatter)

Parameters

formatter (click.HelpFormatter) –

Return type

None

cloup.constraints.constraint(constr, params)

Registers a constraint.

Parameters

• constr (cloup.constraints._core.Constraint) –

• params (Iterable[str]) –

class cloup.constraints.BoundConstraintSpec

Bases: NamedTuple

A NamedTuple storing a Constraint and the names of the parameters if has check.

Parameters

• constraint (cloup.constraints._core.Constraint) –

• params (Sequence[str]) –

constraint :cloup.constraints._core.Constraint

params :Sequence[str]

class cloup.constraints.AllSet(*param_names)

Bases: Predicate

True if all listed parameters are set.

New in version 0.8.0.

Parameters

param_names (str) –

negated_description(self, ctx)

Succint description of the negation of this predicate (alias: neg_desc).

Parameters

ctx (click.Context) –

Return type

str

description(self, ctx)

Succint description of the predicate (alias: desc).

Parameters

ctx (click.Context) –

Return type

str

__call__(self, ctx)

Evaluate the predicate on the given context.

Parameters

ctx (click.Context) –

Return type

bool

__and__(self, other)

Parameters

other (Predicate) –

class cloup.constraints.AnySet(*param_names)

Bases: Predicate

True if any of the listed parameters is set.

New in version 0.8.0.

Parameters

param_names (str) –

negated_description(self, ctx)

Succint description of the negation of this predicate (alias: neg_desc).

Parameters

ctx (click.Context) –

Return type

str

description(self, ctx)

Succint description of the predicate (alias: desc).

Parameters

ctx (click.Context) –

Return type

str

__call__(self, ctx)

Evaluate the predicate on the given context.

Parameters

ctx (click.Context) –

Return type

bool

__or__(self, other)

Parameters

other (Predicate) –

class cloup.constraints.Equal(param_name, value)

Bases: Predicate

True if the parameter value equals value.

Parameters

• param_name (str) –

• value (Any) –

description(self, ctx)

Succint description of the predicate (alias: desc).

Parameters

ctx (click.Context) –

Return type

str

negated_description(self, ctx)

Succint description of the negation of this predicate (alias: neg_desc).

Parameters

ctx (click.Context) –

Return type

str

__call__(self, ctx)

Evaluate the predicate on the given context.

Parameters

ctx (click.Context) –

Return type

bool

class cloup.constraints.IsSet(param_name)

Bases: Predicate

True if the parameter is set.

Parameters

param_name (str) –

description(self, ctx)

Succint description of the predicate (alias: desc).

Parameters

ctx (click.Context) –

Return type

str

negated_description(self, ctx)

Succint description of the negation of this predicate (alias: neg_desc).

Parameters

ctx (click.Context) –

Return type

str

__call__(self, ctx)

Evaluate the predicate on the given context.

Parameters

ctx (click.Context) –

Return type

bool

__and__(self, other)

Parameters

other (Predicate) –

__or__(self, other)

Parameters

other (Predicate) –

class cloup.constraints.Not(predicate)

Bases: Predicate, Generic[P]

Logical NOT of a predicate.

description(self, ctx)

Succint description of the predicate (alias: desc).

Parameters

ctx (click.Context) –

Return type

str

negated_description(self, ctx)

Succint description of the negation of this predicate (alias: neg_desc).

Parameters

ctx (click.Context) –

Return type

str

__call__(self, ctx)

Evaluate the predicate on the given context.

Parameters

ctx (click.Context) –

Return type

bool

__invert__(self)

Return type

P

__repr__(self)

Return repr(self).

Return type

str

exception cloup.constraints.ConstraintViolated(message, ctx=None)

Bases: click.UsageError

An internal exception that signals a usage error. This typically aborts any further handling.

Parameters

• message – the error message to display.

• ctx – optionally the context that caused this error. Click will fill in the context automatically in some situations.

classmethod default(cls, params, desc, ctx=None)

Parameters

• params (Iterable[click.Parameter]) –

• desc (str) –

• ctx (Optional[click.Context]) –

Return type

ConstraintViolated

exception cloup.constraints.UnsatisfiableConstraint(constraint, params, reason)

Bases: Exception

Raised if a constraint cannot be satisfied by a group of parameters independently from their values at runtime; e.g. mutually_exclusive cannot be satisfied if multiple of the parameters are required.