To run echo locally:
import spur shell = spur.LocalShell() result = shell.run(["echo", "-n", "hello"]) print result.output # prints hello
Executing the same command over SSH uses the same interface – the only difference is how the shell is created:
import spur shell = spur.SshShell(hostname="localhost", username="bob", password="password1") result = shell.run(["echo", "-n", "hello"]) print result.output # prints hello
Installation
$ pip install spur
Shell constructors
LocalShell
Takes no arguments:
spur.LocalShell()
SshShell
Requires a hostname and a username. Also requires some combination of a password and private key, as necessary to authenticate:
# Use a password
spur.SshShell(
hostname="localhost",
username="bob",
password="password1"
)
# Use a private key
spur.SshShell(
hostname="localhost",
username="bob",
private_key_file="path/to/private.key"
)
# Use a port other than 22
spur.SshShell(
hostname="localhost",
port=50022,
username="bob",
password="password1"
)
Optional arguments:
connect_timeout – a timeout in seconds for establishing an SSH connection. Defaults to 60 (one minute).
Shell interface
run(command, cwd, update_env, store_pid, allow_error, stdout, stderr)
Run a command and wait for it to complete. The command is expected to be a list of strings. Returns an instance of ExecutionResult.
result = shell.run(["echo", "-n", "hello"]) print result.output # prints hello
Note that arguments are passed without any shell expansion. For instance, shell.run(["echo", "$PATH"]) will print the literal string $PATH rather than the value of the environment variable $PATH.
Optional arguments:
cwd – change the current directory to this value before executing the command.
update_env – a dict containing environment variables to be set before running the command. If there’s an existing environment variable with the same name, it will be overwritten. Otherwise, it is unchanged.
store_pid – if set to True when calling spawn, store the process id of the spawned process as the attribute pid on the returned process object. Has no effect when calling run.
allow_error – False by default. If False, an exception is raised if the return code of the command is anything but 0. If True, a result is returned irrespective of return code.
stdout – if not None, anything the command prints to standard output during its execution will also be written to stdout using stdout.write.
stderr – if not None, anything the command prints to standard error during its execution will also be written to stderr using stderr.write.
shell.run(*args, **kwargs) should behave similarly to shell.spawn(*args, **kwargs).wait_for_result()
spawn(command, cwd, update_env, store_pid, allow_error, stdout, stderr)
Behaves the same as run except that spawn immediately returns an object representing the running process.
open(path, mode=”r”)
Open the file at path. Returns a file-like object.
Process interface
Returned by calls to shell.spawn. Has the following attributes:
pid – the process ID of the process. Only available if store_pid was set to True when calling spawn.
Has the following methods:
is_running() – return True if the process is still running, False otherwise.
stdin_write(value) – write value to the standard input of the process.
wait_for_result() – wait for the process to exit, and then return an instance of ExecutionResult. Will raise RunProcessError if the return code is not zero and shell.spawn was not called with allow_error=True.
send_signal(signal) – sends the process the signal signal. Only available if store_pid was set to True when calling spawn.
Classes
ExecutionResult
ExecutionResult has the following properties:
return_code – the return code of the command
output – a string containing the result of capturing stdout
stderr_output – a string containing the result of capturing stdout
It also has the following methods:
to_error() – return the corresponding RunProcessError. This is useful if you want to conditionally raise RunProcessError, for instance:
result = shell.run(["some-command"], allow_error=True)
if result.return_code > 4:
raise result.to_error()
RunProcessError
A subclass of RuntimeError with the same properties as ExecutionResult:
return_code – the return code of the command
output – a string containing the result of capturing stdout
stderr_output – a string containing the result of capturing stdout
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file spur-0.2.4.tar.gz.
File metadata
- Download URL: spur-0.2.4.tar.gz
- Upload date:
- Size: 7.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a1b5de04c0bdeb0dd4cd94c44399405a32ef08b2d508ae54b0ffe1a6a23901af
|
|
| MD5 |
91199d2f49273b640e0a71b0583d3e64
|
|
| BLAKE2b-256 |
794e2cc048b4294840f32f1976426d81c572d24d8ae1c9501883d623a4e2d41e
|
