datalad.api.getexec

datalad.api.getexec(cmd: List[str], path: str, dataset: Dataset | None = None, inputs: List[str] | None = None, message: str | None = None) → Iterable[Dict]

Get a file by executing a command and register the command for future retrievals

The command consists of a list of strings which are passed as is to python's "subprocess.run". No shell interpretation takes place, if you want that you need to execute a shell yourself. In the invocation a last argument naming the output file the command should write to is added. Therefore your command should expect a single argument which specifies it's output path.

Examples

Run an executable script and register it for an output file:

> getexec(["code/script.sh"], path="output.txt")

Use bash and specify the full command:

> getexec(["bash", "-c", 'printf "Hello World!" > "$1"', "test-cmd"], path="output.txt")

Run an executable script which depends on other files and register it for an output file:

> getexec(["code/script.sh", "input1.txt", "input2.txt"], path="output.txt", inputs=["input1.txt", "input2.txt"])
Parameters:

  • cmd (non-empty sequence of str) -- the command to execute and register. The first argument is the program to execute, the following arguments are passed to this program. It is expected that the program takes a target filename as its last argument, which is appended to the full command in the special remote.

  • path (str) -- target for the program execution. If the path is directory, then a string representation of the command will be used as the target filename. Otherwise this parameter is assumed to be the target filename. The target is always assumed to be relative to the dataset.

  • dataset (Dataset or None, optional) -- specify the dataset to execute and register the command in. If no dataset is given, an attempt is made to identify the dataset based on the current working directory. The newly created file will be saved in the dataset. [Default: None]

  • inputs -- a dependency for the getexec command. These dependencies will be fetched by a datalad get before executing the getexec command. The dependencies will be registered in git-annex in a way that they will be fetched on subsequent gets on the file created by getexec. [Default: None]

  • message (str or None, optional) -- commit message to use. If no commit message is given the specified command will be used in a readable format. [Default: None]

  • on_failure ({'ignore', 'continue', 'stop'}, optional) -- behavior to perform on failure: 'ignore' any failure is reported, but does not cause an exception; 'continue' if any failure occurs an exception will be raised at the end, but processing other actions will continue for as long as possible; 'stop': processing will stop on first failure and an exception is raised. A failure is any result with status 'impossible' or 'error'. Raised exception is an IncompleteResultsError that carries the result dictionaries of the failures in its failed attribute. [Default: 'continue']

  • result_filter (callable or None, optional) -- if given, each to-be-returned status dictionary is passed to this callable, and is only returned if the callable's return value does not evaluate to False or a ValueError exception is raised. If the given callable supports **kwargs it will additionally be passed the keyword arguments of the original API call. [Default: None]

  • result_renderer -- select rendering mode command results. 'tailored' enables a command- specific rendering style that is typically tailored to human consumption, if there is one for a specific command, or otherwise falls back on the the 'generic' result renderer; 'generic' renders each result in one line with key info like action, status, path, and an optional message); 'json' a complete JSON line serialization of the full result record; 'json_pp' like 'json', but pretty-printed spanning multiple lines; 'disabled' turns off result rendering entirely; '<template>' reports any value(s) of any result properties in any format indicated by the template (e.g. '{path}', compare with JSON output for all key-value choices). The template syntax follows the Python "format() language". It is possible to report individual dictionary values, e.g. '{metadata[name]}'. If a 2nd-level key contains a colon, e.g. 'music:Genre', ':' must be substituted by '#' in the template, like so: '{metadata[music#Genre]}'. [Default: 'tailored']

  • result_xfm ({'datasets', 'successdatasets-or-none', 'paths', 'relpaths', 'metadata'} or callable or None, optional) -- if given, each to-be-returned result status dictionary is passed to this callable, and its return value becomes the result instead. This is different from result_filter, as it can perform arbitrary transformation of the result value. This is mostly useful for top- level command invocations that need to provide the results in a particular format. Instead of a callable, a label for a pre-crafted result transformation can be given. [Default: None]

  • return_type ({'generator', 'list', 'item-or-list'}, optional) -- return value behavior switch. If 'item-or-list' a single value is returned instead of a one-item return value list, or a list in case of multiple return values. None is return in case of an empty list. [Default: 'list']