cloup.constraints
¶
Constraints for parameter groups.
New in version v0.5.0.
Classes¶
|
Checks one constraint or another depending on the truth value of the condition. |
|
Satisfied if the number of set parameters is <= n. |
|
Satisfied if the number of set parameters is between |
|
It’s satisfied if all operands are satisfied. |
A constraint that can be checked against an arbitrary collection of CLI parameters with respect to a specific |
|
|
Base class for all n-ary operators defined on constraints. |
|
It’s satisfied if at least one of the operands is satisfied. |
|
A Constraint decorator that can override the help and/or the error message of the wrapped constraint. |
Satisfied if the number of set parameters is >= n. |
|
Requires an exact number of parameters to be set. |
|
|
Abstract class that wraps another constraint and delegates all methods to it. |
|
Provides support to constraints. |
|
A NamedTuple storing a |
|
True if all listed parameters are set. |
|
True if any of the listed parameters is set. |
|
True if the parameter value equals |
|
True if the parameter is set. |
|
Logical NOT of a predicate. |
Functions¶
|
Registers a constraint. |
Attributes¶
Satisfied if none of the parameters is set. Useful only in conditional constraints. |
|
Satisfied if either all or none of the parameters are set. |
|
Satisfied if at most one of the parameters is set. |
|
Satisfied if all parameters are set. |
Contents¶
-
class
cloup.constraints.
If
(condition, then, else_=None)[source]¶ 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 inctx.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)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
check_consistency
(self, params)[source]¶ 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
-
check_values
(self, params, ctx)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
class
cloup.constraints.
AcceptAtMost
(n)[source]¶ Bases:
Constraint
Satisfied if the number of set parameters is <= n.
- Parameters
n (int) –
-
help
(self, ctx)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
check_consistency
(self, params)[source]¶ 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
-
check_values
(self, params, ctx)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
class
cloup.constraints.
AcceptBetween
(min, max)[source]¶ 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.-
help
(self, ctx)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
-
class
cloup.constraints.
And
(*constraints)[source]¶ Bases:
Operator
It’s satisfied if all operands are satisfied.
- Parameters
constraints (cloup.constraints._core.Constraint) –
-
HELP_SEP
= and¶
-
check_values
(self, params, ctx)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
class
cloup.constraints.
Constraint
[source]¶ 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 inctx.params
).-
classmethod
must_check_consistency
(cls)[source]¶ Returns True if consistency checks are enabled.
- Return type
-
classmethod
toggle_consistency_checks
(cls, value)[source]¶ Enables/disables consistency checks. Enabling means that:
check()
will callcheck_consistency()
ConstraintMixin
will call check_consistency on constraints it is responsible for before parsing CLI arguments.
- Parameters
value (bool) –
-
abstract
help
(self, ctx)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
check_consistency
(self, params)[source]¶ 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
-
abstract
check_values
(self, params, ctx)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
check
(self, params: Sequence[click.Parameter], ctx: Optional[click.Context] = None) → None[source]¶ -
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) andcheck_values()
.Tip
By default
check_consistency()
is called since it shouldn’t have any performance impact. Nonetheless, you can disable it in production passingFalse
totoggle_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
Hides this constraint from the command help.
- Return type
-
__call__
(self, param_names, ctx=None)[source]¶ - Parameters
param_names (Iterable[str]) –
ctx (Optional[click.Context]) –
- Return type
-
__or__
(self, other)[source]¶ - Parameters
other (Constraint) –
- Return type
-
__and__
(self, other)[source]¶ - Parameters
other (Constraint) –
- Return type
-
classmethod
-
class
cloup.constraints.
Operator
(*constraints)[source]¶ 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)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
check_consistency
(self, params)[source]¶ 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
-
class
cloup.constraints.
Or
(*constraints)[source]¶ 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)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
class
cloup.constraints.
Rephraser
(constraint, help=None, error=None)[source]¶ 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)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
check_consistency
(self, params)[source]¶ 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
-
check_values
(self, params, ctx)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
class
cloup.constraints.
RequireAtLeast
(n)[source]¶ Bases:
Constraint
Satisfied if the number of set parameters is >= n.
- Parameters
n (int) –
-
help
(self, ctx)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
check_consistency
(self, params)[source]¶ 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
-
check_values
(self, params, ctx)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
class
cloup.constraints.
RequireExactly
(n)[source]¶ Bases:
WrapperConstraint
Requires an exact number of parameters to be set.
- Parameters
n (int) –
-
help
(self, ctx)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
check_values
(self, params, ctx)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
class
cloup.constraints.
WrapperConstraint
(constraint, **attrs)[source]¶ 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)[source]¶ A description of the constraint.
- Parameters
ctx (click.Context) –
- Return type
-
check_consistency
(self, params)[source]¶ 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
-
check_values
(self, params, ctx)[source]¶ 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
instancesctx (click.Context) –
click.Context
- Raises
-
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)[source]¶ Provides support to constraints.
- Parameters
constraints (Sequence[cloup.constraints._support.BoundConstraintSpec]) –
show_constraints (Optional[bool]) –
-
get_params_by_name
(self, names)[source]¶ - Parameters
names (Iterable[str]) –
- Return type
Sequence[click.Parameter]
-
format_help
(self, ctx, formatter)[source]¶ - Parameters
formatter (click.HelpFormatter) –
- Return type
-
cloup.constraints.
constraint
(constr, params)[source]¶ Registers a constraint.
- Parameters
constr (cloup.constraints._core.Constraint) –
params (Iterable[str]) –
-
class
cloup.constraints.
BoundConstraintSpec
[source]¶ 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)[source]¶ Bases:
Predicate
True if all listed parameters are set.
New in version 0.8.0.
- Parameters
param_names (str) –
-
negated_description
(self, ctx)[source]¶ Succint description of the negation of this predicate (alias: neg_desc).
- Parameters
ctx (click.Context) –
- Return type
-
description
(self, ctx)[source]¶ Succint description of the predicate (alias: desc).
- Parameters
ctx (click.Context) –
- Return type
-
__call__
(self, ctx)[source]¶ Evaluate the predicate on the given context.
- Parameters
ctx (click.Context) –
- Return type
-
class
cloup.constraints.
AnySet
(*param_names)[source]¶ 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)[source]¶ Succint description of the negation of this predicate (alias: neg_desc).
- Parameters
ctx (click.Context) –
- Return type
-
description
(self, ctx)[source]¶ Succint description of the predicate (alias: desc).
- Parameters
ctx (click.Context) –
- Return type
-
__call__
(self, ctx)[source]¶ Evaluate the predicate on the given context.
- Parameters
ctx (click.Context) –
- Return type
-
class
cloup.constraints.
Equal
(param_name, value)[source]¶ Bases:
Predicate
True if the parameter value equals
value
.- Parameters
param_name (str) –
value (Any) –
-
description
(self, ctx)[source]¶ Succint description of the predicate (alias: desc).
- Parameters
ctx (click.Context) –
- Return type
-
negated_description
(self, ctx)[source]¶ Succint description of the negation of this predicate (alias: neg_desc).
- Parameters
ctx (click.Context) –
- Return type
-
__call__
(self, ctx)[source]¶ Evaluate the predicate on the given context.
- Parameters
ctx (click.Context) –
- Return type
-
class
cloup.constraints.
IsSet
(param_name)[source]¶ Bases:
Predicate
True if the parameter is set.
- Parameters
param_name (str) –
-
description
(self, ctx)[source]¶ Succint description of the predicate (alias: desc).
- Parameters
ctx (click.Context) –
- Return type
-
negated_description
(self, ctx)[source]¶ Succint description of the negation of this predicate (alias: neg_desc).
- Parameters
ctx (click.Context) –
- Return type
-
__call__
(self, ctx)[source]¶ Evaluate the predicate on the given context.
- Parameters
ctx (click.Context) –
- Return type
-
class
cloup.constraints.
Not
(predicate)[source]¶ Bases:
Predicate
,Generic
[P
]Logical NOT of a predicate.
-
description
(self, ctx)[source]¶ Succint description of the predicate (alias: desc).
- Parameters
ctx (click.Context) –
- Return type
-
negated_description
(self, ctx)[source]¶ Succint description of the negation of this predicate (alias: neg_desc).
- Parameters
ctx (click.Context) –
- Return type
-
__call__
(self, ctx)[source]¶ Evaluate the predicate on the given context.
- Parameters
ctx (click.Context) –
- Return type
-
-
exception
cloup.constraints.
ConstraintViolated
(message, ctx=None)[source]¶ 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)[source]¶ - Parameters
params (Iterable[click.Parameter]) –
desc (str) –
ctx (Optional[click.Context]) –
- Return type
-
exception
cloup.constraints.
UnsatisfiableConstraint
(constraint, params, reason)[source]¶ 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.