datalad_next.shell.ShellCommandExecutor

class datalad_next.shell.ShellCommandExecutor(process_inputs: Queue, stdout: OutputFrom, shell_cmd: list[str], default_rg_class: type[VariableLengthResponseGenerator])[source]

Bases: object

Execute a command in a shell and return a generator that yields output

Instances of ShellCommandExecutor allow to execute commands that are provided as byte-strings via its __call__()-method.

To execute the command and collect its output, return code, and stderr-output, ShellCommandExecutor uses instances of subclasses of ShellCommandResponseGenerator, e.g. VariableLengthResponseGeneratorPosix.

__call__(command: bytes | str, *, stdin: Iterable[bytes] | None = None, response_generator: ShellCommandResponseGenerator | None = None, encoding: str = 'utf-8', check: bool = False) → ExecutionResult[source]

Execute a command in the connected shell and return the result

This method executes the given command in the connected shell. It assembles all output on stdout, all output on stderr that was written during the execution of the command, and the return code of the command. (The response generator defines when the command output is considered complete. Usually that is done by checking for a random end-of-output marker.)

Parameters:

  • command (bytes | str) -- The command to execute. If the command is given as a string, it will be encoded to bytes using the encoding given in encoding.

  • stdin (Iterable[byte] | None, optional, default: None) --

    If given, the bytes are sent to stdin of the command.

    Note: If the command reads its stdin until EOF, you have to use self.close() to close stdin of the command. Otherwise, the command will usually not terminate. Once self.close() is called, no more commands can be executed with this ShellCommandExecutor-instance. If you want to execute further commands in the same ShellCommandExecutor-instance, you must ensure that commands consume a fixed amount of input, for example, by using head -c <byte-count> | <command>.

  • response_generator (ShellCommandResponseGenerator | None, optional, default: None) -- If given, the responder generator (usually an instance of a subclass of ShellCommandResponseGenerator), that is used to generate the command line and to parse the output of the command. This can be used to implement, for example, fixed length output processing.

  • encoding (str, optional, default: 'utf-8') -- The encoding that is used to encode the command if it is given as a string. Note: the encoding should match the decoding the is used in the connected shell.

  • check (bool, optional, default: False) -- If True, a CommandError-exception is raised if the return code of the command is not zero.

Returns:

An instance of ExecutionResult that contains the stdout-output, the stderr-output, and the return code of the command.

Return type:

ExecutionResult

Raises:

CommandError -- If the return code of the command is not zero and check is True.

close()[source]

stop input to the shell

This method closes stdin of the shell. This will in turn terminate the shell, no further commands can be executed in the shell.

command_zero(response_generator: VariableLengthResponseGenerator) → None[source]

Execute the zero command

This method is only used by shell() to skip any login messages

start(command: bytes | str, *, stdin: Iterable[bytes] | None = None, response_generator: ShellCommandResponseGenerator | None = None, encoding: str = 'utf-8') → ShellCommandResponseGenerator[source]

Execute a command in the connected shell

Execute a command in the connected shell and return a generator that provides the content written to stdout of the command. After the generator is exhausted, the return code of the command is available in the returncode-attribute of the generator.

Parameters:

  • command (bytes | str) -- The command to execute. If the command is given as a string, it will be encoded to bytes using the encoding given in encoding.

  • stdin (Iterable[byte] | None, optional, default: None) --

    If given, the bytes are sent to stdin of the command.

    Note: If the command reads its stdin until EOF, you have to use self.close() to close stdin of the command. Otherwise, the command will usually not terminate. Once self.close() is called, no more commands can be executed with this ShellCommandExecutor-instance. If you want to execute further commands in the same ShellCommandExecutor-instance, you must ensure that commands consume a fixed amount of input, for example, by using head -c <byte-count> | <command>.

  • response_generator (ShellCommandResponseGenerator | None, optional, default: None) -- If given, the responder generator (usually an instance of a subclass of ShellCommandResponseGenerator), that is used to generate the command line and to parse the output of the command. This can be used to implement, for example, fixed length output processing.

  • encoding (str, optional, default: 'utf-8') -- The encoding that is used to encode the command if it is given as a string. Note: the encoding should match the decoding the is used in the connected shell.

Returns:

A generator that yields the output of stdout of the command. The generator is exhausted when all output is read. After that, the return code of the command execution is available in the returncode-attribute of the generator, and the stderr-output is available in the stderr_deque-attribute of the response generator. If a response generator was passed in via the response_generator-parameter, the same instance will be returned.

Return type:

ShellCommandResponseGenerator