Package plumbum.commands

class plumbum.commands.base.AppendingStdoutRedirection(cmd, file)

class plumbum.commands.base.BaseCommand

Base of all command objects

__str__()

Return str(self).

Return type:

str

__or__(other)

Creates a pipe with the other command

Return type:

Pipeline

__gt__(file)

Redirects the process’ stdout to the given file

Return type:

StdoutRedirection

__rshift__(file)

Redirects the process’ stdout to the given file (appending)

Return type:

AppendingStdoutRedirection

__ge__(file)

Redirects the process’ stderr to the given file

Return type:

StderrRedirection

__lt__(file)

Redirects the given file into the process’ stdin

Return type:

StdinRedirection

__lshift__(data)

Redirects the given data into the process’ stdin

Return type:

StdinDataRedirection

__getitem__(args)

Creates a bound-command with the given arguments. Shortcut for bound_command.

Return type:

BoundCommand

bound_command(*args)

Overloads:

• self → Self

• self, args (Any) → BoundCommand

Creates a bound-command with the given arguments

__call__(*args, **kwargs)

A shortcut for run(args), returning only the process’ stdout

Return type:

str

with_env(**env)

Returns a BoundEnvCommand with the given environment variables

Return type:

BaseCommand

with_cwd(path)

Returns a BoundEnvCommand with the specified working directory. This overrides a cwd specified in a wrapping machine.cwd() context manager.

Return type:

BaseCommand

setenv(**env)

Returns a BoundEnvCommand with the given environment variables

Return type:

BaseCommand

formulate(level=0, args=())

Formulates the command into a command-line, i.e., a list of shell-quoted strings that can be executed by Popen or shells.

Parameters:

• level (int) – The nesting level of the formulation; it dictates how much shell-quoting (if any) should be performed

• args (Sequence[Any]) – The arguments passed to this command (a tuple)

Return type:

list[str]

Returns:

A list of strings

popen(args=(), **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any]) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

nohup(cwd='.', stdout='nohup.out', stderr=None, append=True)

Runs a command detached.

Return type:

PopenWithAddons[str]

bgrun(args=(), **kwargs)

Runs the given command as a context manager, allowing you to create a pipeline (not in the UNIX sense) of programs, parallelizing their work. In other words, instead of running programs one after the other, you can start all of them at the same time and wait for them to finish. For a more thorough review, see Lightweight Asynchronism.

Example:

from plumbum.cmd import mkfs

with mkfs["-t", "ext3", "/dev/sda1"] as p1:
    with mkfs["-t", "ext3", "/dev/sdb1"] as p2:
        pass

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

For the arguments, see run.

Return type:

Generator[PopenWithAddons[str], None, None]

Returns:

A Popen object, augmented with a .run() method, which returns a tuple of (return code, stdout, stderr)

run(args=(), **kwargs)

Runs the given command (equivalent to popen() followed by run_proc). If the exit code of the process does not match the expected one, ProcessExecutionError is raised.

Parameters:

• args (Sequence[Any]) – Any arguments to be passed to the process (a tuple)

• retcode –

  The expected return code of this process (defaults to 0). In order to disable exit-code validation, pass None. It may also be a tuple (or any iterable) of expected exit codes.

  Note

  this argument must be passed as a keyword argument.

• timeout –

  The maximal amount of time (in seconds) to allow the process to run. None means no timeout is imposed; otherwise, if the process hasn’t terminated after that many seconds, the process will be forcefully terminated an exception will be raised

  Note

  this argument must be passed as a keyword argument.

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

tuple[int, str, str]

Returns:

A tuple of (return code, stdout, stderr)

run_bg(**kwargs)

Run this command in the background. Uses all arguments from the BG construct :py:class: plumbum.commands.modifiers.BG

Return type:

Future

run_fg(**kwargs)

Run this command in the foreground. Uses all arguments from the FG construct :py:class: plumbum.commands.modifiers.FG

Return type:

None

run_tee(**kwargs)

Run this command using the TEE construct. Inherits all arguments from TEE :py:class: plumbum.commands.modifiers.TEE

Return type:

tuple[int, str, str]

run_tf(**kwargs)

Run this command using the TF construct. Inherits all arguments from TF :py:class: plumbum.commands.modifiers.TF

Return type:

bool

run_retcode(**kwargs)

Run this command using the RETCODE construct. Inherits all arguments from RETCODE :py:class: plumbum.commands.modifiers.RETCODE

Return type:

int

run_nohup(**kwargs)

Run this command using the NOHUP construct. Inherits all arguments from NOHUP :py:class: plumbum.commands.modifiers.NOHUP

Return type:

PopenWithAddons[str]

class plumbum.commands.base.BaseRedirection(cmd, file)

__init__(cmd, file)

__repr__()

Return repr(self).

Return type:

str

formulate(level=0, args=())

Formulates the command into a command-line, i.e., a list of shell-quoted strings that can be executed by Popen or shells.

Parameters:

• level (int) – The nesting level of the formulation; it dictates how much shell-quoting (if any) should be performed

• args (Sequence[Any]) – The arguments passed to this command (a tuple)

Return type:

list[str]

Returns:

A list of strings

popen(args=(), **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any]) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

class plumbum.commands.base.BoundCommand(cmd, args)

__init__(cmd, args)

__repr__()

Return repr(self).

Return type:

str

formulate(level=0, args=())

Formulates the command into a command-line, i.e., a list of shell-quoted strings that can be executed by Popen or shells.

Parameters:

• level (int) – The nesting level of the formulation; it dictates how much shell-quoting (if any) should be performed

• args (Sequence[Any]) – The arguments passed to this command (a tuple)

Return type:

list[str]

Returns:

A list of strings

popen(args=(), **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any] | str) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

class plumbum.commands.base.BoundEnvCommand(cmd, env=None, cwd=None)

__init__(cmd, env=None, cwd=None)

__repr__()

Return repr(self).

Return type:

str

formulate(level=0, args=())

Formulates the command into a command-line, i.e., a list of shell-quoted strings that can be executed by Popen or shells.

Parameters:

• level (int) – The nesting level of the formulation; it dictates how much shell-quoting (if any) should be performed

• args (Sequence[Any]) – The arguments passed to this command (a tuple)

Return type:

list[str]

Returns:

A list of strings

popen(args=(), cwd=None, env=None, **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any]) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

class plumbum.commands.base.ConcreteCommand(executable, encoding)

__init__(executable, encoding)

__str__()

Return str(self).

Return type:

str

__repr__()

Return repr(self).

Return type:

str

formulate(level=0, args=())

Formulates the command into a command-line, i.e., a list of shell-quoted strings that can be executed by Popen or shells.

Parameters:

• level (int) – The nesting level of the formulation; it dictates how much shell-quoting (if any) should be performed

• args (Sequence[Any]) – The arguments passed to this command (a tuple)

Return type:

list[str]

Returns:

A list of strings

popen(args=(), **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any]) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

class plumbum.commands.base.Pipeline(srccmd, dstcmd)

__init__(srccmd, dstcmd)

__repr__()

Return repr(self).

Return type:

str

formulate(level=0, args=())

Formulates the command into a command-line, i.e., a list of shell-quoted strings that can be executed by Popen or shells.

Parameters:

• level (int) – The nesting level of the formulation; it dictates how much shell-quoting (if any) should be performed

• args (Sequence[Any]) – The arguments passed to this command (a tuple)

Return type:

list[str]

Returns:

A list of strings

popen(args=(), **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any]) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

exception plumbum.commands.base.RedirectionError

Raised when an attempt is made to redirect an process’ standard handle, which was already redirected to/from a file

__weakref__

list of weak references to the object

class plumbum.commands.base.StderrRedirection(cmd, file)

class plumbum.commands.base.StdinDataRedirection(cmd, data)

__init__(cmd, data)

formulate(level=0, args=())

Formulates the command into a command-line, i.e., a list of shell-quoted strings that can be executed by Popen or shells.

Parameters:

• level (int) – The nesting level of the formulation; it dictates how much shell-quoting (if any) should be performed

• args (Sequence[Any]) – The arguments passed to this command (a tuple)

Return type:

list[str]

Returns:

A list of strings

popen(args=(), **kwargs)

Spawns the given command, returning a Popen-like object.

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

Parameters:

• args (Sequence[Any]) – Any arguments to be passed to the process (a tuple)

• kwargs (Any) – Any keyword-arguments to be passed to the Popen constructor

Return type:

PopenWithAddons[str]

Returns:

A Popen-like object

class plumbum.commands.base.StdinRedirection(cmd, file)

class plumbum.commands.base.StdoutRedirection(cmd, file)

plumbum.commands.base.iter_lines(proc, retcode=0, timeout=None, linesize=-1, line_timeout=None, buffer_size=None, *, mode=None, _iter_lines=<function _iter_lines_posix>)

Overloads:

• proc (PopenWithAddons[Any]), retcode (int), timeout (float | None), linesize (int), line_timeout (float | None), buffer_size (int | None), mode (Literal[Mode.BY_POSITION] | None), _iter_lines (Callable[[PopenWithAddons[Any], Callable[[bytes], str], int, float | None], Generator[tuple[int, str], None, None]]) → Generator[tuple[int, str], None, None]

• proc (PopenWithAddons[Any]), retcode (int), timeout (float | None), linesize (int), line_timeout (float | None), buffer_size (int | None), mode (Literal[Mode.BY_TYPE]), _iter_lines (Callable[[PopenWithAddons[Any], Callable[[bytes], str], int, float | None], Generator[tuple[int, str], None, None]]) → Generator[tuple[None, str] | tuple[str, None], None, None]

Runs the given process (equivalent to run_proc()) and yields a tuples of (out, err) line pairs. If the exit code of the process does not match the expected one, ProcessExecutionError is raised.

Parameters:

• retcode (int) – The expected return code of this process (defaults to 0). In order to disable exit-code validation, pass None. It may also be a tuple (or any iterable) of expected exit codes.

• timeout (float | None) – The maximal amount of time (in seconds) to allow the process to run. None means no timeout is imposed; otherwise, if the process hasn’t terminated after that many seconds, the process will be forcefully terminated an exception will be raised

• linesize (int) – Maximum number of characters to read from stdout/stderr at each iteration. -1 (default) reads until a b’n’ is encountered.

• line_timeout (float | None) – The maximal amount of time (in seconds) to allow between consecutive lines in either stream. Raise an ProcessLineTimedOut if the timeout has been reached. None means no timeout is imposed.

• buffer_size (int | None) – Maximum number of lines to keep in the stdout/stderr buffers, in case of a ProcessExecutionError. Default is None, which defaults to DEFAULT_BUFFER_SIZE (which is infinite by default). 0 will disable buffering completely.

• mode (Mode | None) – Controls what the generator yields. Defaults to DEFAULT_ITER_LINES_MODE (which is BY_POSITION by default) - BY_POSITION (default): yields (out, err) line tuples, where either item may be None - BY_TYPE: yields (fd, line) tuples, where fd is 1 (stdout) or 2 (stderr)

Returns:

An iterator of (out, err) line tuples.

plumbum.commands.base.run_proc(proc, retcode, timeout=None)

Waits for the given process to terminate, with the expected exit code

Parameters:

• proc (PopenWithAddons[Any]) – a running Popen-like object, with all the expected methods.

• retcode (int | None | Container[int]) – the expected return (exit) code of the process. It defaults to 0 (the convention for success). If None, the return code is ignored. It may also be a tuple (or any object that supports __contains__) of expected return codes.

• timeout (float | None) – the number of seconds (a float) to allow the process to run, before forcefully terminating it. If None, not timeout is imposed; otherwise the process is expected to terminate within that timeout value, or it will be killed and ProcessTimedOut will be raised

Return type:

tuple[int | None, str, str]

Returns:

A tuple of (return code, stdout, stderr)

plumbum.commands.base.shquote(text)

Quotes the given text with shell escaping (assumes as syntax similar to sh)

Return type:

str

class plumbum.commands.modifiers.Future(proc, expected_retcode, timeout=None)

Represents a “future result” of a running process. It basically wraps a Popen object and the expected exit code, and provides poll(), wait(), returncode, stdout, and stderr.

__init__(proc, expected_retcode, timeout=None)

__repr__()

Return repr(self).

Return type:

str

poll()

Polls the underlying process for termination; returns False if still running, or True if terminated

Return type:

bool

ready()

Polls the underlying process for termination; returns False if still running, or True if terminated

Return type:

bool

wait()

Waits for the process to terminate; will raise a plumbum.commands.processes.ProcessExecutionError in case of failure

Return type:

None

property stdout

The process’ stdout; accessing this property will wait for the process to finish

property stderr

The process’ stderr; accessing this property will wait for the process to finish

property returncode

The process’ returncode; accessing this property will wait for the process to finish

class plumbum.commands.modifiers.PipeToLoggerMixin

This mixin allows piping plumbum commands’ output into a logger. The logger must implement a log(level, msg) method, as in logging.Logger

Example:

class MyLogger(logging.Logger, PipeToLoggerMixin):
    pass

logger = MyLogger("example.app")

Here we send the output of an install.sh script into our log:

local['./install.sh'] & logger

We can choose the log-level for each stream:

local['./install.sh'] & logger.pipe(out_level=logging.DEBUG, err_level=logging.DEBUG)

Or use a convenience method for it:

local['./install.sh'] & logger.pipe_debug()

A prefix can be added to each line:

local['./install.sh'] & logger.pipe(prefix="install.sh: ")

If the command fails, an exception is raised as usual. This can be modified:

local['install.sh'] & logger.pipe_debug(retcode=None)

An exception is also raised if too much time (DEFAULT_LINE_TIMEOUT) passed between lines in the stream, This can also be modified:

local['install.sh'] & logger.pipe(line_timeout=10)

If we happen to use logbook:

class MyLogger(logbook.Logger, PipeToLoggerMixin):
    from logbook import DEBUG, INFO  # hook up with logbook's levels

pipe(out_level=None, err_level=None, prefix=None, line_timeout=None, **kw)

Pipe a command’s stdout and stderr lines into this logger.

Parameters:

• out_level (int | None) – the log level for lines coming from stdout

• err_level (int | None) – the log level for lines coming from stderr

Return type:

LogPipe

Optionally use prefix for each line.

pipe_info(prefix=None, **kw)

Pipe a command’s stdout and stderr lines into this logger (both at level INFO)

Return type:

LogPipe

pipe_debug(prefix=None, **kw)

Pipe a command’s stdout and stderr lines into this logger (both at level DEBUG)

Return type:

LogPipe

__rand__(cmd)

Pipe a command’s stdout and stderr lines into this logger. Log levels for each stream are determined by DEFAULT_STDOUT and DEFAULT_STDERR.

Return type:

int

plumbum.commands.modifiers.BG = _BG(kargs = {}, retcode = 0, timeout = None)

An execution modifier that runs the given command in the background, returning a Future object. In order to mimic shell syntax, it applies when you right-and it with a command. If you wish to expect a different return code (other than the normal success indicate by 0), use BG(retcode). Example:

future = sleep[5] & BG       # a future expecting an exit code of 0
future = sleep[5] & BG(7)    # a future expecting an exit code of 7

Note

When processes run in the background (either via popen or & BG), their stdout/stderr pipes might fill up, causing them to hang. If you know a process produces output, be sure to consume it every once in a while, using a monitoring thread/reactor in the background. For more info, see #48

plumbum.commands.modifiers.FG = _FG(retcode = 0, timeout = None)

An execution modifier that runs the given command in the foreground, passing it the current process’ stdin, stdout and stderr. Useful for interactive programs that require a TTY. There is no return value.

In order to mimic shell syntax, it applies when you right-and it with a command. If you wish to expect a different return code (other than the normal success indicate by 0), use FG(retcode). Example:

vim & FG       # run vim in the foreground, expecting an exit code of 0
vim & FG(7)    # run vim in the foreground, expecting an exit code of 7

plumbum.commands.modifiers.NOHUP = _NOHUP(append = True, cwd = ., stderr = None, stdout = nohup.out)

An execution modifier that runs the given command in the background, disconnected from the current process, returning a standard popen object. It will keep running even if you close the current process. In order to slightly mimic shell syntax, it applies when you right-and it with a command. If you wish to use a different working directory or different stdout, stderr, you can use named arguments. The default is NOHUP( cwd=local.cwd, stdout='nohup.out', stderr=None). If stderr is None, stderr will be sent to stdout. Use os.devnull for null output. Will respect redirected output. Example:

sleep[5] & NOHUP                       # Outputs to nohup.out
sleep[5] & NOHUP(stdout=os.devnull)    # No output

The equivalent bash command would be

nohup sleep 5 &

plumbum.commands.modifiers.RETCODE = _RETCODE(foreground = False, timeout = None)

An execution modifier that runs the given command, causing it to run and return the retcode. This is useful for working with bash commands that have important retcodes but not very useful output.

If you want to run the process in the foreground, then use RETCODE(FG=True).

Example:

local['touch']['/root/test'] & RETCODE # Returns 1, since this cannot be touched
local['touch']['/root/test'] & RETCODE(FG=True) * Returns 1, will show error message

plumbum.commands.modifiers.TEE = _TEE(buffered = True, retcode = 0, timeout = None)

Run a command, dumping its stdout/stderr to the current process’s stdout and stderr, but ALSO return them. Useful for interactive programs that expect a TTY but also have valuable output.

Use as:

ls[“-l”] & TEE

Returns a tuple of (return code, stdout, stderr), just like run().

plumbum.commands.modifiers.TF = _TF(FG = False, retcode = 0, timeout = None)

An execution modifier that runs the given command, but returns True/False depending on the retcode. This returns True if the expected exit code is returned, and false if it is not. This is useful for checking true/false bash commands.

If you wish to expect a different return code (other than the normal success indicate by 0), use TF(retcode). If you want to run the process in the foreground, then use TF(FG=True).

Example:

local['touch']['/root/test'] & TF * Returns False, since this cannot be touched
local['touch']['/root/test'] & TF(1) # Returns True
local['touch']['/root/test'] & TF(FG=True) * Returns False, will show error message

exception plumbum.commands.processes.CommandNotFound(program, path)

Raised by local.which and BaseRemoteMachine.which when a command was not found in the system’s PATH

__init__(program, path)

__weakref__

list of weak references to the object

class plumbum.commands.processes.Mode(*values)

exception plumbum.commands.processes.ProcessExecutionError(argv, retcode, stdout, stderr, message=None, *, host=None)

Represents the failure of a process. When the exit code of a terminated process does not match the expected result, this exception is raised by run_proc. It contains the process’ return code, stdout, and stderr, as well as the command line used to create the process (argv)

__init__(argv, retcode, stdout, stderr, message=None, *, host=None)

__str__()

Return str(self).

Return type:

str

__weakref__

list of weak references to the object

exception plumbum.commands.processes.ProcessLineTimedOut(msg, argv, machine)

Raises by iter_lines when a line_timeout has been specified and it has elapsed before the process yielded another line

__init__(msg, argv, machine)

__weakref__

list of weak references to the object

exception plumbum.commands.processes.ProcessTimedOut(msg, argv)

Raises by run_proc when a timeout has been specified and it has elapsed before the process terminated

__init__(msg, argv)

__weakref__

list of weak references to the object

plumbum.commands.processes.iter_lines(proc, retcode=0, timeout=None, linesize=-1, line_timeout=None, buffer_size=None, *, mode=None, _iter_lines=<function _iter_lines_posix>)

Overloads:

• proc (PopenWithAddons[Any]), retcode (int), timeout (float | None), linesize (int), line_timeout (float | None), buffer_size (int | None), mode (Literal[Mode.BY_POSITION] | None), _iter_lines (Callable[[PopenWithAddons[Any], Callable[[bytes], str], int, float | None], Generator[tuple[int, str], None, None]]) → Generator[tuple[int, str], None, None]

• proc (PopenWithAddons[Any]), retcode (int), timeout (float | None), linesize (int), line_timeout (float | None), buffer_size (int | None), mode (Literal[Mode.BY_TYPE]), _iter_lines (Callable[[PopenWithAddons[Any], Callable[[bytes], str], int, float | None], Generator[tuple[int, str], None, None]]) → Generator[tuple[None, str] | tuple[str, None], None, None]

Runs the given process (equivalent to run_proc()) and yields a tuples of (out, err) line pairs. If the exit code of the process does not match the expected one, ProcessExecutionError is raised.

Parameters:

• retcode (int) – The expected return code of this process (defaults to 0). In order to disable exit-code validation, pass None. It may also be a tuple (or any iterable) of expected exit codes.

• timeout (float | None) – The maximal amount of time (in seconds) to allow the process to run. None means no timeout is imposed; otherwise, if the process hasn’t terminated after that many seconds, the process will be forcefully terminated an exception will be raised

• linesize (int) – Maximum number of characters to read from stdout/stderr at each iteration. -1 (default) reads until a b’n’ is encountered.

• line_timeout (float | None) – The maximal amount of time (in seconds) to allow between consecutive lines in either stream. Raise an ProcessLineTimedOut if the timeout has been reached. None means no timeout is imposed.

• buffer_size (int | None) – Maximum number of lines to keep in the stdout/stderr buffers, in case of a ProcessExecutionError. Default is None, which defaults to DEFAULT_BUFFER_SIZE (which is infinite by default). 0 will disable buffering completely.

• mode (Mode | None) – Controls what the generator yields. Defaults to DEFAULT_ITER_LINES_MODE (which is BY_POSITION by default) - BY_POSITION (default): yields (out, err) line tuples, where either item may be None - BY_TYPE: yields (fd, line) tuples, where fd is 1 (stdout) or 2 (stderr)

Returns:

An iterator of (out, err) line tuples.

plumbum.commands.processes.run_proc(proc, retcode, timeout=None)

Waits for the given process to terminate, with the expected exit code

Parameters:

• proc (PopenWithAddons[Any]) – a running Popen-like object, with all the expected methods.

• retcode (int | None | Container[int]) – the expected return (exit) code of the process. It defaults to 0 (the convention for success). If None, the return code is ignored. It may also be a tuple (or any object that supports __contains__) of expected return codes.

• timeout (float | None) – the number of seconds (a float) to allow the process to run, before forcefully terminating it. If None, not timeout is imposed; otherwise the process is expected to terminate within that timeout value, or it will be killed and ProcessTimedOut will be raised

Return type:

tuple[int | None, str, str]

Returns:

A tuple of (return code, stdout, stderr)

Asyncio support for Plumbum commands.

This module provides async versions of Plumbum commands that can be used with Python’s asyncio framework. Commands can be awaited directly or used with async context managers.

For async machines (AsyncLocalMachine, AsyncSshMachine), see plumbum.machines.local and plumbum.machines.ssh_machine respectively

Design Philosophy

This implementation uses delegation over inheritance to wrap existing sync commands rather than reimplementing their functionality. This approach:

• Maximizes code reuse (~100 lines of logic delegated to sync commands)

• Ensures consistency between sync and async APIs

• Reduces maintenance burden (changes to sync code automatically apply)

• Enables automatic support for features like with_env() and with_cwd()

Why Delegation Instead of Inheritance?

Sync and async methods are fundamentally incompatible in Python:

• Sync methods return values directly: def run() -> tuple[int, str, str]

• Async methods return coroutines: async def run() -> AsyncResult

You cannot override a sync method with an async one in the same class hierarchy. Therefore, we use separate classes that wrap and delegate to sync commands, reusing all their formulation, binding, and pipeline logic.

Example Usage

from plumbum import async_local

async def main():
    # Simple command execution
    result = await async_local["ls"]("-la")
    print(result)

    # With explicit run method
    ls = async_local["ls"]
    result = await ls.run(["-la"])
    print(result.stdout)

    # Pipeline support
    result = await (async_local["ls"] | async_local["grep"]["py"])()
    print(result)

Added in version 2.0.

class plumbum.commands.async_.AsyncCommand(base_cmd)

Async wrapper for BaseCommand.

This class wraps any BaseCommand and provides async execution capabilities. It reuses all the formulation, binding, and pipeline logic from the base command.

Example:

# The sync command is looked up and wrapped
async_cmd = async_local["ls"]

# Binding works via delegation to sync command
bound_cmd = async_cmd["-la"]

# Execution is async
result = await bound_cmd.run()

class plumbum.commands.async_.AsyncLocalCommand(base_cmd)

Async version of LocalCommand.

This class wraps a LocalCommand and provides async execution methods. It reuses all the LocalCommand logic for formulation, binding, etc.

property executable

The path to the executable.

class plumbum.commands.async_.AsyncPipelineProcess(dstproc, srcproc)

Proxy around the downstream process of an async pipeline.

Output attributes (stdout, stderr, pid, …) are delegated to the downstream asyncio.subprocess.Process, while stdin is taken from the upstream process so writes feed the head of the pipeline (mirroring plumbum.commands.base.Pipeline.popen(), which sets dstproc.stdin = srcproc.stdin). wait() and communicate() reap both stages and report a combined return code – the downstream code, or the upstream code if the downstream stage succeeded. kill(), terminate() and send_signal() are propagated to every stage (recursing through a nested upstream pipeline) rather than only the last one.

A separate proxy is needed (rather than patching wait on the downstream process) because asyncio.subprocess.Process.returncode is a read-only property and cannot be reassigned to the combined value.

Instances are returned by AsyncCommandMixin.popen() for pipelines; you don’t normally construct them directly.

Added in version 1.11.

__init__(dstproc, srcproc)

__weakref__

list of weak references to the object

class plumbum.commands.async_.AsyncRemoteCommand(base_cmd)

Async wrapper for RemoteCommand.

This class wraps a RemoteCommand and provides async execution capabilities. It reuses all the RemoteCommand logic for formulation, binding, etc.

Example:

async with AsyncSshMachine("host") as rem:
    ls = rem["ls"]
    result = await ls("-la")

Added in version 2.0.

property remote

The remote machine this command belongs to.

class plumbum.commands.async_.AsyncResult(returncode, stdout, stderr)

Result of an async command execution.

Attributes:

returncode: The exit code of the process stdout: Standard output as a string stderr: Standard error as a string

__init__(returncode, stdout, stderr)

__str__()

Return str(self).

Return type:

str

__repr__()

Return repr(self).

Return type:

str