datasalad.runners.CommandError

exception datasalad.runners.CommandError(cmd: str | list[str], msg: str = '', returncode: int = 32767, stdout: str | bytes = '', stderr: str | bytes = '', cwd: str | PathLike | None = None) → None[source]

Raised when a subprocess execution fails (non-zero exit)

This custom exception combines the functionality of subprocess.CalledProcessError and RuntimeError. It provides additional features like context messages (msg) and current working directory (cwd) tracking.

Parameters:

  • cmd – The command that was executed (either as a string or list of strings)

  • msg – Optional contextual message explaining why the command was executed or failure context

  • returncode – Optional return code of the failed command (default: CommandError.UNKNOWN_RETURNCODE)

  • stdout – Optional standard output from the command

  • stderr – Optional standard error from the command

  • cwd – Optional current working directory where the command was executed

msg

Additional contextual information about the error

cwd

The working directory where the command was executed

cmd

The command that was executed

returncode

The command’s exit code

stdout

Standard output from the command

stderr

Standard error from the command

Examples

>>> raise CommandError('mycmd')
Traceback (most recent call last):
  ...
datasalad.runners.exception.CommandError: Command 'mycmd' errored with unknown exit status

A more complex example:

>>> raise CommandError('invalid', msg='intentional blow', returncode=23)
Traceback (most recent call last):
  ...
datasalad.runners.exception.CommandError: Command 'invalid' returned non-zero exit status 23 [intentional blow]