Interact with shell locally or over different connection types (telnet, ssh, serial, adb)
Project description
# citizenshell [![Build Status](https://travis-ci.org/meuter/citizenshell.svg?branch=master)](https://travis-ci.org/meuter/citizenshell)
__citizenshell__ is (or rather will be) a python library allowing to execute shell commands either locally or remotely over several protocols (telnet, ssh, serial or adb) using a simple and consistent API. This library is compatible with both python 2 (2.7) and 3 (>=3.4) as well as with [PyPy](https://pypy.org/). For now, it focuses on POSIX platforms like Linux and MacOS, but may be extended to work to Windows based platform in the future. It is distributed under
[MIT](https://opensource.org/licenses/MIT) license.
## Installing
__citizenshell__ can simply installed using [`pip`](https://pypi.python.org/pypi/pip)
```bash
pip install citizenshell
```
## Examples
### LocalShell
you can use the built-in `sh` command for simple commands:
```python
from citizenshell import sh
assert sh("echo Hello World") == "Hello World"
```
you can instanciate a `LocalShell` for more complex cases:
```python
from citizenshell import LocalShell
shell = LocalShell(GREET="Hello")
assert shell("echo $GREET $WHO", WHO="Citizen") == "Hello Citizen"
```
you can also iterate over stdout:
```python
from citizenshell import LocalShell
shell = LocalShell()
result = [int(x) for x in shell("""
for i in 1 2 3 4; do
echo $i;
done
""")]
assert result == [1, 2, 3, 4]
```
or you can extract stdout, stderr and exit code seperately:
```python
from citizenshell import LocalShell
shell = LocalShell()
result = shell(">&2 echo error && echo output && exit 13")
assert result.out == ["output"]
assert result.err == ["error"]
assert result.xc == 13
```
### TelnetShell
you can instanciate the `TelnetShell` for shell over telnet:
```python
from citizenshell import TelnetShell
shell = TelnetShell(hostname="acme.org", username="john", password="secretpassword")
assert shell("echo Hello World") == "Hello World"
```
you can then do eveything you can do with a `LocalShell`.
### SecureShell
you can instanciate the `SecureShell` for shell over SSH:
```python
from citizenshell import SecureShell
shell = SecureShell(hostname="acme.org", username="john", password="secretpassword")
assert shell("echo Hello World") == "Hello World"
```
you can then do eveything you can do with a `LocalShell`. Beware that some SSH servers
refuse to set environment variable (see documentation of AcceptEnv of
[sshd_config](https://linux.die.net/man/5/sshd_config) and documentation of `update_environment` of [paramiko's `Channel` class](http://docs.paramiko.org/en/2.4/api/channel.html)) and that will fail silently.
### AdbShell
you can instanciate the `AdbShell` for shell over ADB:
```python
from citizenshell import AdbShell
shell = AdbShell(hostname="acme.org", username="john", password="secretpassword")
assert shell("echo Hello World") == "Hello World"
```
you can then do eveything you can do with a `LocalShell`.
### SerialShell
you can instanciate the `SerialShell` for shell over serial line:
```python
from serial import EIGHTBITS, PARITY_NONE
from citizenshell import SerialShell
shell = SerialShell(port="/dev/ttyUSB3", username="john", password="secretpassword", baudrate=115200, parity=PARITY_NONE, bytesize=EIGHTBITS)
assert shell("echo Hello World") == "Hello World"
```
you can then do eveything you can do with a `LocalShell`.
### Shell
you can also obtain shell objects by URI using the `Shell` function:
```python
from citizenshell import Shell
localshell = Shell()
telnetshell = Shell("telnet://john:secretpassword@acme.org:1234")
secureshell = Shell("ssh://john:secretpassword@acme.org:1234")
adbshell = Shell("adb://myandroiddevice:5555")
serialshell = Shell("serial://jogn:secretpassword@/dev/ttyUSB3?baudrate=115200")
```
you can mix and match betweens providing arguments in the URI or via kwargs:
```python
from citizenshell import Shell
localshell = Shell()
telnetshell = Shell("telnet://john@acme.org", password="secretpassword", port=1234)
serialshell = Shell("serial://jogn:secretpassword@/dev/ttyUSB3", baudrate=115200)
```
you can then use the shell objects as you would any other.
__citizenshell__ is (or rather will be) a python library allowing to execute shell commands either locally or remotely over several protocols (telnet, ssh, serial or adb) using a simple and consistent API. This library is compatible with both python 2 (2.7) and 3 (>=3.4) as well as with [PyPy](https://pypy.org/). For now, it focuses on POSIX platforms like Linux and MacOS, but may be extended to work to Windows based platform in the future. It is distributed under
[MIT](https://opensource.org/licenses/MIT) license.
## Installing
__citizenshell__ can simply installed using [`pip`](https://pypi.python.org/pypi/pip)
```bash
pip install citizenshell
```
## Examples
### LocalShell
you can use the built-in `sh` command for simple commands:
```python
from citizenshell import sh
assert sh("echo Hello World") == "Hello World"
```
you can instanciate a `LocalShell` for more complex cases:
```python
from citizenshell import LocalShell
shell = LocalShell(GREET="Hello")
assert shell("echo $GREET $WHO", WHO="Citizen") == "Hello Citizen"
```
you can also iterate over stdout:
```python
from citizenshell import LocalShell
shell = LocalShell()
result = [int(x) for x in shell("""
for i in 1 2 3 4; do
echo $i;
done
""")]
assert result == [1, 2, 3, 4]
```
or you can extract stdout, stderr and exit code seperately:
```python
from citizenshell import LocalShell
shell = LocalShell()
result = shell(">&2 echo error && echo output && exit 13")
assert result.out == ["output"]
assert result.err == ["error"]
assert result.xc == 13
```
### TelnetShell
you can instanciate the `TelnetShell` for shell over telnet:
```python
from citizenshell import TelnetShell
shell = TelnetShell(hostname="acme.org", username="john", password="secretpassword")
assert shell("echo Hello World") == "Hello World"
```
you can then do eveything you can do with a `LocalShell`.
### SecureShell
you can instanciate the `SecureShell` for shell over SSH:
```python
from citizenshell import SecureShell
shell = SecureShell(hostname="acme.org", username="john", password="secretpassword")
assert shell("echo Hello World") == "Hello World"
```
you can then do eveything you can do with a `LocalShell`. Beware that some SSH servers
refuse to set environment variable (see documentation of AcceptEnv of
[sshd_config](https://linux.die.net/man/5/sshd_config) and documentation of `update_environment` of [paramiko's `Channel` class](http://docs.paramiko.org/en/2.4/api/channel.html)) and that will fail silently.
### AdbShell
you can instanciate the `AdbShell` for shell over ADB:
```python
from citizenshell import AdbShell
shell = AdbShell(hostname="acme.org", username="john", password="secretpassword")
assert shell("echo Hello World") == "Hello World"
```
you can then do eveything you can do with a `LocalShell`.
### SerialShell
you can instanciate the `SerialShell` for shell over serial line:
```python
from serial import EIGHTBITS, PARITY_NONE
from citizenshell import SerialShell
shell = SerialShell(port="/dev/ttyUSB3", username="john", password="secretpassword", baudrate=115200, parity=PARITY_NONE, bytesize=EIGHTBITS)
assert shell("echo Hello World") == "Hello World"
```
you can then do eveything you can do with a `LocalShell`.
### Shell
you can also obtain shell objects by URI using the `Shell` function:
```python
from citizenshell import Shell
localshell = Shell()
telnetshell = Shell("telnet://john:secretpassword@acme.org:1234")
secureshell = Shell("ssh://john:secretpassword@acme.org:1234")
adbshell = Shell("adb://myandroiddevice:5555")
serialshell = Shell("serial://jogn:secretpassword@/dev/ttyUSB3?baudrate=115200")
```
you can mix and match betweens providing arguments in the URI or via kwargs:
```python
from citizenshell import Shell
localshell = Shell()
telnetshell = Shell("telnet://john@acme.org", password="secretpassword", port=1234)
serialshell = Shell("serial://jogn:secretpassword@/dev/ttyUSB3", baudrate=115200)
```
you can then use the shell objects as you would any other.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
citizenshell-1.1.1.tar.gz
(12.9 kB
view hashes)
Built Distribution
Close
Hashes for citizenshell-1.1.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | adb4f9c7ecbc09272ad0ebef0b866c8a40cfbfdca7cec658785e676a22d490be |
|
MD5 | 0f62dad406c166c07b26f2cfeebce2c2 |
|
BLAKE2b-256 | e8a00bb6b1298d3f3fb9749614deac355599a1466baef9113cc31eadbf0e5247 |