cloup.constraints._support

Classes

BoundConstraintSpec(constraint, param_names)

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

BoundConstraint(constraint, params)

Internal utility NamedTuple that represents a Constraint bound to a collection of click.Parameter instances.

ConstraintMixin(*args[, constraints, …])

Provides support for constraints.

Functions

constraint(constr, params)

Register a constraint on a list of parameters specified by (destination) name (e.g.

constrained_params(constr, *param_adders)

Return a decorator that adds the given parameters and applies a constraint to them. Equivalent to::.

ensure_constraints_support(command)

Contents

class cloup.constraints._support.BoundConstraintSpec[source]

Bases: NamedTuple

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

Parameters
constraint :cloup.constraints._core.Constraint
param_names :Union[Sequence[str]]
resolve_params(self, cmd)[source]
Parameters

cmd (ConstraintMixin) –

Return type

BoundConstraint

cloup.constraints._support.constraint(constr, params)[source]

Register a constraint on a list of parameters specified by (destination) name (e.g. the default name of --input-file is input_file).

Parameters
Return type

Callable[[F], F]

cloup.constraints._support.constrained_params(constr, *param_adders)[source]

Return a decorator that adds the given parameters and applies a constraint to them. Equivalent to:

@param_adders[0]
...
@param_adders[-1]
@constraint(constr, <param names>)

This decorator saves you to manually (re)type the parameter names. It can also be used inside @option_group.

Instead of using this decorator, you can also call the constraint itself:

@constr(*param_adders)

but remember that:

  • Python 3.9 is the first that allows arbitrary expressions on the right of @;

  • using a long conditional/composite constraint as decorator may be less readable.

In these cases, you may consider using @constrained_params.

New in version 0.9.0.

Parameters

  • constr (cloup.constraints._core.Constraint) – an instance of Constraint

  • param_adders (Callable[[Callable[[..], Any]], Callable[[..], Any]]) – function decorators, each attaching a single parameter to the decorated function.

Return type

Callable[[F], F]

class cloup.constraints._support.BoundConstraint[source]

Bases: NamedTuple

Internal utility NamedTuple that represents a Constraint bound to a collection of click.Parameter instances. Note: this is not a subclass of Constraint.

Parameters
constraint :cloup.constraints._core.Constraint
params :Sequence[click.Parameter]
check_consistency(self)[source]
Return type

None

check_values(self, ctx)[source]
Parameters

ctx (click.Context) –

Return type

None

get_help_record(self, ctx)[source]
Parameters

ctx (click.Context) –

Return type

Optional[Tuple[str, str]]

class cloup.constraints._support.ConstraintMixin(*args, constraints=(), show_constraints=None, **kwargs)[source]

Provides support for constraints.

Parameters

  • constraints (Sequence[Union[cloup.constraints._support.BoundConstraintSpec, cloup.constraints._support.BoundConstraint]]) – sequence of constraints bound to specific groups of parameters. Note that constraints applied to option groups are collected from the option groups themselves, so they don’t need to be included in this argument.

  • show_constraints (Optional[bool]) – whether to include a “Constraint” section in the command help. This is also available as a context setting having a lower priority than this attribute.

  • args (Any) – positional arguments forwarded to the next class in the MRO

  • kwargs (Any) – keyword arguments forwarded to the next class in the MRO

optgroup_constraints

Constraints applied to OptionGroup instances.

param_constraints :Tuple[BoundConstraint, Ellipsis]

Constraints registered using @constraint (or equivalent method).

all_constraints

All constraints applied to parameter/option groups of this command.

parse_args(self, ctx, args)[source]
Parameters
Return type

List[str]

get_param_by_name(self, name)[source]
Parameters

name (str) –

Return type

click.Parameter

get_params_by_name(self, names)[source]
Parameters

names (Iterable[str]) –

Return type

Sequence[click.Parameter]

format_constraints(self, ctx, formatter)[source]
Parameters
Return type

None

must_show_constraints(self, ctx)[source]
Parameters

ctx (click.Context) –

Return type

bool

cloup.constraints._support.ensure_constraints_support(command)[source]
Parameters

command (click.core.Command) –

Return type

cloup.constraints._support.ConstraintMixin