datalad_next.runners

Execution of subprocesses

This module provides all relevant components for subprocess execution. The main work horse is iter_subproc(), a context manager that enables interaction with a subprocess in the form of an iterable for input/output processing. Execution errors are communicated with the CommandError exception. In addition, a few convenience functions are provided to execute Git commands (including git-annex).

iter_subproc(args, *[, input, chunk_size, ...])

Context manager to communicate with a subprocess using iterables

call_git(args, *[, cwd, force_c_locale])

Call Git with no output capture, raises on non-zero exit.

call_git_lines(args, *[, cwd, input, ...])

Call Git for any (small) number of lines of output

call_git_oneline(args, *[, cwd, input, ...])

Call Git for a single line of output

call_git_success(args, *[, cwd, capture_output])

Call Git and report success or failure of the command

iter_git_subproc(args, **kwargs)

iter_subproc() wrapper for calling Git commands

CommandError([cmd, msg, code, stdout, ...])

Thrown if a command call fails.

Low-level tooling from datalad-core

Deprecated since version 1.4: The functionality described here has been deprecated, and the associated imports from datalad-core are scheduled for removal with version 2.0. Use the implementations listed above instead.

Few process execution/management utilities are provided, for generic command execution, and for execution command in the context of a Git repository.

GitRunner

alias of GitWitlessRunner

Runner

alias of WitlessRunner

Additional information on the design of the subprocess execution tooling is available from https://docs.datalad.org/design/threaded_runner.html

A standard exception type is used to communicate any process termination with a non-zero exit code

CommandError([cmd, msg, code, stdout, ...])

Thrown if a command call fails.

Command output can be processed via "protocol" implementations that are inspired by asyncio.SubprocessProtocol.

KillOutput([done_future, encoding])

WitlessProtocol that swallows stdout/stderr of a subprocess

NoCapture([done_future, encoding])

WitlessProtocol that captures no subprocess output

StdOutCapture([done_future, encoding])

WitlessProtocol that only captures and returns stdout of a subprocess

StdErrCapture([done_future, encoding])

WitlessProtocol that only captures and returns stderr of a subprocess

StdOutErrCapture([done_future, encoding])

WitlessProtocol that captures and returns stdout/stderr of a subprocess