datalad_next.constraints.ParameterConstraintContext

class datalad_next.constraints.ParameterConstraintContext(parameters: Tuple[str], description: str | None = None)

Bases: object

Representation of a parameter constraint context

This type is used for the keys in the error map of. ParametrizationErrors. 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 how the parameters were linked or combined. In the simple case of an error occurring in the context of a single parameter, the second component is superfluous. Otherwise, it can be thought of as an operation label, describing what aspect of the set of parameters is being relevant in a particular context.

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 ParameterConstraintContext and ConstraintError instances:

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

ParameterConstraintContext(('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'])

description: str | None = None

get_label_with_parameter_values(values: dict) → str

Like .label but each parameter will also state a value

property label: str

A concise summary of the context

This label will be a compact as possible.

parameters: Tuple[str]