Added exception raising on join timeout reached with command still running, tests.

Updated docs, added base parallel client class.
 Updated changelog.Resolves #101

Author: Pan

Changelog.rst

@@ -1,6 +1,20 @@
 Change Log
 ============
 
+1.4.0
+++++++
+
+Changes
+----------
+
+* ``ParallelSSH2Client.join`` now raises ``pssh.exceptions.Timeout`` exception when timeout is requested and reached with command still running.
+
+
+Fixes
+--------
+
+* ``ParallelSSH2Client.join`` timeout duration was incorrectly for per-host rather than total.
+
 1.3.2
 ++++++
 

doc/api.rst

@@ -8,6 +8,7 @@ API Documentation
    ssh_client
    pssh2_client
    ssh2_client
+   base_pssh
    output
    agent
    utils

doc/base_pssh.rst

@@ -0,0 +1,7 @@
+BaseParallelSSHClient
+======================
+
+API documentation for common parallel client functionality.
+
+.. automodule:: pssh.base_pssh
+    :member-order: groupwise

doc/ssh2.rst

@@ -5,22 +5,24 @@ For the ``ssh2-python`` (``libssh2``) based clients, not all features supported
 
 Below is a comparison of feature support for the two client types.
 
-===============================  =========  ======================
-Feature                          paramiko   ssh2-python (libssh2)
-===============================  =========  ======================
-Agent forwarding                  Yes       Not supported
-Proxying/tunnelling               Yes       Not yet implemented
-Kerberos (GSS) authentication     Yes       Not supported
-Private key file authentication   Yes       Yes
-Private key from memory           Yes       Not yet implemented
-Agent authentication              Yes       Yes
-Password authentication           Yes       Yes
-SFTP copy to/from hosts           Yes       Yes
-Session timeout setting           Yes       Yes
-Per-channel timeout setting       Yes       Not supported
-Programmatic SSH agent            Yes       Not supported
-OpenSSH config parsing            Yes       Not yet implemented
-===============================  =========  ======================
+===============================  ============== ======================
+Feature                          paramiko       ssh2-python (libssh2)
+===============================  ============== ======================
+Agent forwarding                  Yes           Not supported (*PR Pending*)
+Proxying/tunnelling               Yes           Yes
+Kerberos (GSS) authentication     Yes           Not supported
+Private key file authentication   Yes           Yes
+Private key from memory           Yes           Not yet implemented
+Agent authentication              Yes           Yes
+Password authentication           Yes           Yes
+SFTP copy to/from hosts           Yes           Yes
+Session timeout setting           Yes           Yes
+Per-channel timeout setting       Yes           Yes
+Programmatic SSH agent            Yes           Not supported
+OpenSSH config parsing            Yes           Not yet implemented
+ECSA keys support                 Yes           Not supported (*PR Pending*)
+SCP functionality                 Not supported Not yet implemented
+===============================  ============== ======================
 
 If any of missing features are required for a use case, then the paramiko based clients should be used instead.
 

pssh/base_pssh.py

@@ -1,6 +1,6 @@
 # This file is part of parallel-ssh.
 
-# Copyright (C) 2014-2017 Panos Kittenis
+# Copyright (C) 2014-2018 Panos Kittenis
 
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -40,6 +40,8 @@
 
 class BaseParallelSSHClient(object):
 
+    """Parallel client base class."""
+
     def __init__(self, hosts, user=None, password=None, port=None, pkey=None,
                  allow_agent=True,
                  num_retries=DEFAULT_RETRIES,

pssh/exceptions.py

@@ -61,3 +61,7 @@ class SFTPIOError(SFTPError):
 
 class ProxyError(Exception):
     """Raised on proxy errors"""
+
+
+class Timeout(Exception):
+    """Raised on timeout requested and reached"""

pssh/pssh2_client.py

@@ -1,6 +1,6 @@
 # This file is part of parallel-ssh.
 
-# Copyright (C) 2014-2017 Panos Kittenis
+# Copyright (C) 2014-2018 Panos Kittenis
 
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -21,7 +21,7 @@
 from .base_pssh import BaseParallelSSHClient
 from .constants import DEFAULT_RETRIES, RETRY_DELAY
 from .ssh2_client import SSHClient
-from .exceptions import ProxyError
+from .exceptions import ProxyError, Timeout
 from .tunnel import Tunnel
 
 
@@ -207,13 +207,20 @@ def join(self, output, consume_output=False, timeout=None):
           finished.
         :type timeout: int
 
+        :raises: :py:class:`pssh.exceptions.Timeout` on timeout requested and
+          reached with commands still running.
+
         :rtype: ``None``"""
         for host in output:
             if host not in self.host_clients or self.host_clients[host] is None:
                 continue
             self.host_clients[host].wait_finished(output[host].channel,
                                                   timeout=timeout)
-            if consume_output:
+            if timeout and not output[host].channel.eof():
+                raise Timeout(
+                    "Timeout of %s sec(s) reached on host %s with command "
+                    "still running", timeout, host)
+            elif consume_output:
                 for line in output[host].stdout:
                     pass
                 for line in output[host].stderr:

pssh/utils.py

@@ -1,6 +1,6 @@
 # This file is part of parallel-ssh.
 
-# Copyright (C) 2014-2017 Panos Kittenis
+# Copyright (C) 2014-2018 Panos Kittenis
 
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -16,7 +16,7 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 
-"""Package containing static utility functions for parallel-ssh module."""
+"""Module containing static utility functions for parallel-ssh."""
 
 
 import logging
@@ -54,7 +54,9 @@ def enable_host_logger():
 
 
 def load_private_key(_pkey):
-    """Load private key from pkey file object or filename
+    """Load private key from pkey file object or filename.
+
+    For Paramiko based clients only.
 
     :param pkey: File object or file name containing private key
     :type pkey: file/str"""

tests/test_pssh_ssh2_client.py

@@ -39,7 +39,7 @@
 from pssh.pssh2_client import ParallelSSHClient, logger as pssh_logger
 from pssh.exceptions import UnknownHostException, \
     AuthenticationException, ConnectionErrorException, SessionError, \
-    HostArgumentException, SFTPError, SFTPIOError
+    HostArgumentException, SFTPError, SFTPIOError, Timeout
 
 from .embedded_server.embedded_server import make_socket
 from .embedded_server.openssh import OpenSSHServer
@@ -1167,10 +1167,11 @@ def test_join_timeout(self):
         client = ParallelSSHClient([self.host], port=self.port,
                                    pkey=self.user_key)
         output = client.run_command('sleep 2')
-        client.join(output, timeout=1)
+        self.assertRaises(Timeout, client.join, output, timeout=1)
         self.assertFalse(output[self.host].channel.eof())
         client.join(output, timeout=2)
         self.assertTrue(output[self.host].channel.eof())
+        self.assertTrue(client.finished(output))
 
     def test_read_timeout(self):
         client = ParallelSSHClient([self.host], port=self.port,