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.
- property passthrough: Any
Returns the set pass-through value
- 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.
- 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
- class datalad_next.constraints.compound.EnsureListOf(item_constraint: Callable, min_len: int | None = None, max_len: int | None = None)[source]
Bases:
EnsureIterableOf
- 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.
- class datalad_next.constraints.compound.EnsureTupleOf(item_constraint: Callable, min_len: int | None = None, max_len: int | None = None)[source]
Bases:
EnsureIterableOf
- 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.