Shell API¶

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¶

Thrown when a command fails.

error_code = 1¶

exception shell.MissingCommandException¶: Thrown when no command was setup.

class shell.Shell(has_input=False, record_output=True, record_errors=True, strip_empty=True)¶

Handles executing commands & recording output.

Optionally accepts a has_input parameter, which should be a boolean. If set to True, the command will wait to execute until you call the Shell.write method & send input. (Default: False)

Optionally accepts a record_output parameter, which should be a boolean. If set to True, the stdout from the command will be recorded. (Default: True)

Optionally accepts a record_errors parameter, which should be a boolean. If set to True, the stderr from the command will be recorded. (Default: True)

Optionally accepts a strip_empty parameter, which should be a boolean. If set to True, only non-empty lines from Shell.output or Shell.errors will be returned. (Default: True)

errors(raw=False)¶

Returns the errors from running a command.

Optionally accepts a raw parameter, which should be a boolean. If raw is set to False, you get an array of lines of errors. If raw is set to True, 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. If raw is set to False, you get an array of lines of output. If raw is set to True, 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)¶

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 to True, the command will wait to execute until you call the Shell.write method & send input. (Default: False)

Optionally accepts a record_output parameter, which should be a boolean. If set to True, the stdout from the command will be recorded. (Default: True)

Optionally accepts a record_errors parameter, which should be a boolean. If set to True, the stderr from the command will be recorded. (Default: True)

Optionally accepts a strip_empty parameter, which should be a boolean. If set to True, only non-empty lines from Shell.output or Shell.errors will be returned. (Default: True)

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']