Package plumbum.commands

exception plumbum.commands.base.RedirectionError[source]

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 (if defined)

plumbum.commands.base.shquote(text)[source]

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

class plumbum.commands.base.BaseCommand[source]

Base of all command objects

__or__(other)[source]

Creates a pipe with the other command

__gt__(file)[source]

Redirects the process’ stdout to the given file

__rshift__(file)[source]

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

__ge__(file)[source]

Redirects the process’ stderr to the given file

__lt__(file)[source]

Redirects the given file into the process’ stdin

__lshift__(data)[source]

Redirects the given data into the process’ stdin

__getitem__(args)[source]

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

bound_command(*args)[source]

Creates a bound-command with the given arguments

__call__(*args, **kwargs)[source]

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

with_env(**envvars)[source]

Returns a BoundEnvCommand with the given environment variables

setenv(**envvars)

Returns a BoundEnvCommand with the given environment variables

formulate(level=0, args=())[source]

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 – The nesting level of the formulation; it dictates how much shell-quoting (if any) should be performed
  • args – The arguments passed to this command (a tuple)
Returns:

A list of strings

popen(args=(), **kwargs)[source]

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 – Any arguments to be passed to the process (a tuple)
  • kwargs – Any keyword-arguments to be passed to the Popen constructor
Returns:

A Popen-like object

nohup(command, cwd='.', stdout='nohup.out', stderr=None, append=True)[source]

Runs a command detached.

bgrun(*args, **kwds)[source]

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.

Returns:A Popen object, augmented with a .run() method, which returns a tuple of (return code, stdout, stderr)
run(args=(), **kwargs)[source]

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 – 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 keyword-arguments to be passed to the Popen constructor
Returns:

A tuple of (return code, stdout, stderr)

__weakref__

list of weak references to the object (if defined)

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

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.

poll()[source]

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

ready()

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

wait()[source]

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

stdout

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

stderr

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

returncode

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

__weakref__

list of weak references to the object (if defined)

exception plumbum.commands.processes.ProcessExecutionError(argv, retcode, stdout, stderr)[source]

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)

__weakref__

list of weak references to the object (if defined)

exception plumbum.commands.processes.ProcessTimedOut(msg, argv)[source]

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

__weakref__

list of weak references to the object (if defined)

exception plumbum.commands.processes.CommandNotFound(program, path)[source]

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

__weakref__

list of weak references to the object (if defined)

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

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

Parameters:
  • proc – a running Popen-like object, with all the expected methods.
  • retcode – 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 – 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
Returns:

A tuple of (return code, stdout, stderr)

plumbum.commands.processes.iter_lines(proc, retcode=0, timeout=None, linesize=-1, _iter_lines=<function _iter_lines>)[source]

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 – 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 – 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 – Maximum number of characters to read from stdout/stderr at each iteration. -1 (default) reads until a b’n’ is encountered.
Returns:

An iterator of (out, err) line tuples.