datalad_core.commands.ParamConstraintContext

class datalad_core.commands.ParamConstraintContext(param_names: tuple[str, ...], description: str | None = None) → None

Bases: object

Representation of a parameter constraint context

This type is used for the keys in the error map of. ParamErrors. Its purpose is to clearly identify which parameter combination (and its nature) led to a ConstraintError.

An error context comprises to components: 1) the names of the parameters that were considered, and 2) a description of the particular aspect of the parameter values is the focus of the constraint. In the simple case of an error occurring in the context of a single parameter, the second component is superfluous.

Example:

A command has two parameters p1 and p2. The may also have respective individual constraints, but importantly they 1) must not have identical values, and 2) their sum must be larger than 3. If the command is called with cmd(p1=1, p2=1), both conditions are violated. The reporting may be implemented using the following ParamConstraintContext and ConstraintError instances:

ParamConstraintContext(('p1', 'p2'), 'inequality):
  ConstraintError(EnsureValue(True), False, <EnsureValue error>)

ParamConstraintContext(('p1', 'p2'), 'sum):
  ConstraintError(EnsureRange(min=3), False, <EnsureRange error>)

where the ConstraintError instances are generated by standard Constraint implementation. For the second error, this could look like:

EnsureRange(min=3)(params['p1'] + params['p2'])

__eq__(other)

Return self==value.

description: str | None = None

get_label_with_parameter_values(values: dict) → str

Like .label but each parameter will also state a value

Return type:

str

property label: str

A concise summary of the context

This label will be a compact as possible.

param_names: tuple[str, ...]