1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
.. _constraints:
``datalad-next``'s Constraint System
************************************
``datalad_next.constraints`` implements a system to perform data validation, coercion, and parameter documentation for commands via a flexible set of "Constraints".
You can find an overview of available Constraints in the respective module overview of the :ref:`pyutils`.
Adding parameter validation to a command
----------------------------------------
In order to equip an existing or new command with the constraint system, the following steps are required:
* Set the commands base class to ``ValidatedInterface``:
.. code-block:: python
from datalad_next.commands import ValidatedInterface
@build_doc
class MyCommand(ValidatedInterface):
"""Download from URLs"""
* Declare a ``_validator_`` class member:
.. code-block:: python
from datalad_next.commands import (
EnsureCommandParameterization,
ValidatedInterface,
)
@build_doc
class MyCommand(ValidatedInterface):
"""Download from URLs"""
_validator_ = EnsureCommandParameterization(dict(
[...]
))
* Determine for each parameter of the command whether it has constraints, and what those constraints are.
If you're transitioning an existing command, remove any ``constraints=`` declaration in the ``_parameter_`` class member.
* Add a fitting Constraint declaration for each parameter into the ``_validator_`` as a key-value pair where the key is the parameter and its value is a Constraint.
There does not need to be a Constraint per parameter; only add entries for parameters that need validation.
.. code-block:: python
from datalad_next.commands import (
EnsureCommandParameterization,
ValidatedInterface,
)
from datalad_next.constraints import EnsureChoice
from datalad_next.constraints import EnsureDataset
@build_doc
class Download(ValidatedInterface):
"""Download from URLs"""
_validator_ = EnsureCommandParameterization(dict(
dataset=EnsureDataset(installed=True),
force=EnsureChoice('yes','no','maybe'),
))
Combining constraints
"""""""""""""""""""""
Constraints can be combined in different ways.
The ``|``, ``&``, and ``()`` operators allow ``AND``, ``OR``, and grouping of Constraints.
The following example from the ``download`` command defines a chain of possible Constraints:
.. code-block:: python
spec_item_constraint = url2path_constraint | (
(
EnsureJSON() | EnsureURLFilenamePairFromURL()
) & url2path_constraint)
Constrains can also be combined using ``AnyOf`` or ``AllOf`` MultiConstraints, which correspond almost entirely to ``|`` and ``&``.
Here's another example from the ``download`` command:
.. code-block:: python
spec_constraint = AnyOf(
spec_item_constraint,
EnsureListOf(spec_item_constraint),
EnsureGeneratorFromFileLike(
spec_item_constraint,
exc_mode='yield',
),
One can combine an arbitrary number of Constraints.
They are evaluated in the order in which they were specified.
Logical OR constraints will return the value from the first constraint that does not raise an exception, and logical AND constraints pass the return values of each constraint into the next.
Implementing additional constraints
-----------------------------------
TODO
Parameter Documentation
-----------------------
TODO
|
