datalad_core.constraints

Parameter validation, coercion, and documentation

This module provides a set of classes to validate and document parameters. In a nutshell, each of these Constraint classes:

  • focuses on a specific aspect, such as type coercion, or checking particular input properties

  • is instantiated with a set of parameters to customize such an instance for a particular task

  • performs its task by receiving an input via its __call__() method

  • provides default auto-documentation

Individual Constraint instances can be combined with logical and (AllOf) and or (AnyOf) operations to form arbitrarily complex constructs.

For (validation/coercion) errors, a ConstraintError class is provided. This class supports error reporting in a structure fashion with standard (yet customizable) error messages, and is capable of communicating the underlying causes of an error in full detail without the need to generate long textual descriptions.

If the provided input descriptions and error messages of a particular constraint are not an optimal fit for a particular context, they can be replace by wrapping a constraint instance into WithDescription. This creates a new constraint instance that maintains the exact same validation/coercion behavior, but has a targeted description (input synopsis and description, and/or error message template).

Constraint()

Base class for value coercion/validation.

AllOf(*constraints)

Logical AND for constraints.

AnyOf(*constraints)

Logical OR for constraints.

ConstraintError(constraint, value, msg[, ctx])

Exception type raised by constraints when their conditions are violated

WithDescription(constraint, *[, ...])

Constraint that wraps another constraint and replaces its description

NoConstraint()

A constraint that represents no constraints

EnsureChoice(*values)

Ensure an input is element of a set of possible values

EnsureDatasetPath(path_constraint, dataset)

Resolves a path in the context of a particular dataset

EnsurePath(*, path_type, is_format, lexists, ...)

Convert input to a (platform) path and ensures select properties