datalad_next.constraints

Data validation, coercion, and parameter documentation

This module provides a set of uniform classes to validate and document particular aspects of inputs. In a nutshell, each of these Constraint class:

  • focuses on a specific aspect, such as data 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 that can be customized by wrapping an instance in WithDescription

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

On (validation/coercion) error, instances raise ConstraintError) via their raise_for() method. This approach to error reporting helps to communicate standard (yet customizable) error messages, aids structured error reporting, and is capable of communication the underlying causes of an error in full detail without the need to generate long textual descriptions.

EnsureCommandParameterization is a particular variant of a Constraint that is capable of validating a complete parameterization of a command (or function), for each parameter individually, and for arbitrary combinations of parameters. It puts a particular emphasis on structured error reporting.

Constraint()

Base class for value coercion/validation.

AllOf(*constraints)

Logical AND for constraints.

AnyOf(*constraints)

Logical OR for constraints.

NoConstraint()

A constraint that represents no constraints

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

Constraint that wraps another constraint and replaces its description

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

Exception type raised by constraints when their conditions are violated

CommandParametrizationError(exceptions)

Exception type raised on violating any command parameter constraints

ParameterConstraintContext(parameters[, ...])

Representation of a parameter constraint context

EnsureDataset([installed, purpose, require_id])

Ensure an absent/present Dataset from any path or Dataset instance

DatasetParameter(original, ds)

Utility class to report an original and resolve dataset parameter value

EnsureBool()

Ensure that an input is a bool.

EnsureCallable()

Ensure an input is a callable object

EnsureChoice(*values)

Ensure an input is element of a set of possible values

EnsureFloat()

Ensure that an input (or several inputs) are of a data type 'float'.

EnsureHashAlgorithm()

Ensure an input matches a name of a hashlib algorithm

EnsureDType(dtype)

Ensure that an input (or several inputs) are of a particular data type.

EnsureInt()

Ensure that an input (or several inputs) are of a data type 'int'.

EnsureKeyChoice(key, values)

Ensure value under a key in an input is in a set of possible values

EnsureNone()

Ensure an input is of value None

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

Ensures input is convertible to a (platform) path and returns a Path

EnsureStr([min_len, match])

Ensure an input is a string of some min.

EnsureStrPrefix(prefix)

Ensure an input is a string that starts with a given prefix.

EnsureRange([min, max])

Ensure an input is within a particular range

EnsureValue(value)

Ensure an input is a particular value

EnsureIterableOf(iter_type, item_constraint)

Ensure that an input is a list of a particular data type

EnsureListOf(item_constraint[, min_len, max_len])

EnsureTupleOf(item_constraint[, min_len, ...])

EnsureMapping(key, value[, delimiter, ...])

Ensure a mapping of a key to a value of a specific nature

EnsureGeneratorFromFileLike(item_constraint)

Ensure a constraint for each item read from a file-like.

EnsureJSON()

Ensures that string is JSON formatted and can be deserialized.

EnsureURL([required, forbidden, match])

Ensures that a string is a valid URL with a select set of components

EnsureParsedURL([required, forbidden, match])

Like EnsureURL, but returns a parsed URL

EnsureGitRefName([allow_onelevel, ...])

Ensures that a reference name is well formed

EnsureRemoteName([known, dsarg])

Ensures a valid remote name, and optionally if such a remote is known

EnsureSiblingName([known, dsarg])

Identical to EnsureRemoteName, but used the term "sibling"

EnsureCommandParameterization(...[, ...])

Base class for ValidatedInterface parameter validators