cloup.constraints
¶
Constraints for parameter groups.
Classes summary¶
|
|
|
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. |
|
True if the parameter value equals |
|
True if the parameter is set. |
|
Functions Summary¶
|
Registers a constraint. |
Contents¶
-
class
cloup.constraints.
If
(condition: Union[str, Predicate], then: cloup.constraints._core.Constraint, else_: Optional[Constraint] = 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, cloup.constraints.conditions.Predicate]) –
then (cloup.constraints._core.Constraint) –
else_ (Optional[cloup.constraints._core.Constraint]) –
-
help
(self, ctx: click.Context) → str[source]¶ A description of the constraint.
-
check_consistency
(self, params: Sequence[Parameter]) → None[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 – list of
click.Parameter
instances- Raises
UnsatisfiableConstraint
if the constraint cannot be satisfied independently from the values provided by the user
-
check_values
(self, params: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
class
cloup.constraints.
AcceptAtMost
(n: int)[source]¶ Bases:
cloup.constraints._core.Constraint
Satisfied if the number of set parameters is <= n.
- Parameters
n (int) –
-
help
(self, ctx: click.Context) → str[source]¶ A description of the constraint.
-
check_consistency
(self, params: Sequence[Parameter]) → None[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 – list of
click.Parameter
instances- Raises
UnsatisfiableConstraint
if the constraint cannot be satisfied independently from the values provided by the user
-
check_values
(self, params: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
class
cloup.constraints.
AcceptBetween
(min: int, max: int)[source]¶ Bases:
cloup.constraints._core.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: click.Context) → str[source]¶ A description of the constraint.
-
-
class
cloup.constraints.
And
(*constraints: cloup.constraints._core.Constraint)[source]¶ Bases:
cloup.constraints._core.Operator
It’s satisfied if all operands are satisfied.
- Parameters
constraints (cloup.constraints._core.Constraint) –
-
HELP_SEP
= and¶
-
check_values
(self, params: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
__and__
(self, other) → cloup.constraints._core.And[source]¶
-
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) → bool[source]¶ Returns True if consistency checks are enabled.
-
classmethod
toggle_consistency_checks
(cls, value: bool)[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.
-
abstract
help
(self, ctx: click.Context) → str[source]¶ A description of the constraint.
-
check_consistency
(self, params: Sequence[Parameter]) → None[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 – list of
click.Parameter
instances- Raises
UnsatisfiableConstraint
if the constraint cannot be satisfied independently from the values provided by the user
-
abstract
check_values
(self, params: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
check
(self, params: Sequence[Parameter], ctx: Optional[Context] = None) → None[source]¶ -
check
(self, params: Iterable[str], ctx: Optional[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
-
rephrased
(self, help: Union[None, str, HelpRephraser] = None, error: Union[None, str, ErrorRephraser] = None) → cloup.constraints._core.Rephraser[source]¶
Hides this constraint from the command help.
-
__or__
(self, other: cloup.constraints._core.Constraint) → cloup.constraints._core.Or[source]¶
-
__and__
(self, other: cloup.constraints._core.Constraint) → cloup.constraints._core.And[source]¶
-
classmethod
-
class
cloup.constraints.
Operator
(*constraints: cloup.constraints._core.Constraint)[source]¶ Bases:
cloup.constraints._core.Constraint
,abc.ABC
Base class for all n-ary operators defined on constraints.
- Parameters
constraints (cloup.constraints._core.Constraint) –
-
HELP_SEP
:str¶
-
help
(self, ctx: click.Context) → str[source]¶ A description of the constraint.
-
check_consistency
(self, params: Sequence[Parameter]) → None[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 – list of
click.Parameter
instances- Raises
UnsatisfiableConstraint
if the constraint cannot be satisfied independently from the values provided by the user
-
class
cloup.constraints.
Or
(*constraints: cloup.constraints._core.Constraint)[source]¶ Bases:
cloup.constraints._core.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: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
__or__
(self, other) → cloup.constraints._core.Or[source]¶
-
class
cloup.constraints.
Rephraser
(constraint: cloup.constraints._core.Constraint, help: Union[None, str, HelpRephraser] = None, error: Union[None, str, ErrorRephraser] = None)[source]¶ Bases:
cloup.constraints._core.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: click.Context) → str[source]¶ A description of the constraint.
-
check_consistency
(self, params: Sequence[Parameter]) → None[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 – list of
click.Parameter
instances- Raises
UnsatisfiableConstraint
if the constraint cannot be satisfied independently from the values provided by the user
-
check_values
(self, params: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
class
cloup.constraints.
RequireAtLeast
(n: int)[source]¶ Bases:
cloup.constraints._core.Constraint
Satisfied if the number of set parameters is >= n.
- Parameters
n (int) –
-
help
(self, ctx: click.Context) → str[source]¶ A description of the constraint.
-
check_consistency
(self, params: Sequence[Parameter]) → None[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 – list of
click.Parameter
instances- Raises
UnsatisfiableConstraint
if the constraint cannot be satisfied independently from the values provided by the user
-
check_values
(self, params: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
class
cloup.constraints.
RequireExactly
(n: int)[source]¶ Bases:
cloup.constraints._core.WrapperConstraint
Requires an exact number of parameters to be set.
- Parameters
n (int) –
-
help
(self, ctx: click.Context) → str[source]¶ A description of the constraint.
-
check_values
(self, params: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
class
cloup.constraints.
WrapperConstraint
(constraint: cloup.constraints._core.Constraint, **attrs)[source]¶ Bases:
cloup.constraints._core.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: click.Context) → str[source]¶ A description of the constraint.
-
check_consistency
(self, params: Sequence[Parameter]) → None[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 – list of
click.Parameter
instances- Raises
UnsatisfiableConstraint
if the constraint cannot be satisfied independently from the values provided by the user
-
check_values
(self, params: Sequence[Parameter], ctx: click.Context)[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 – list of
click.Parameter
instancesctx –
click.Context
- Raises
-
cloup.constraints.
accept_none
¶
-
cloup.constraints.
all_or_none
¶
-
cloup.constraints.
mutually_exclusive
¶
-
cloup.constraints.
require_all
¶
-
class
cloup.constraints.
ConstraintMixin
(*args, constraints: Sequence[BoundConstraintSpec] = (), show_constraints: bool = False, **kwargs)[source]¶ Provides support to constraints.
- Parameters
constraints (Sequence[cloup.constraints._support.BoundConstraintSpec]) –
show_constraints (bool) –
-
get_param_by_name
(self, name: str) → click.Parameter[source]¶
-
format_help
(self, ctx, formatter: click.HelpFormatter) → None[source]¶
-
cloup.constraints.
constraint
(constr: cloup.constraints._core.Constraint, params: Iterable[str])[source]¶ Registers a constraint.
- Parameters
constr (cloup.constraints._core.Constraint) –
params (Iterable[str]) –
-
class
cloup.constraints.
Equal
(param_name: str, value: Any)[source]¶ Bases:
cloup.constraints.conditions.Predicate
True if the parameter value equals
value
.- Parameters
param_name (str) –
value (Any) –
-
description
(self, ctx: click.Context) → str[source]¶ Succint description of the predicate (alias: desc).
-
negated_description
(self, ctx: click.Context) → str[source]¶ Succint description of the negation of this predicate (alias: neg_desc).
-
__call__
(self, ctx: click.Context) → bool[source]¶ Evaluate the predicate on the given context.
-
class
cloup.constraints.
IsSet
(param_name: str)[source]¶ Bases:
cloup.constraints.conditions.Predicate
A
Callable
that takes aContext
and returns a boolean, with an associated description. Meant to be used as condition in a conditional constraint (seeIf
).- Parameters
param_name (str) –
-
description
(self, ctx: click.Context) → str[source]¶ Succint description of the predicate (alias: desc).
-
negated_description
(self, ctx: click.Context) → str[source]¶ Succint description of the negation of this predicate (alias: neg_desc).
-
__call__
(self, ctx: click.Context) → bool[source]¶ Evaluate the predicate on the given context.
-
class
cloup.constraints.
Not
(predicate: P)[source]¶ Bases:
cloup.constraints.conditions.Predicate
,Generic[P]
A
Callable
that takes aContext
and returns a boolean, with an associated description. Meant to be used as condition in a conditional constraint (seeIf
).-
description
(self, ctx: click.Context) → str[source]¶ Succint description of the predicate (alias: desc).
-
negated_description
(self, ctx: click.Context) → str[source]¶ Succint description of the negation of this predicate (alias: neg_desc).
-
__call__
(self, ctx: click.Context) → bool[source]¶ Evaluate the predicate on the given context.
-
-
exception
cloup.constraints.
ConstraintViolated
(message: str, ctx: Optional[Context] = 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: Iterable[Parameter], desc: str, ctx: Optional[Context] = None) → cloup.constraints.exceptions.ConstraintViolated[source]¶
-
exception
cloup.constraints.
UnsatisfiableConstraint
(constraint: cloup.constraints._core.Constraint, params: Iterable[Parameter], reason: str)[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.