tessl/pypi-parallel-ssh

Asynchronous parallel SSH client library that enables developers to execute SSH commands across many servers simultaneously with minimal system load on the client host.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Parallel SSH

Name: tessl/pypi-parallel-ssh
Author: tessl

Asynchronous parallel SSH client library that enables developers to execute SSH commands across many servers simultaneously with minimal system load on the client host. Built on mature C libraries (libssh2 and libssh) providing thread safety, native asynchronous execution, and significantly reduced CPU and memory overhead compared to other Python SSH libraries.

Package Information

Package Name: parallel-ssh
Language: Python
Installation: pip install parallel-ssh

Core Imports

from pssh.clients import ParallelSSHClient, SSHClient

Alternative SSH implementation (libssh-based):

from pssh.clients.ssh import ParallelSSHClient, SSHClient

Configuration and utilities:

from pssh.config import HostConfig
from pssh.utils import enable_host_logger, enable_debug_logger

Basic Usage

from pssh.clients import ParallelSSHClient

# Execute commands on multiple hosts in parallel
hosts = ['host1.example.com', 'host2.example.com', 'host3.example.com']
client = ParallelSSHClient(hosts)

# Run a command on all hosts
output = client.run_command('uname -a')

# Wait for completion and get results
client.join()
for host_output in output:
    print(f"Host: {host_output.host}")
    for line in host_output.stdout:
        print(line)
    print(f"Exit code: {host_output.exit_code}")

# Single host usage
from pssh.clients import SSHClient

client = SSHClient('host.example.com')
host_output = client.run_command('ls -la')
for line in host_output.stdout:
    print(line)

Architecture

The library provides two main client implementations:

Native Client (default): Based on ssh2-python (libssh2 C library) offering highest performance and stability
SSH Client: Alternative implementation using ssh-python (libssh C library) with identical API

Both implementations support:

Parallel execution across hundreds or thousands of hosts
Thread-safe operations with native threading for CPU-bound tasks like authentication
Asynchronous I/O using gevent for non-blocking operations
Comprehensive file transfer via both SFTP and SCP protocols
Flexible authentication including SSH keys, passwords, and SSH agent integration
Advanced networking with proxy support and IPv6 capabilities

Capabilities

Parallel SSH Operations

Execute commands across multiple hosts simultaneously with comprehensive configuration options, authentication methods, and result handling.

class ParallelSSHClient:
    def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
                 num_retries=3, timeout=None, pool_size=100, allow_agent=True,
                 host_config=None, retry_delay=5, proxy_host=None, proxy_port=None,
                 proxy_user=None, proxy_password=None, proxy_pkey=None,
                 forward_ssh_agent=False, keepalive_seconds=60, identity_auth=True,
                 ipv6_only=False): ...
    
    def run_command(self, command, sudo=False, user=None, stop_on_errors=True,
                   use_pty=False, host_args=None, shell=None, encoding='utf-8',
                   read_timeout=None): ...
    
    def join(self, output=None, consume_output=False, timeout=None): ...

Parallel Operations

Single Host SSH Operations

Connect to and execute commands on individual hosts with the same rich feature set as parallel operations, ideal for single-host workflows.

class SSHClient:
    def __init__(self, host, user=None, password=None, port=None, pkey=None,
                 alias=None, num_retries=3, retry_delay=5, allow_agent=True,
                 timeout=None, forward_ssh_agent=False, proxy_host=None,
                 proxy_port=None, proxy_pkey=None, proxy_user=None,
                 proxy_password=None, keepalive_seconds=60, identity_auth=True,
                 ipv6_only=False): ...
    
    def run_command(self, command, sudo=False, user=None, use_pty=False,
                   shell=None, encoding='utf-8', timeout=None, read_timeout=None): ...

Single Host Operations

File Transfer Operations

High-performance file copying between local and remote hosts using both SFTP and SCP protocols, with support for recursive directory operations and per-host file naming.

# SFTP operations
def copy_file(self, local_file, remote_file, recurse=False, copy_args=None): ...
def copy_remote_file(self, remote_file, local_file, recurse=False,
                    suffix_separator='_', copy_args=None, encoding='utf-8'): ...

# SCP operations  
def scp_send(self, local_file, remote_file, recurse=False, copy_args=None): ...
def scp_recv(self, remote_file, local_file, recurse=False, copy_args=None,
            suffix_separator='_'): ...

File Transfer

Configuration and Host Management

Flexible per-host configuration system allowing different authentication methods, connection parameters, and proxy settings for individual hosts within parallel operations.

class HostConfig:
    def __init__(self, user=None, port=None, password=None, private_key=None,
                 allow_agent=None, alias=None, num_retries=None, retry_delay=None,
                 timeout=None, identity_auth=None, proxy_host=None, proxy_port=None,
                 proxy_user=None, proxy_password=None, proxy_pkey=None,
                 keepalive_seconds=None, ipv6_only=None, cert_file=None,
                 auth_thread_pool=True, gssapi_auth=False,
                 gssapi_server_identity=None, gssapi_client_identity=None,
                 gssapi_delegate_credentials=False, forward_ssh_agent=False): ...

Configuration

Interactive Shell Sessions

Open and manage interactive shell sessions on remote hosts for complex multi-command workflows and real-time interaction.

def open_shell(self, encoding='utf-8', read_timeout=None): ...

class InteractiveShell:
    def run(self, cmd): ...
    def close(self): ...
    def __enter__(self): ...  # Context manager support
    def __exit__(self, exc_type, exc_val, exc_tb): ...
    # Properties: stdout, stderr, stdin, exit_code, output

class Stdin:
    def write(self, data): ...
    def flush(self): ...

Interactive Shells

Output Processing and Result Handling

Comprehensive result objects providing access to command output, exit codes, and execution metadata for both parallel and single-host operations.

class HostOutput:
    # Properties
    host: str
    alias: str  
    channel: object
    stdin: object
    stdout: generator  # Yields output lines
    stderr: generator  # Yields error lines
    exit_code: int     # Command exit code (None until ready)
    client: object     # Reference to SSH client
    exception: Exception  # Exception if any occurred

Output Handling

Types

# Core exceptions
class UnknownHostError(Exception): ...
class ConnectionError(Exception): ...
class AuthenticationError(Exception): ...
class Timeout(Exception): ...
class SessionError(Exception): ...
class SFTPError(Exception): ...
class SFTPIOError(SFTPError): ...
class SCPError(Exception): ...
class ProxyError(Exception): ...
class HostArgumentError(Exception): ...
class ShellError(Exception): ...
class PKeyFileError(Exception): ...
class NoIPv6AddressFoundError(Exception): ...
class HostConfigError(Exception): ...

# Constants
DEFAULT_RETRIES = 3
RETRY_DELAY = 5

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:pypi/parallel-ssh@2.14.x
Publish Source: CLI
Badge