feat: Conditional parameters (HEXA-1687)

Author: mrivar

openhexa/sdk/pipelines/parameter/decorator.py

@@ -51,6 +51,7 @@ def __init__(
         required: bool = True,
         multiple: bool = False,
         directory: str | None = None,
+        disables: typing.Sequence[str] | None = None,
     ):
         validate_pipeline_parameter_code(code)
         self.code = code
@@ -92,6 +93,7 @@ def __init__(
         self.widget = widget
         self.connection = connection
         self.directory = directory
+        self.disables = list(disables) if disables else None
 
         self._validate_default(default, multiple)
         self.default = default
@@ -117,6 +119,7 @@ def to_dict(self) -> dict[str, typing.Any]:
             "required": self.required,
             "multiple": self.multiple,
             "directory": self.directory,
+            "disables": self.disables,
         }
         if isinstance(self.choices, ChoicesFromFile):
             d["choices_from_file"] = self.choices.to_dict()
@@ -207,6 +210,28 @@ def validate_parameters(parameters: list[Parameter]):
     supported_connection_types = {DHIS2ConnectionType, IASOConnectionType}
     connection_parameters = {p.code for p in parameters if type(p.type) in supported_connection_types}
 
+    parameters_by_code = {p.code: p for p in parameters}
+    controllers = {p.code for p in parameters if p.disables}
+    for parameter in parameters:
+        if not parameter.disables:
+            continue
+        if not isinstance(parameter.type, Boolean):
+            raise InvalidParameterError(
+                f"Only boolean parameters can use 'disables'. Parameter '{parameter.code}' is of type {parameter.type}."
+            )
+        for target_code in parameter.disables:
+            if target_code == parameter.code:
+                raise InvalidParameterError(f"Parameter '{parameter.code}' cannot disable itself.")
+            if target_code not in parameters_by_code:
+                raise InvalidParameterError(
+                    f"Parameter '{parameter.code}' disables a non-existing parameter '{target_code}'."
+                )
+            if target_code in controllers:
+                raise InvalidParameterError(
+                    f"Parameter '{parameter.code}' disables '{target_code}', which is itself a disabling "
+                    f"parameter. Chaining disabling parameters is not supported."
+                )
+
     for parameter in parameters:
         if parameter.connection and parameter.connection not in connection_parameters:
             raise InvalidParameterError(
@@ -251,6 +276,7 @@ def parameter(
     required: bool = True,
     multiple: bool = False,
     directory: str | None = None,
+    disables: typing.Sequence[str] | None = None,
 ):
     """Decorate a pipeline function by attaching a parameter to it..
 
@@ -282,6 +308,10 @@ def parameter(
         values of the chosen type)
     directory : str, optional
         An optional parameter to force file selection to specific directory (only used for parameter type File). If the directory does not exist, it will be ignored.
+    disables : sequence of str, optional
+        An optional list of parameter codes to disable when this (boolean) parameter is set to ``True``. Disabled
+        parameters are hidden/greyed out in the run form, their required check is skipped, and they are omitted from
+        the run config (the pipeline function receives their default value). Only boolean parameters can use this.
 
     Returns
     -------
@@ -305,6 +335,7 @@ def decorator(fun):
                 connection=connection,
                 multiple=multiple,
                 directory=directory,
+                disables=disables,
             ),
         )
 

openhexa/sdk/pipelines/pipeline.py

@@ -123,9 +123,16 @@ def _validate_config(self, config: dict[str, typing.Any]) -> dict[str, typing.An
         ParameterValueError
             If the config contains invalid keys or parameter validation fails.
         """
+        disabled_codes = self._get_disabled_codes(config)
+
         validated_config = {}
         for parameter in self.parameters:
             value = config.pop(parameter.code, None)
+            if parameter.code in disabled_codes:
+                # Parameter is disabled by an active controller: ignore the (possibly dummy or missing)
+                # value, skip required/type validation, and fall back to its default.
+                validated_config[parameter.code] = parameter.default
+                continue
             validated_value = parameter.validate(value)
             validated_config[parameter.code] = validated_value
 
@@ -134,6 +141,22 @@ def _validate_config(self, config: dict[str, typing.Any]) -> dict[str, typing.An
 
         return validated_config
 
+    def _get_disabled_codes(self, config: dict[str, typing.Any]) -> set[str]:
+        """Return the codes of parameters disabled by an active controller in the given config.
+
+        A controller is a boolean parameter declaring ``disables=[...]``. It is "active" when its effective
+        value (from the config, falling back to its default) is truthy. A parameter is disabled if any active
+        controller lists it.
+        """
+        disabled_codes: set[str] = set()
+        for parameter in self.parameters:
+            if not parameter.disables:
+                continue
+            effective_value = config.get(parameter.code, parameter.default)
+            if effective_value:
+                disabled_codes.update(parameter.disables)
+        return disabled_codes
+
     def _execute_tasks(self, pool):
         """Execute all tasks using the provided multiprocessing pool.
 

openhexa/sdk/pipelines/runtime.py

@@ -316,6 +316,7 @@ def get_pipeline(pipeline_path: Path) -> Pipeline:
                     Argument("required", [ast.Constant], default_value=True),
                     Argument("multiple", [ast.Constant], default_value=False),
                     Argument("directory", [ast.Constant]),
+                    Argument("disables", [ast.List]),
                 ),
             )
 

tests/test_ast.py

@@ -154,13 +154,37 @@ def test_pipeline_with_int_param(self):
                             "help": "Param help",
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         }
                     ],
                     "timeout": None,
                     "functional_type": None,
                 },
             )
 
+    def test_pipeline_with_disables_param(self):
+        """The @parameter decorator's 'disables' list is parsed from the pipeline code."""
+        with tempfile.TemporaryDirectory() as tmpdirname:
+            with open(f"{tmpdirname}/pipeline.py", "w") as f:
+                f.write(
+                    "\n".join(
+                        [
+                            "from openhexa.sdk.pipelines import pipeline, parameter",
+                            "",
+                            "@parameter('run_report_only', type=bool, default=False, disables=['data_input'])",
+                            "@parameter('data_input', type=str)",
+                            "@pipeline('Test pipeline')",
+                            "def test_pipeline():",
+                            "    pass",
+                            "",
+                        ]
+                    )
+                )
+            pipeline = get_pipeline(tmpdirname)
+            params = {p["code"]: p for p in pipeline.to_dict()["parameters"]}
+            self.assertEqual(params["run_report_only"]["disables"], ["data_input"])
+            self.assertIsNone(params["data_input"]["disables"])
+
     def test_pipeline_with_multiple_param(self):
         """The file contains a @pipeline decorator and a @parameter decorator with multiple=True."""
         with tempfile.TemporaryDirectory() as tmpdirname:
@@ -198,6 +222,7 @@ def test_pipeline_with_multiple_param(self):
                             "help": "Param help",
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         }
                     ],
                     "timeout": None,
@@ -243,6 +268,7 @@ def test_pipeline_with_dataset(self):
                             "help": "Dataset",
                             "required": False,
                             "directory": None,
+                            "disables": None,
                         }
                     ],
                     "timeout": None,
@@ -287,6 +313,7 @@ def test_pipeline_with_choices(self):
                             "help": "Param help",
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         }
                     ],
                     "timeout": None,
@@ -359,6 +386,7 @@ def test_pipeline_with_bool(self):
                             "help": "Param help",
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         }
                     ],
                     "timeout": None,
@@ -404,6 +432,7 @@ def test_pipeline_with_multiple_parameters(self):
                             "help": "Param help",
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         },
                         {
                             "choices": ["a", "b"],
@@ -417,6 +446,7 @@ def test_pipeline_with_multiple_parameters(self):
                             "help": "Param help 2",
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         },
                     ],
                     "timeout": None,
@@ -484,6 +514,7 @@ def test_pipeline_with_connection_parameter_for_dhis2(self):
                             "help": None,
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         },
                         {
                             "code": "data_element_ids",
@@ -497,6 +528,7 @@ def test_pipeline_with_connection_parameter_for_dhis2(self):
                             "help": None,
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         },
                     ],
                     "timeout": None,
@@ -546,6 +578,7 @@ def test_pipeline_with_connection_parameter_for_iaso(self):
                             "help": None,
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         },
                         {
                             "code": "org_units",
@@ -559,6 +592,7 @@ def test_pipeline_with_connection_parameter_for_iaso(self):
                             "help": None,
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         },
                         {
                             "code": "projects",
@@ -572,6 +606,7 @@ def test_pipeline_with_connection_parameter_for_iaso(self):
                             "help": None,
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         },
                         {
                             "code": "forms",
@@ -585,6 +620,7 @@ def test_pipeline_with_connection_parameter_for_iaso(self):
                             "help": None,
                             "required": True,
                             "directory": None,
+                            "disables": None,
                         },
                     ],
                     "timeout": None,

tests/test_parameter.py

@@ -36,6 +36,7 @@
     SecretType,
     StringType,
     parameter,
+    validate_parameters,
 )
 from openhexa.utils import stringcase
 
@@ -422,3 +423,52 @@ def a_function():
     assert function_parameters[1].default == ["yo"]
     assert function_parameters[1].required is False
     assert function_parameters[1].multiple is True
+
+
+def test_parameter_disables_serialization():
+    """The 'disables' option is normalized to a list and serialized in to_dict."""
+    no_disables = Parameter("plain", type=str)
+    assert no_disables.disables is None
+    assert no_disables.to_dict()["disables"] is None
+
+    controller = Parameter("run_report_only", type=bool, disables=["data_input", "year"])
+    assert controller.disables == ["data_input", "year"]
+    assert controller.to_dict()["disables"] == ["data_input", "year"]
+
+
+def test_validate_parameters_disables_ok():
+    """A valid disabling setup passes validation."""
+    controller = Parameter("run_report_only", type=bool, default=False, disables=["data_input"])
+    data_input = Parameter("data_input", type=str, required=True)
+    validate_parameters([controller, data_input])
+
+
+def test_validate_parameters_disables_must_be_boolean():
+    """Only boolean parameters can use 'disables'."""
+    controller = Parameter("mode", type=str, disables=["data_input"])
+    data_input = Parameter("data_input", type=str)
+    with pytest.raises(InvalidParameterError):
+        validate_parameters([controller, data_input])
+
+
+def test_validate_parameters_disables_unknown_target():
+    """Disabling a non-existing parameter raises."""
+    controller = Parameter("run_report_only", type=bool, disables=["does_not_exist"])
+    with pytest.raises(InvalidParameterError):
+        validate_parameters([controller])
+
+
+def test_validate_parameters_disables_self_reference():
+    """A parameter cannot disable itself."""
+    controller = Parameter("run_report_only", type=bool, disables=["run_report_only"])
+    with pytest.raises(InvalidParameterError):
+        validate_parameters([controller])
+
+
+def test_validate_parameters_disables_no_chaining():
+    """A disabling parameter cannot disable another disabling parameter."""
+    controller_a = Parameter("toggle_a", type=bool, disables=["toggle_b"])
+    controller_b = Parameter("toggle_b", type=bool, disables=["plain_c"])
+    plain_c = Parameter("plain_c", type=str)
+    with pytest.raises(InvalidParameterError):
+        validate_parameters([controller_a, controller_b, plain_c])

tests/test_pipeline.py

@@ -52,6 +52,41 @@ def test_pipeline_run_extra_config():
         pipeline.run({"arg1": "ok", "arg2": "extra"})
 
 
+def test_pipeline_run_disabled_required_parameter_skipped():
+    """A required parameter disabled by an active controller is skipped and receives its default."""
+    pipeline_func = Mock()
+    controller = Parameter("run_report_only", type=bool, default=False, disables=["data_input"])
+    data_input = Parameter("data_input", type=str, required=True)
+    pipeline = Pipeline("pipeline", pipeline_func, [controller, data_input])
+
+    pipeline.run({"run_report_only": True})
+
+    pipeline_func.assert_called_once_with(run_report_only=True, data_input=None)
+
+
+def test_pipeline_run_disabled_parameter_value_ignored():
+    """A dummy value provided for a disabled parameter is ignored in favor of its default."""
+    pipeline_func = Mock()
+    controller = Parameter("run_report_only", type=bool, default=False, disables=["year"])
+    year = Parameter("year", type=int, required=True, default=2024)
+    pipeline = Pipeline("pipeline", pipeline_func, [controller, year])
+
+    pipeline.run({"run_report_only": True, "year": 1})
+
+    pipeline_func.assert_called_once_with(run_report_only=True, year=2024)
+
+
+def test_pipeline_run_inactive_controller_still_validates():
+    """When the controller is not active, disabled parameters are still validated as usual."""
+    pipeline_func = Mock()
+    controller = Parameter("run_report_only", type=bool, default=False, disables=["data_input"])
+    data_input = Parameter("data_input", type=str, required=True)
+    pipeline = Pipeline("pipeline", pipeline_func, [controller, data_input])
+
+    with pytest.raises(ParameterValueError):
+        pipeline.run({"run_report_only": False})
+
+
 @patch.dict(
     os.environ,
     {"HEXA_SERVER_URL": "https://test.openhexa.org"},