sshreader API

All the classes and functions that make sshreader tick

class sshreader.utils.Hook(target: Callable, args: list | None = None, kwargs: dict | None = None, ssh_established: bool = False)[source]

Custom class for creating “Hooks” that can execute code before of after a ServerJob object executes and can evn act on the data of a ServerJob when it is passed as the first argument to the Hook object.

Parameters:

  • target (func, required) – Function to call when using the hook

  • args (list, optional) – List of args to pass to target function

  • kwargs (dict, optional) – Dictionary of keyword arguments to pass to target function

  • ssh_established (bool, optional) – Should the ssh connection be established when the hook is run (Default: False)

Raises:

TypeError

run(*args, **kwargs) → Any[source]

Run the Hook. You can add additional args or kwargs at this time!

Parameters:

  • args (list, optional) – Append to args

  • kwargs (dict, optional) – Append to/update kwargs

Returns:

Result from target function

class sshreader.utils.ServerJob(fqdn: str, cmds: list | tuple | str, username: str | None = None, password: str | None = None, keyfile: str | None = None, key_pass: str | None = None, timeout: int | float | Tuple[int | float, int | float] | None = (0.5, 30), run_local: bool = False, pre_hook: Hook | None = None, post_hook: Hook | None = None, combine_output: bool = False, ssh_port: int = 22, rsa_sha2: bool | None = True)[source]

Custom class for holding all the info needed to run ssh commands or shell commands in sub-processes or threads

Parameters:

  • fqdn (str, required) – Fully qualified domain name or IP address

  • cmds (list, required) – List of commands to run (in the order you want them run)

  • username (str, optional) – Username for SSH

  • password (str, optional) – Password for SSH

  • keyfile (str, optional) – Path to ssh private key

  • key_pass (str, optional) – Password for private ssh key file

  • ssh_port (int) – Integer of SSH Port to use (Default: 22)

  • rsa_sha2 (bool, optional) – Enable/Disable RSA w/SHA2 hashes (Default: True)

  • timeout (tuple, optional) – Tuple of timeouts in seconds (TCP timeout, SSH Timeout)

  • run_local (bool, optional) – Run job on localhost without opening SSH connection (Default: False)

  • pre_hook (Hook, optional) – Hook object

  • post_hook (Hook, optional) – Hook object

  • combine_output (bool, optional) – Combine stdout and stderr (Default: False)

Property results:

List of namedtuples (cmd, stdout, stderr, return_code) or (cmd, stdout, return_code)

Property status:

Sum of return codes for entire job (255 = ssh did not connect)

run() → int[source]

Run a ServerJob. SSH to server, run cmds, return result

Returns:

Sum of return codes for each command executed

Return type:

int

sshreader.utils.echo(*args, **kwargs) → None[source]

Wrapper for print that implements a multiprocessing.Lock object as well as uses unbuffered output to sys.stdout.

Parameters:

  • args – Passthrough to print function

  • kwargs – Passthrough to print function

Returns:

None

Return type:

None

sshreader.utils.shell_command(command: str, combine: bool = False, decode_bytes: bool = True) → Command[source]

Run a command in the shell on localhost and return the output. This attempts to be a simplified wrapper for subprocess.run

Parameters:

  • command (str, required) – The shell script to run

  • combine (bool, optional) – Direct stderr to stdout (Default: False)

  • decode_bytes (bool, optional) – Decode bytes objects to unicode strings (Default: True)

Returns:

NamedTuple for (cmd, stdout, stderr) or (cmd, stdout)

Return type:

Command

Raises:

None

sshreader.utils.sshread(serverjobs: list, pcount: int | None = None, tcount: int | None = None, progress_bar: bool = False, print_lock: bool = True) → list[source]

Takes a list of ServerJob objects and puts them into threads/sub-processes and runs them

Parameters:

  • serverjobs (list, required) – List of ServerJob objects

  • pcount (int, required) – Number of sub-processes to spawn (None = off, 0 = cpu_limit(), -1 = cpu_limit(2)

  • tcount (int, required) – Number of threads to spawn (None = off, 0 = cpu_limit())

  • progress_bar (bool, optional) – Print a progress bar (Default: False)

  • print_lock (bool, optional) – Create a :class:multiprocessing.Lock for use with sshreader.echo()

Returns:

List of completed ServerJob objects (single object returned if 1 job was passed)

Return type:

list

Raises:

ExceedCPULimit, TypeError, ValueError

Indices and tables