datalad_next.constraints.exceptions

Custom exceptions raised by Constraint implementations

exception datalad_next.constraints.exceptions.CommandParametrizationError(exceptions: Dict[str, ConstraintError] | Dict[ParameterConstraintContext, ConstraintError])

Bases: ParametrizationErrors

Exception type raised on violating any command parameter constraints

See also

EnsureCommandParameterization

exception datalad_next.constraints.exceptions.ConstraintError(constraint, value: Any, msg: str, ctx: Dict[str, Any] | None = None)

Bases: ValueError

Exception type raised by constraints when their conditions are violated

A primary purpose of this class is to provide uniform means for communicating information on violated constraints.

property caused_by: Tuple[Exception] | None

Returns a tuple of any underlying exceptions that caused a violation

property constraint

Get the instance of the constraint that was violated

property context: mappingproxy

Get a constraint violation's context

This is a mapping of key/value-pairs matching the ctx constructor argument.

property msg

Obtain an (interpolated) message on the constraint violation

The error message template can be interpolated with any information available in the error context dict (ctx). In addition to the information provided by the Constraint that raised the error, the following additional placeholders are provided:

• __value__: the value reported to have caused the error

• __itemized_causes__: an indented bullet list str with on item for each error in the caused_by report of the error.

Message template can use any feature of the Python format mini language. For example {__value__!r} to get a repr()-style representation of the offending value.

property value

Get the value that violated the constraint

exception datalad_next.constraints.exceptions.ConstraintErrors(exceptions: Dict[Any, ConstraintError])

Bases: ConstraintError

Exception representing context-specific ConstraintError instances

This class enables the association of a context in which any particular constraint was violated. This is done by passing a mapping, of a context identifier (e.g., a label) to the particular ConstraintError that occurred in this context, to the constructor.

This is a generic implementation with no requirements regarding the nature of the context identifiers (expect for being hashable). See CommandParametrizationError for a specialization.

property errors: mappingproxy[Any, ConstraintError]

class datalad_next.constraints.exceptions.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]

class datalad_next.constraints.exceptions.ParameterContextErrors(errors: Dict[ParameterConstraintContext, ConstraintError])

Bases: Mapping

Read-only convenience that wraps a ConstraintErrors error mapping

property context_labels

items() → a set-like object providing a view on D's items

property messages

exception datalad_next.constraints.exceptions.ParametrizationErrors(exceptions: Dict[str, ConstraintError] | Dict[ParameterConstraintContext, ConstraintError])

Bases: ConstraintErrors

Exception type raised on violating parameter constraints

This is a ConstraintErrors variant that uses parameter names (i.e, str labels) as context identifiers. In addition to individual parameter names an additional __all__ identifier is recognized. It can be used to record a ConstraintError arising from high-order constraints, such as the violation of "mutually exclusive" requirements across more than one parameter.

property errors: ParameterContextErrors