diff --git a/docs/bids_app/plugins.md b/docs/bids_app/plugins.md new file mode 100644 index 00000000..a2fbfcd7 --- /dev/null +++ b/docs/bids_app/plugins.md @@ -0,0 +1,32 @@ +# Plugins + +Plugins are a Snakebids feature that allow you to add arbitrary behaviour to your Snakebids app after CLI arguments are parsed but before Snakemake is invoked. For example, you might add BIDS validation of an input dataset to your app via a plugin, so your app is only run if the input dataset is valid. + +A plugin is simply a function that takes a {class}`SnakeBidsApp ` as input and returns either a modified {class}`SnakeBidsApp ` or `None`. To add one or more plugins to your {class}`SnakeBidsApp `, use the method {func}`add_plugins `, which will typically be easiest in a `run.py` or similar entrypoint to your app. Your plugin will have access to CLI parameters (after they've been parsed) via their names in {attr}`SnakeBidsApp.config `. Any modifications to that config dictionary will be carried forward into the workflow. + +As an example, a plugin could run the [BIDS Validator](https://github.com/bids-standard/bids-validator) on the input directory like so: + +``` +import subprocess + +from snakebids.app import SnakeBidsApp + +def bids_validate(app: SnakeBidsApp) -> None: + if app.config["skip_bids_validation"]: + return + + try: + subprocess.run(["bids-validator", app.config["bids_dir"]], check=True) + except subprocess.CalledProcessError as err: + raise InvalidBidsError from err + +class InvalidBidsError(Exception): + """Error raised if an input BIDS dataset is invalid.""" + +app = SnakeBidsApp("path/to/snakebids/app") +app.add_plugins([bids_validate]) +app.run_snakemake() + +``` + +You would also want to add some logic to check if the BIDS Validator is installed and pass along the error message, but the point is that a plugin can do anything that can be handled by a Python function. diff --git a/docs/index.md b/docs/index.md index b99997ae..b81dbbfc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,6 +39,7 @@ bids_function/overview bids_app/overview bids_app/config bids_app/workflow +bids_app/plugins ``` ```{toctree} diff --git a/snakebids/app.py b/snakebids/app.py index b1f16a3e..79757085 100644 --- a/snakebids/app.py +++ b/snakebids/app.py @@ -1,10 +1,12 @@ """Tools to generate a Snakemake-based BIDS app.""" +from __future__ import annotations import argparse import logging import sys +from collections.abc import Iterable from pathlib import Path -from typing import Any, Dict, List, Optional +from typing import Any, Callable, Dict, List, Optional import attr import boutiques.creator as bc @@ -111,6 +113,31 @@ class SnakeBidsApp: takes_self=True, ) args: Optional[SnakebidsArgs] = None + plugins: list[Callable[[SnakeBidsApp], None | SnakeBidsApp]] = attr.Factory(list) + + def add_plugins( + self, plugins: Iterable[Callable[[SnakeBidsApp], None | SnakeBidsApp]] + ): + """Supply list of methods to be called after CLI parsing. + + Each callable in ``plugins`` should take, as a single argument, a + reference to the ``SnakeBidsApp``. Plugins may perform any arbitrary + side effects, including updates to the config dictionary, validation + of inputs, optimization, or other enhancements to the snakebids app. + + CLI parameters may be read from ``SnakeBidsApp.config``. Plugins + are responsible for documenting what properties they expect to find + in the config. + + Every plugin should return either: + + - Nothing, in which case any changes to the SnakeBidsApp will + persist in the workflow. + - A ``SnakeBidsApp``, which will replace the existing instance, + so this option should be used with care. + """ + # pylint: disable=no-member + self.plugins.extend(plugins) def run_snakemake(self): """Run snakemake with that config. @@ -187,10 +214,15 @@ def run_snakemake(self): new_config_file = args.outputdir / self.configfile_path self.config["root"] = "" + app = self + # pylint: disable=not-an-iterable + for plugin in self.plugins: + app = plugin(app) or app + # Write the config file write_config_file( config_file=new_config_file, - data=self.config, + data=app.config, force_overwrite=True, ) @@ -202,14 +234,14 @@ def run_snakemake(self): None, [ "--snakefile", - str(self.snakefile_path), + str(app.snakefile_path), "--directory", str(cwd), "--configfile", str(new_config_file.resolve()), - *self.config["snakemake_args"], - *self.config["targets_by_analysis_level"][ - self.config["analysis_level"] + *app.config["snakemake_args"], + *app.config["targets_by_analysis_level"][ + app.config["analysis_level"] ], ], ) diff --git a/snakebids/tests/test_app.py b/snakebids/tests/test_app.py index 63b90afb..2d252a41 100644 --- a/snakebids/tests/test_app.py +++ b/snakebids/tests/test_app.py @@ -162,6 +162,34 @@ def test_runs_in_correct_mode( ] ) + def test_plugins(self, mocker: MockerFixture, app: SnakeBidsApp): + # Get mocks for all the io functions + self.io_mocks(mocker) + mocker.patch.object( + sn_app, + "update_config", + side_effect=lambda config, sn_args: config.update(sn_args.args_dict), + ) + output_dir = Path("app") / "results" + app.args = SnakebidsArgs( + force=False, + outputdir=output_dir, + snakemake_args=[], + args_dict={"output_dir": output_dir.resolve()}, + ) + + def plugin(my_app): + my_app.foo = "bar" + + app.add_plugins([plugin]) + try: + app.run_snakemake() + except SystemExit as e: + print("System exited prematurely") + print(e) + + assert app.foo == "bar" + class TestGenBoutiques: def test_boutiques_descriptor(self, tmp_path: Path, app: SnakeBidsApp):