datalad_next.constraints.compound

Constraints that wrap or contain other constraints

class datalad_next.constraints.compound.ConstraintWithPassthrough(constraint: Constraint, passthrough: Any)[source]

Bases: Constraint

Regular constraint, but with a "pass-through" value that is not processed

This is different from a Constraint() | EnsureValue(...) construct, because the pass-through value is not communicated. This can be useful when a particular value must be supported for technical reasons, but need not, or must not be included in (error) messages.

The pass-through is returned as-is, and is not processed except for an identity check (==).

For almost all reporting (__str__, descriptions, ...) the wrapped value constraint is used, making this class virtually invisible. Only __repr__ reflects the wrapping.

property constraint: Constraint

Returns the wrapped constraint instance

for_dataset(dataset: DatasetParameter) Constraint[source]

Wrap the wrapped constraint again after tailoring it for the dataset

The pass-through value is re-used.

long_description() str[source]

This method is deprecated. Use input_description instead

property passthrough: Any

Returns the set pass-through value

short_description() str[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.compound.EnsureGeneratorFromFileLike(item_constraint: Callable, exc_mode: str = 'raise')[source]

Bases: Constraint

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

A given value can either be a file-like (the outcome of open(), or StringIO), or - as an alias of STDIN, or a path to an existing file to be read from.

short_description()[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.compound.EnsureIterableOf(iter_type: type, item_constraint: Callable, min_len: int | None = None, max_len: int | None = None)[source]

Bases: Constraint

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

property item_constraint
short_description()[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.compound.EnsureListOf(item_constraint: Callable, min_len: int | None = None, max_len: int | None = None)[source]

Bases: EnsureIterableOf

short_description()[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.compound.EnsureMapping(key: Constraint, value: Constraint, delimiter: str = ':', allow_length2_sequence: bool = True)[source]

Bases: Constraint

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

for_dataset(dataset: DatasetParameter) Constraint[source]

Return a constraint-variant for a specific dataset context

The default implementation returns the unmodified, identical constraint. However, subclasses can implement different behaviors.

short_description()[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.compound.EnsureTupleOf(item_constraint: Callable, min_len: int | None = None, max_len: int | None = None)[source]

Bases: EnsureIterableOf

short_description()[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.compound.WithDescription(constraint: Constraint, *, input_synopsis: str | None = None, input_description: str | None = None, error_message: str | None = None, input_synopsis_for_ds: str | None = None, input_description_for_ds: str | None = None, error_message_for_ds: str | None = None)[source]

Bases: Constraint

Constraint that wraps another constraint and replaces its description

Whenever a constraint's self-description does not fit an application context, it can be wrapped with this class. The given synopsis and description of valid inputs replaces those of the wrapped constraint.

property constraint: Constraint

Returns the wrapped constraint instance

for_dataset(dataset: DatasetParameter) Constraint[source]

Wrap the wrapped constraint again after tailoring it for the dataset

property input_description

Returns full description of valid input for a constraint

Like input_synopsis this information is user-facing. In contrast, to the synopsis there is length/line limit. Nevertheless, the information should be presented in a compact fashion that avoids needless verbosity. If possible, a single paragraph is a good format. If multiple paragraphs are necessary, they should be separated by a single, empty line.

Rendering code may indent, or rewrap the text, so no line-by-line formatting will be preserved.

If possible, the synopsis should be written in a UI/API-agnostic fashion. However, if this is impossible or leads to imprecisions or confusion, it should focus on use within Python code and with Python data types. Tailored documentation can be provided via the WithDescription wrapper.

property input_synopsis

Returns brief, single line summary of valid input for a constraint

This information is user-facing, and to be used in any place where space is limited (tooltips, usage summaries, etc).

If possible, the synopsis should be written in a UI/API-agnostic fashion. However, if this is impossible or leads to imprecisions or confusion, it should focus on use within Python code and with Python data types. Tailored documentation can be provided via the WithDescription wrapper.

long_description() str[source]

This method is deprecated. Use input_description instead

short_description() str[source]

This method is deprecated. Use input_synopsis instead