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
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 :
build
Command
object using only the binarypass 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.stdout
A
@property
that callswait()
and then returns the contents of what the process wrote to stdout.
- RunningCommand.stderr
A
@property
that callswait()
and then returns the contents of what the process wrote to stderr.
- 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, likesignal.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, likesignal.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)
.
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, likesignal.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, likesignal.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
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.