Skip to main content

Python subprocess wrapper

Project description

``sh`` is a unique subprocess wrapper that maps your system programs to
Python functions dynamically. ``sh`` helps you write shell scripts in
Python by giving you the good features of Bash (easy command calling, easy
piping) with all the power and flexibility of Python.

```python
from sh import ifconfig
print ifconfig("eth0")
```

``sh`` is not a collection of system commands implemented in Python.

# Getting

You can't use 'macro parameter character #' in math modePATH:

```python
import sh
ffmpeg = sh.Command("/usr/bin/ffmpeg")
ffmpeg(movie_file)
```

The last usage pattern is for trying ``sh`` through an interactive REPL. By
default, this acts like a star import (so all of your system programs will be
immediately available as functions):

You can't use 'macro parameter character #' in math mode1, $2, etc by using
ARG1, ARG2, etc:

```python
print ARG1, ARG2

# if an argument isn't defined, it's set to None
if ARG10 is None: do_something()
```

You can access the entire argparse/optparse-friendly list of commandline
arguments through "ARGV". This is recommended for flexibility:

```python
import argparse
parser = argparse.ArgumentParser(prog="PROG")
parser.add_argument("-x", default=3, type=int)
ns = parser.parse_args(ARGV)
print ns.x
```


## Weirdly-named Commands

``sh`` automatically handles underscore-dash conversions. For example, if you want
to call apt-get:

```python
apt_get("install", "mplayer", y=True)
```

``sh`` looks for "apt_get", but if it doesn't find it, replaces all underscores
with dashes and searches again. If the command still isn't found, a
CommandNotFound exception is raised.

Commands with other, less-commonly symbols in their names must be accessed
directly through the "Command" class wrapper. The Command class takes the full
path to the program as a string:

```python
p27 = Command(which("python2.7"))
print p27("-h")
```

The Command wrapper is also useful for commands that are not in your standard PATH:

```python
script = Command("/tmp/temporary-script.sh")
print script()
```

## Non-standard Exit Codes

Normally, if a command returns an exit code that is not 0, ``sh`` raises an exception
based on that exit code. However, if you have determined that an error code
is normal and want to retrieve the output of the command without ``sh`` raising an
exception, you can use the "_ok_code" special argument to suppress the exception:

```python
output = sh.ls("dir_that_exists", "dir_that_doesnt", _ok_code=2)
```

In the above example, even though you're trying to list a directory that doesn't
exist, you can still get the output from the directory that does exist by telling
the command that 2 is an "ok" exit code, so don't raise an exception.

_ok_code can also take a list or tuple of numbers for multiple ok exit codes.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page