API

Command Class

The Command class represents a program that exists on the system and can be run at some point in time. An instance of Command is never running; an instance of RunningCommand is spawned for that.

An instance of Command can take the form of a manually instantiated object, or as an object instantiated by dynamic lookup:

import sh

ls1 = sh.Command("ls")
ls2 = sh.ls

assert ls1 == ls2

class Command(name, search_paths=None)

Instantiates a Command instance, where name is the name of a program that exists on the user’s $PATH, or is a full path itself. If search_paths is specified, it must be a list of all the paths to look for the program name.

from sh import Command

ifconfig = Command("ifconfig")
ifconfig = Command("/sbin/ifconfig")

Command.bake(*args, **kwargs)

Returns a new Command with *args and **kwargs baked in as positional and keyword arguments, respectively. Any future calls to the returned Command will include *args and **kwargs automatically:

from sh import ls

long_ls = ls.bake("-l")
print(ls("/var"))
print(ls("/tmp"))

See also

Baking

Similar to the above, arguments to the sh.Command must be separate. e.g. the following does not work:

lscmd = sh.Command("/bin/ls -l")
tarcmd = sh.Command("/bin/tar cvf /tmp/test.tar /my/home/directory/")

You will run into CommandNotFound(path) exception even when correct full path is specified. The correct way to do this is to :

1. build Command object using only the binary

2. pass the arguments to the object when invoking

as follows:

lscmd = sh.Command("/bin/ls")
lscmd("-l")
tarcmd = sh.Command("/bin/tar")
tarcmd("cvf", "/tmp/test.tar", "/my/home/directory/")

RunningCommand Class

This represents a Command instance that has been or is being executed. It exists as a wrapper around the low-level OProc. Most of your interaction with sh objects are with instances of this class. It is only returned if _return_cmd=True when you execute a command.

Warning

Objects of this class behave very much like strings. This was an intentional design decision to make the “output” of an executing Command behave more intuitively.

Be aware that functions that accept real strings only, for example json.dumps, will not work on instances of RunningCommand, even though it look like a string.

RunningCommand.wait(timeout=None)

Parameters:

timeout – An optional non-negative number to wait for the command to complete. If it doesn’t complete by the timeout, we raise TimeoutException.

Block and wait for the command to finish execution and obtain an exit code. If the exit code represents a failure, we raise the appropriate exception. See exceptions.

Note

Calling this method multiple times only yields an exception on the first call.

This is called automatically by sh unless your command is being executed asynchronously, in which case, you may want to call this manually to ensure completion.

If an instance of Command is being used as the stdin argument (see piping), wait() is also called on that instance, and any exceptions resulting from that process are propagated up.

RunningCommand.process

The underlying OProc instance.

RunningCommand.stdout

A @property that calls wait() and then returns the contents of what the process wrote to stdout.

RunningCommand.stderr

A @property that calls wait() and then returns the contents of what the process wrote to stderr.

RunningCommand.exit_code

A @property that calls wait() and then returns the process’s exit code.

RunningCommand.pid

The process id of the process.

RunningCommand.sid

The session id of the process. This will typically be a different session than the current python process, unless _new_session=False was specified.

RunningCommand.pgid

The process group id of the process.

RunningCommand.ctty

The controlling terminal device, if there is one.

RunningCommand.signal(sig_num)

Sends sig_num to the process. Typically used with a value from the signal module, like signal.SIGHUP (see signal(7)).

RunningCommand.signal_group(sig_num)

Sends sig_num to every process in the process group. Typically used with a value from the signal module, like signal.SIGHUP (see signal(7)).

RunningCommand.terminate()

Shortcut for RunningCommand.signal(signal.SIGTERM).

RunningCommand.kill()

Shortcut for RunningCommand.signal(signal.SIGKILL).

RunningCommand.kill_group()

Shortcut for RunningCommand.signal_group(signal.SIGKILL).

RunningCommand.is_alive()

Returns whether or not the process is still alive.

Return type:

bool

OProc Class

Warning

Don’t use instances of this class directly. It is being documented here for posterity, not for direct use.

OProc.wait()

Block until the process completes, aggregate the output, and populate OProc.exit_code.

OProc.stdout

A collections.deque, sized to _internal_bufsize items, that contains the process’s STDOUT.

OProc.stderr

A collections.deque, sized to _internal_bufsize items, that contains the process’s STDERR.

OProc.exit_code

Contains the process’s exit code, or None if the process has not yet exited.

OProc.pid

The process id of the process.

OProc.sid

The session id of the process. This will typically be a different session than the current python process, unless _new_session=False was specified.

OProc.pgid

The process group id of the process.

OProc.ctty

The controlling terminal device, if there is one.

OProc.signal(sig_num)

Sends sig_num to the process. Typically used with a value from the signal module, like signal.SIGHUP (see signal(7)).

OProc.signal_group(sig_num)

Sends sig_num to every process in the process group. Typically used with a value from the signal module, like signal.SIGHUP (see signal(7)).

OProc.terminate()

Shortcut for OProc.signal(signal.SIGTERM).

OProc.kill()

Shortcut for OProc.signal(signal.SIGKILL).

OProc.kill_group()

Shortcut for OProc.signal_group(signal.SIGKILL).

Exceptions

ErrorReturnCode

class ErrorReturnCode

This is the base class for, as the name suggests, error return codes. It subclasses Exception.

ErrorReturnCode.full_cmd

The full command that was executed, as a string, so that you can try it on the commandline if you wish.

ErrorReturnCode.stdout

The total aggregated STDOUT for the process.

ErrorReturnCode.stderr

The total aggregated STDERR for the process.

ErrorReturnCode.exit_code

The process’s adjusted exit code.

See also

Exit Code Processing

SignalException

Subclasses ErrorReturnCode. Raised when a command receives a signal that causes it to exit.

TimeoutException

Raised when a command specifies a non-null _timeout and the command times out:

import sh

try:
    sh.sleep(10, _timeout=1)
except sh.TimeoutException:
    print("we timed out, as expected")

Also raised when you specify a timeout to RunningCommand.wait(timeout=None):

import sh

p = sh.sleep(10, _bg=True)
try:
    p.wait(timeout=1)
except sh.TimeoutException:
    print("we timed out waiting")
    p.kill()

CommandNotFound

This exception is raised in one of the following conditions:

• The program cannot be found on your path.

• You do not have permissions to execute the program.

• The program is not marked executable.

The last two bullets may seem strange, but they fall in line with how a shell like Bash behaves when looking up a program to execute.

Note

CommandNotFound subclasses AttributeError. As such, the repr of it is simply the name of the missing attribute.

Helper Functions

which(name, search_paths=None)

Resolves name to program’s absolute path, or None if it cannot be found. If search_paths is list of paths, use that list to look for the program, otherwise use the environment variable $PATH.

pushd(directory)

This function provides a with context that behaves similar to Bash’s pushd by pushing to the provided directory, and popping out of it at the end of the context.

import sh

with sh.pushd("/tmp"):
    sh.touch("a_file")

Note

It should be noted that we use a reentrant lock, so that different threads using this function will have the correct behavior inside of their with contexts.