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, alias=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, ipv6_only=False)
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()

Deprecated and a no-op. Disconnections handled by client de-allocation.

execute(cmd, use_pty=False, channel=None)

Deprecated - use run_command instead which returns a HostOutput object.

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.

read_output(stdout_buffer, timeout=None)

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

Parameters:
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.

  • encoding (str) – Encoding for output.

read_stderr(stderr_buffer, timeout=None)

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

Parameters:
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')
sock
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.PollMixIn(sock=None)

MixIn for co-operative socket polling functionality.

eagain(func, *args, **kwargs)
eagain_write(write_func, data)
poll(timeout=None)
sock
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.