Base Single Client

API documentation for common single host client functionality.

This class is abstract and contains functions that need to be implemented for each underlying SSH library.

class pssh.clients.base.single.BaseSSHClient(host, user=None, password=None, port=None, pkey=None, num_retries=3, retry_delay=5, allow_agent=True, timeout=None, proxy_host=None, proxy_port=None, _auth_thread_pool=True, identity_auth=True)
auth()
close_channel(channel)
copy_file(local_file, remote_file, recurse=False, sftp=None)
copy_remote_file(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')
disconnect()
execute(cmd, use_pty=False, channel=None)
get_exit_status(channel)
mkdir(sftp, directory)
open_session()
open_shell(encoding='utf-8', read_timeout=None)

Open interactive shell on new channel.

Can be used as context manager - with open_shell() as shell.

Parameters
  • encoding (str) – Encoding to use for command string and shell output.

  • read_timeout (float) – Timeout in seconds for reading from output.

poll(timeout=None)
read_output(stdout_buffer, timeout=None)

Read standard output buffer. Returns a generator of line by line output.

Parameters

stdout_buffer (pssh.clients.reader.ConcurrentRWBuffer) – Buffer to read from.

Return type

generator

read_output_buffer(output_buffer, prefix=None, callback=None, callback_args=None, encoding='utf-8')

Read from output buffers and log to host_logger.

Parameters
  • output_buffer (iterator) – Iterator containing buffer

  • prefix (str) – String to prefix log output to host_logger with

  • callback (function) – Function to call back once buffer is depleted:

  • callback_args (tuple) – Arguments for call back function

read_stderr(stderr_buffer, timeout=None)

Read standard error buffer. Returns a generator of line by line output.

Parameters

stdout_buffer (pssh.clients.reader.ConcurrentRWBuffer) – Buffer to read from.

Return type

generator

run_command(command, sudo=False, user=None, use_pty=False, shell=None, encoding='utf-8', timeout=None, read_timeout=None)

Run remote command.

Parameters
  • command (str) – Command to run.

  • sudo (bool) – Run command via sudo as super-user.

  • user (str) – Run command as user via sudo

  • use_pty (bool) – Whether or not to obtain a PTY on the channel.

  • shell (str) – (Optional) Override shell to use to run command with. Defaults to login user’s defined shell. Use the shell’s command syntax, eg shell=’bash -c’ or shell=’zsh -c’.

  • encoding (str) – Encoding to use for output. Must be valid Python codec

  • read_timeout (float) – (Optional) Timeout in seconds for reading output.

  • timeout – Deprecated - use read_timeout.

Return type

pssh.output.HostOutput

scp_recv(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')
scp_send(local_file, remote_file, recurse=False, sftp=None)
sftp_get(sftp, remote_file, local_file)
sftp_put(sftp, local_file, remote_file)
wait_finished(host_output, timeout=None)
IDENTITIES = ('/home/docs/.ssh/id_rsa', '/home/docs/.ssh/id_dsa', '/home/docs/.ssh/identity', '/home/docs/.ssh/id_ecdsa', '/home/docs/.ssh/id_ed25519')
class pssh.clients.base.single.InteractiveShell(channel, client, encoding='utf-8', read_timeout=None)

Run commands on an interactive shell.

Use as context manager to wait for commands to finish on exit.

Read from .stdout and stderr once context manager has exited.

InteractiveShell.output is a pssh.output.HostOutput object.

Parameters
  • channel (ssh2.channel.Channel or similar.) – The channel to open shell on.

  • client (BaseSSHClient) – The SSHClient that opened the channel.

  • encoding (str) – Encoding to use for command string when calling run and shell output.

close()

Wait for shell to finish executing and close channel.

run(cmd)

Run command on interactive shell.

Parameters

cmd (str) – The command string to run. Note that \n is appended to every string.

property exit_code

self.output.exit_code

output
property stderr

self.output.stderr

property stdin

self.output.stdin

property stdout

self.output.stdout

class pssh.clients.base.single.Stdin(channel, client)

Stdin stream for a channel.

Handles EAGAIN.

Provides write and flush only.

Parameters
  • channel (IO object) – The channel the stdin stream is from.

  • client (BaseSSHClient) – The SSH client the channel is from.

flush()

Flush pending data written to stdin.

write(data)

Write to stdin.

Parameters

data (str) – Data to write.