Implementation of proposed syntax changes

pydra/design/base.py

@@ -244,12 +244,14 @@ class Arg(Field):
         the default value for the field, by default it is NO_DEFAULT
     help: str
         A short description of the input field.
-    allowed_values: list, optional
-        List of allowed values for the field.
     requires: list, optional
         Names of the inputs that are required together with the field.
-    xor: list[str], optional
-        Names of the inputs that are mutually exclusive with the field.
+    allowed_values: Sequence, optional
+        List of allowed values for the field.
+    xor: Sequence[str | None], optional
+        Names of args that are exclusive mutually exclusive, which must include
+        the name of the current field. If this list includes None, then none of the
+        fields need to be set.
     copy_mode: File.CopyMode, optional
         The mode of copying the file, by default it is File.CopyMode.any
     copy_collation: File.CopyCollation, optional
@@ -263,15 +265,20 @@ class Arg(Field):
         it is False
     """
 
-    allowed_values: tuple = attrs.field(default=(), converter=tuple)
-    xor: tuple[str] = attrs.field(default=(), converter=tuple)
+    allowed_values: frozenset = attrs.field(default=(), converter=frozenset)
+    xor: frozenset[str | None] = attrs.field(default=(), converter=frozenset)
     copy_mode: File.CopyMode = File.CopyMode.any
     copy_collation: File.CopyCollation = File.CopyCollation.any
     copy_ext_decomp: File.ExtensionDecomposition = File.ExtensionDecomposition.single
     readonly: bool = False
 
     @xor.validator
     def _xor_validator(self, _, value):
+        for v in value:
+            if not isinstance(v, (str, type(None))):
+                raise ValueError(
+                    f"xor values must be strings or None, not {v} ({self!r})"
+                )
         if value and self.type not in (ty.Any, bool) and not is_optional(self.type):
             raise ValueError(
                 f"Fields that have 'xor' must be of boolean or optional type, "

pydra/design/boutiques.py

@@ -28,8 +28,10 @@ class arg(shell.arg):
         List of allowed values for the field.
     requires: list, optional
         Names of the inputs that are required together with the field.
-    xor: list[str], optional
-        Names of the inputs that are mutually exclusive with the field.
+    xor: list[str | None], optional
+        Names of args that are exclusive mutually exclusive, which must include
+        the name of the current field. If this list includes None, then none of the
+        fields need to be set.
     copy_mode: File.CopyMode, optional
         The mode of copying the file, by default it is File.CopyMode.any
     copy_collation: File.CopyCollation, optional

pydra/design/python.py

@@ -33,8 +33,10 @@ class arg(Arg):
         List of allowed values for the field.
     requires: list, optional
         Names of the inputs that are required together with the field.
-    xor: list, optional
-        Names of the inputs that are mutually exclusive with the field.
+    xor: list[str | None], optional
+        Names of args that are exclusive mutually exclusive, which must include
+        the name of the current field. If this list includes None, then none of the
+        fields need to be set.
     copy_mode: File.CopyMode, optional
         The mode of copying the file, by default it is File.CopyMode.any
     copy_collation: File.CopyCollation, optional

pydra/design/shell.py

@@ -56,8 +56,10 @@ class arg(Arg):
         List of allowed values for the field.
     requires: list, optional
         List of field names that are required together with the field.
-    xor: list, optional
-        List of field names that are mutually exclusive with the field.
+    xor: list[str | None], optional
+        Names of args that are exclusive mutually exclusive, which must include
+        the name of the current field. If this list includes None, then none of the
+        fields need to be set.
     copy_mode: File.CopyMode, optional
         The mode of copying the file, by default it is File.CopyMode.any
     copy_collation: File.CopyCollation, optional
@@ -192,8 +194,10 @@ class outarg(arg, Out):
         List of allowed values for the field.
     requires: list, optional
         List of field names that are required together with the field.
-    xor: list, optional
-        List of field names that are mutually exclusive with the field.
+    xor: list[str | None], optional
+        Names of args that are exclusive mutually exclusive, which must include
+        the name of the current field. If this list includes None, then none of the
+        fields need to be set.
     copy_mode: File.CopyMode, optional
         The mode of copying the file, by default it is File.CopyMode.any
     copy_collation: File.CopyCollation, optional

pydra/design/tests/test_shell.py

@@ -502,14 +502,14 @@ class Ls(ShellDef["Ls.Outputs"]):
                 argstr="-T",
                 default=False,
                 requires=["long_format"],
-                xor=["date_format_str"],
+                xor=["complete_date", "date_format_str", None],
             )
             date_format_str: str | None = shell.arg(
                 help="format string for ",
                 argstr="-D",
                 default=None,
                 requires=["long_format"],
-                xor=["complete_date"],
+                xor=["complete_date", "date_format_str", None],
             )
 
             @shell.outputs
@@ -557,15 +557,15 @@ class Outputs(ShellOutputs):
                     argstr="-T",
                     default=False,
                     requires=["long_format"],
-                    xor=["date_format_str"],
+                    xor=["complete_date", "date_format_str", None],
                 ),
                 "date_format_str": shell.arg(
                     type=str | None,
                     help="format string for ",
                     default=None,
                     argstr="-D",
                     requires=["long_format"],
-                    xor=["complete_date"],
+                    xor=["date_format_str", "complete_date", None],
                 ),
             },
             outputs={

pydra/design/workflow.py

@@ -37,8 +37,10 @@ class arg(Arg):
         List of allowed values for the field.
     requires: list, optional
         Names of the inputs that are required together with the field.
-    xor: list, optional
-        Names of the inputs that are mutually exclusive with the field.
+    xor: list[str | None], optional
+        Names of args that are exclusive mutually exclusive, which must include
+        the name of the current field. If this list includes None, then none of the
+        fields need to be set.
     copy_mode: File.CopyMode, optional
         The mode of copying the file, by default it is File.CopyMode.any
     copy_collation: File.CopyCollation, optional

pydra/engine/specs.py

@@ -503,13 +503,13 @@ def _rule_violations(self) -> list[str]:
 
             # Collect alternative fields associated with this field.
             if field.xor:
-                mutually_exclusive = {name: self[name] for name in field.xor}
+                mutually_exclusive = {name: self[name] for name in field.xor if name}
                 are_set = [f"{n}={v!r}" for n, v in mutually_exclusive.items() if v]
                 if len(are_set) > 1:
                     errors.append(
                         f"Mutually exclusive fields ({', '.join(are_set)}) are set together"
                     )
-                elif not are_set:
+                elif not are_set and None not in field.xor:
                     errors.append(
                         "At least one of the mutually exclusive fields should be set: "
                         + ", ".join(f"{n}={v!r}" for n, v in mutually_exclusive.items())
@@ -568,7 +568,7 @@ def _check_arg_refs(cls, inputs: list[Arg], outputs: list[Out]) -> None:
                     f"of {field} " + str(list(unrecognised))
                 )
         for inpt in inputs.values():
-            if unrecognised := set(inpt.xor) - input_names:
+            if unrecognised := inpt.xor - (input_names | {None}):
                 raise ValueError(
                     "'Unrecognised' field names in referenced in the xor "
                     f"of {inpt} " + str(list(unrecognised))

pydra/engine/tests/test_helpers_file.py

@@ -393,13 +393,14 @@ def test_template_formatting(tmp_path: Path):
     field.name = "grad"
     field.argstr = "--grad"
     field.path_template = ("{in_file}.bvec", "{in_file}.bval")
-    inputs = Mock()
-    inputs_dict = {"in_file": "/a/b/c/file.txt", "grad": True}
+    field.keep_extension = False
+    definition = Mock()
+    values = {"in_file": Path("/a/b/c/file.txt"), "grad": True}
 
     assert template_update_single(
         field,
-        inputs,
-        input_values=inputs_dict,
+        definition,
+        values=values,
         output_dir=tmp_path,
         spec_type="input",
     ) == [tmp_path / "file.bvec", tmp_path / "file.bval"]

pydra/engine/tests/test_shelltask_inputspec.py

@@ -1125,7 +1125,7 @@ class Outputs(ShellOutputs):
             help="inpA",
             argstr="",
         )
-        inpStr: str = shell.arg(
+        inpStr: Path = shell.arg(
             position=2,
             help="inp str with extension",
             argstr="-i",

pydra/engine/tests/test_task.py

@@ -1449,11 +1449,11 @@ class Defn(ShellDef["Defn.Outputs"]):
         class Outputs(ShellOutputs):
             pass
 
-    inputs = Defn(a1_field="1", b2_field=2.0, c3_field={"c": "3"}, d4_field=["4"])
+    values = dict(a1_field="1", b2_field=2.0, c3_field={"c": "3"}, d4_field=["4"])
     assert (
         argstr_formatting(
             "{a1_field} {b2_field:02f} -test {c3_field[c]} -me {d4_field[0]}",
-            inputs,
+            values,
         )
         == "1 2.000000 -test 3 -me 4"
     )