datalad_next.constraints.exceptions
Custom exceptions raised by Constraint
implementations
- exception datalad_next.constraints.exceptions.CommandParametrizationError(exceptions: Union[Dict[str, ConstraintError], Dict[ParameterConstraintContext, ConstraintError]])[source]
Bases:
ParametrizationErrors
Exception type raised on violating any command parameter constraints
See also
- exception datalad_next.constraints.exceptions.ConstraintError(constraint, value: Any, msg: str, ctx: Optional[Dict[str, Any]] = None)[source]
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: Optional[Tuple[Exception]]
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 theConstraint
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 thecaused_by
report of the error.
Message template can use any feature of the Python format mini language. For example
{__value__!r}
to get arepr()
-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])[source]
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, datalad_next.constraints.exceptions.ConstraintError]
- class datalad_next.constraints.exceptions.ParameterConstraintContext(parameters: Tuple[str], description: str | None = None)[source]
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 followingParameterConstraintContext
andConstraintError
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 standardConstraint
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 [source]
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])[source]
Bases:
Mapping
Read-only convenience that wraps a
ConstraintErrors
error mapping- property context_labels
- property messages
- exception datalad_next.constraints.exceptions.ParametrizationErrors(exceptions: Union[Dict[str, ConstraintError], Dict[ParameterConstraintContext, ConstraintError]])[source]
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 aConstraintError
arising from high-order constraints, such as the violation of "mutually exclusive" requirements across more than one parameter.- property errors: ParameterContextErrors