Shell API¶
shell¶
shell¶
A better way to run shell commands in Python.
If you just need to quickly run a command, you can use the shell
shortcut
function:
>>> from shell import shell
>>> ls = shell('ls')
>>> for file in ls.output():
... print file
'another.txt'
If you need to extend the behavior, you can also use the Shell
object:
>>> from shell import Shell
>>> sh = Shell(has_input=True)
>>> cat = sh.run('cat -u')
>>> cat.write('Hello, world!')
>>> cat.output()
['Hello, world!']
-
exception
shell.
CommandError
(message, code, stderr)¶ Thrown when a command fails.
-
exception
shell.
MissingCommandException
¶ Thrown when no command was setup.
-
class
shell.
Shell
(has_input=False, record_output=True, record_errors=True, strip_empty=True, die=False, verbose=False)¶ Handles executing commands & recording output.
Optionally accepts a
has_input
parameter, which should be a boolean. If set toTrue
, the command will wait to execute until you call theShell.write
method & send input. (Default:False
)Optionally accepts a
record_output
parameter, which should be a boolean. If set toTrue
, the stdout from the command will be recorded. (Default:True
)Optionally accepts a
record_errors
parameter, which should be a boolean. If set toTrue
, the stderr from the command will be recorded. (Default:True
)Optionally accepts a
strip_empty
parameter, which should be a boolean. If set toTrue
, only non-empty lines fromShell.output
orShell.errors
will be returned. (Default:True
)Optionally accepts a
die
parameter, which should be a boolean. If set toTrue
, raises a CommandError if the command exits with a non-zero return code. (Default:False
)Optionally accepts a
verbose
parameter, which should be a boolean. If set toTrue
, prints stdout to stdout and stderr to stderr as execution happens. (Default:False
)-
errors
(raw=False)¶ Returns the errors from running a command.
Optionally accepts a
raw
parameter, which should be a boolean. Ifraw
is set toFalse
, you get an array of lines of errors. Ifraw
is set toTrue
, the raw string of errors is returned. (Default:False
)Example:
>>> from shell import Shell >>> sh = Shell() >>> sh.run('ls /there-s-no-way-anyone/has/this/directory/please') >>> sh.errors() [ 'ls /there-s-no-way-anyone/has/this/directory/please: No such file or directory' ]
-
kill
()¶ Kills a given process.
Example:
>>> from shell import Shell >>> sh = Shell() >>> sh.run('some_long_running_thing') >>> sh.kill()
-
output
(raw=False)¶ Returns the output from running a command.
Optionally accepts a
raw
parameter, which should be a boolean. Ifraw
is set toFalse
, you get an array of lines of output. Ifraw
is set toTrue
, the raw string of output is returned. (Default:False
)Example:
>>> from shell import Shell >>> sh = Shell() >>> sh.run('ls ~') >>> sh.output() [ 'hello.txt', 'world.txt', ]
-
run
(command)¶ Runs a given command.
Requires a
command
parameter should be either a string command (easier) or an array of arguments to send as the command (if you know what you’re doing).Returns the
Shell
instance.Example:
>>> from shell import Shell >>> sh = Shell() >>> sh.run('ls -alh')
-
write
(the_input)¶ If you’re working with an interactive process, sends that input to the process.
This needs to be used in conjunction with the
has_input=True
parameter.Requires a
the_input
parameter, which should be a string of the input to send to the command.Returns the
Shell
instance.Example:
>>> from shell import Shell >>> sh = Shell(has_input=True) >>> sh.run('cat -u') >>> sh.write('Hello world!')
-
-
exception
shell.
ShellException
¶ The base exception for all shell-related errors.
-
shell.
shell
(command, has_input=False, record_output=True, record_errors=True, strip_empty=True, die=False, verbose=False)¶ A convenient shortcut for running commands.
Requires a
command
parameter should be either a string command (easier) or an array of arguments to send as the command (if you know what you’re doing).Optionally accepts a
has_input
parameter, which should be a boolean. If set toTrue
, the command will wait to execute until you call theShell.write
method & send input. (Default:False
)Optionally accepts a
record_output
parameter, which should be a boolean. If set toTrue
, the stdout from the command will be recorded. (Default:True
)Optionally accepts a
record_errors
parameter, which should be a boolean. If set toTrue
, the stderr from the command will be recorded. (Default:True
)Optionally accepts a
strip_empty
parameter, which should be a boolean. If set toTrue
, only non-empty lines fromShell.output
orShell.errors
will be returned. (Default:True
)Optionally accepts a
die
parameter, which should be a boolean. If set toTrue
, raises a CommandError if the command exits with a non-zero return code. (Default:False
)Optionally accepts a
verbose
parameter, which should be a boolean. If set toTrue
, prints stdout to stdout and stderr to stderr as execution happens. (Default:False
)Returns the
Shell
instance, which has been run with the given command.Example:
>>> from shell import shell >>> sh = shell('ls -alh *py') >>> sh.output() ['hello.py', 'world.py']