datalad_next.constraints.base

Base classes for constraints and their logical connectives

class datalad_next.constraints.base.AllOf(*constraints)[source]

Bases: _MultiConstraint

Logical AND for constraints.

An arbitrary number of constraints can be given. They are evaluated in the order in which they were specified. The return value of each constraint is passed an input into the next. The return value of the last constraint is the global return value. No intermediate exceptions are caught.

Documentation is aggregated for all constraints.

long_description()[source]

This method is deprecated. Use input_description instead

short_description()[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.base.AnyOf(*constraints)[source]

Bases: _MultiConstraint

Logical OR for constraints.

An arbitrary number of constraints can be given. They are evaluated in the order in which they were specified. The value returned by the first constraint that does not raise an exception is the global return value.

Documentation is aggregated for all alternative constraints.

long_description()[source]

This method is deprecated. Use input_description instead

short_description()[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.base.Constraint[source]

Bases: object

Base class for value coercion/validation.

These classes are also meant to be able to generate appropriate documentation on an appropriate parameter value.

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.

property input_description: str

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: str

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()[source]

This method is deprecated. Use input_description instead

raise_for(value, msg, **ctx) None[source]

Convenience method for raising a ConstraintError

The parameters are identical to those of ConstraintError. This method merely passes the Constraint instance as self to the constructor.

short_description()[source]

This method is deprecated. Use input_synopsis instead

class datalad_next.constraints.base.DatasetParameter(original, ds)[source]

Bases: object

Utility class to report an original and resolve dataset parameter value

This is used by EnsureDataset to be able to report the original argument semantics of a dataset parameter to a receiving command. It is consumed by any Constraint.for_dataset().

The original argument is provided via the original property. A corresponding Dataset instance is provided via the ds property.