Reference/API

pystassh.session module

The Session object is the entry point of any command execution via SSH.

Examples

Open a SSH connection, run the “ls” command and print the output.

>>> with Session('localhost', 'foo', 'bar') as ssh_session:
...     result = ssh_session.execute('ls')
...     print(result.stdout)
class pystassh.session.Session(hostname='localhost', username='', password='', passphrase='', port=22, privkey_file='')

Bases: object

channel
connect()

Initiate the connection and authentication process on the remote server.

Raises:
  • ConnectionException – if an error occurred during the connection process
  • AuthenticationException – if an error occurred during the authentication process
disconnect()

Close the current connection.

execute(command)

Execute a command on the remote server.

Parameters:command (str) – the command to run
Returns:the Result object for this command
Return type:Result
get_error_message(session=None)

Tries to retrieve an error message in case of error.

Parameters:session – a session object that will be used instead of self._session
Returns:An error message
Return type:str
is_connected()

Check if the connexion is currently active.

Returns:A boolean indicating whether or not the connexion is currently active.
Return type:bool

pystassh.channel module

class pystassh.channel.Channel(session)

Bases: object

close()

Close the current channel.

execute(command)

Execute a command.

Parameters:command (str) – the command to run
Returns:the Result object for this command
Return type:Result
get_error_message()

Tries to retrieve an error message in case of error.

Returns:An error message
Return type:str
is_eof()

Check if remote has sent an EOF.

open()

Open a new channel.

Raises:ChannelException – if the channel could not be correctly initialized
read(size=2048, from_stderr=False)

Reads data from a channel. The read will block.

Parameters:
  • size (int) – bytes to read.
  • from_stderr (bool) – read from standard error instead from stdout.
Returns:

the string read. Returns an empty string on EOF.
Return type:

string (str)
read_nonblocking(size=2048, from_stderr=False)

Do a nonblocking read on the channel.

Parameters:
  • size (int) – bytes to try to read atomically and without blocking.
  • from_stderr (bool) – read from standard error instead from stdout.
Returns:

the string read. It may be shorter than the expected size.

An empty string does not imply an EOF: you still have to check it.
Return type:

string (str)
request_shell(request_pty=False)

Request a shell and optionally a PTY.

write(data)

Blocking write on a channel.

Parameters:data (str) – data to encode (to bytes) and write (not binary safe).
Results:
The number of bytes written.

pystassh.result module

class pystassh.result.Result(channel, command)

Bases: object

command

The command from wich the current results came from.

raw_stderr

The raw content of the standard error output, as a list of bytes.

raw_stdout

The raw content of the standard output, as a list of bytes.

return_code

The return code of the last command as an int.

stderr

The content of the standard error output, as a string. Decoding errors are not caught at this level.

stdout

The content of the standard output, as a string. Decoding errors are not caught at this level.