cli

This module provides an interface for running command-line applications. Two primary classes are provided:

Command

For constructing and executing command-line commands

Pipe

For piping commands together

Commands are constructed by specifying a program to run, and each separate argument to pass to that program. Arguments are used in a platform-independent way, so there is no need to escape shell-specific characters or do any quoting of arguments.

Commands may be executed in the foreground or background; they can print their output on standard output, or capture it in a string variable.

For example:

>>> echo = Command('echo', "Hello world")
>>> echo.run()                                
Hello world

Commands may be connected together with pipes:

>>> sed = Command('sed', 's/world/nurse/')
>>> pipe = Pipe(echo, sed)
>>> pipe.run()                                
Hello nurse

The above can be easily accomplished using Python standard library functions like os.Popen or commands.getoutput. This module was designed to simplify the task of executing long-running commands or command-line pipes in the background, and getting their output later. This behavior is controlled by the arguments to the run method.

Normally, run prints all output on standard output. If instead you need to capture the output, pass capture=True, then retrieve it later with get_output:

>>> echo.run(capture=True)                    
>>> echo.get_output()
'Hello world\n'

If the command you’re running will take a long time to run, and you don’t want your program to be blocked while it’s running, pass background=True. If the command may produce a lot of output during execution, you’ll probably want to capture it instead of printing it:

>>> find = Command('find', '/')               
>>> find.run(capture=True, background=True)

In this way, your application can keep doing other things while the long-running command is executing; you can check whether it’s done like so:

>>> find.done()
False
>>> find.done()
False
>>> find.done()
True

Then, as before, use get_output to get the output, if you need it. If you need to get the standard error output, use get_errors.

class Command(program, *args)

A command-line statement, consisting of a program and its arguments, with support for various modes of execution.

Create a Command to run a program with the given arguments.

program

A string containing the name of a program to execute

args

Individual arguments to supply the command with

For example:

>>> cmd = Command('echo', 'Hello world')

add(*args)

Append one or more arguments to the command. Each argument passed to this function is converted to string form, and treated as a single argument in the command. No special quoting or escaping of argument contents is necessary.

done()

Return True if the command is finished running; False otherwise. Only useful if the command is run in the background.

get_errors()

Wait for the command to finish running, and return a string containing the command’s standard error output. Returns an empty string if the command has not been run yet.

get_output()

Wait for the command to finish running, and return a string containing the command’s output. If this command is piped into another, return that command’s output instead. Returns an empty string if the command has not been run yet.

kill()

Abort!

run(capture=False, background=False, silent=False)

Run the command and capture or display output.

capture

False to show command output/errors on stdout, True to capture output/errors for retrieval by get_output and get_errors

background

False to wait for command to finish running, True to run process in the background

silent

False to print each command as it runs, True to run silently

By default, this function displays all command output, and waits for the program to finish running, which is usually what you’d want. Capture output if you don’t want it printed immediately (and call get_output later to retrieve it).

This function does not allow special stream redirection. For that, use run_redir.

run_redir(stdin=None, stdout=None, stderr=None)

Execute the command using the given stream redirections.

stdin

Filename or file object to read input from

stdout

Filename or file object to write output to

stderr

Filename or file object to write errors to

Use None for regular system stdin/stdout/stderr (default behavior). That is, if stdout=None, the command’s standard output is printed.

This function is used internally by run; if you need to do stream redirection (ex. spumux < menu.mpg > menu_subs.mpg), use this function instead of run, and call wait afterwards if needed.

to_script()

Return a bash script for running the given command.

wait()

Wait for the command to finish running, and return the result (self.proc.returncode).

If a KeyboardInterrupt occurs (user pressed Ctrl-C), the subprocess is killed (and KeyboardInterrupt re-raised).

class Pipe(*commands)

Several Command objects, each having its output piped into the next.

Create a new Pipe containing all the given Commands.

add(*commands)

Append the given commands to the end of the pipeline.

get_output()

Wait for the pipeline to finish executing, and return a string containing the output from the last command in the pipeline.

run(capture=False, background=False)

Run all Commands in the pipeline, doing appropriate stream redirection for piping.

capture

False to show pipeline output on stdout, True to capture output for retrieval by get_output