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
-
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 #48Parameters: - 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
-
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 #48For 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 raisedNote
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)
-
iter_lines
(args=(), **kwargs)[source]¶ Runs the given command (equivalent to run()) 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: - 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 raisedNote
this argument must be passed as a keyword argument.
- linesize –
Maximum number of characters to read from stdout/stderr at each iteration.
-1
(default) reads until a b’n’ is encountered.Note
this argument must be passed as a keyword argument.
- kwargs – Any keyword-arguments to be passed to the
Popen
constructor
Returns: An iterator of (out, err) line tuples.
-
-
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
None
if still running, or the process’ returncode if terminated
-
ready
()¶ Polls the underlying process for termination; returns
None
if still running, or the process’ returncode 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)
-
-
plumbum.commands.modifiers.
BG
= BG(0)[source]¶ 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), useBG(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
-
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 atimeout
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
andRemoteMachine.which
when a command was not found in the system’sPATH
-
__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
- 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. IfNone
, not timeout is imposed; otherwise the process is expected to terminate within that timeout value, or it will be killed andProcessTimedOut
will be raised
Returns: A tuple of (return code, stdout, stderr)
-
plumbum.commands.processes.
iter_lines
(proc, retcode=0, timeout=None, linesize=-1)[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.
- retcode – The expected return code of this process (defaults to 0).
In order to disable exit-code validation, pass