Fix read same host (#242)

* Added read output from multiple commands on same host test
* Updated examples
* Updated host output to hold output buffers - updated clients.
* Updated documentation, readme, changelog
* Removed travis cfg

Author: pkittenis

.travis.yml

@@ -1,6 +1,21 @@
 Change Log
 ============
 
+2.3.1
++++++
+
+Changes
+-------
+
+* ``SSHClient.read_output`` and ``read_stderr`` now take buffer to read from as argument instead of channel.
+* ``SSHClient.wait_finished`` now takes ``HostOutput`` argument instead of channel.
+
+Fixes
+-----
+
+* Output for multiple commands on one host run at the same time would be lost.
+
+
 2.3.0
 +++++
 
@@ -34,7 +49,7 @@ As is this:
 
 .. code-block:: python
 
-   client.run_command(<..>, timeout=1)
+   client.run_command(<..>, read_timeout=1)
    client.join(output, timeout=1)
    for line in output[0].stdout:
        print(line)

Changelog.rst

@@ -8,16 +8,14 @@ Run SSH commands over many - hundreds/hundreds of thousands - number of servers
 
 Native code based client with extremely high performance - based on ``libssh2`` C library.
 
-.. image:: https://img.shields.io/badge/License-LGPL%20v2-blue.svg
+.. image:: https://img.shields.io/badge/License-LGPL%20v2.1-blue.svg
   :target: https://pypi.python.org/pypi/parallel-ssh
   :alt: License
 .. image:: https://img.shields.io/pypi/v/parallel-ssh.svg
   :target: https://pypi.python.org/pypi/parallel-ssh
   :alt: Latest Version
 .. image:: https://circleci.com/gh/ParallelSSH/parallel-ssh/tree/master.svg?style=svg
   :target: https://circleci.com/gh/ParallelSSH/parallel-ssh
-.. image:: https://ci.appveyor.com/api/projects/status/github/parallelssh/parallel-ssh?svg=true&branch=master
-  :target: https://ci.appveyor.com/project/pkittenis/parallel-ssh-4nme1
 .. image:: https://codecov.io/gh/ParallelSSH/parallel-ssh/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/ParallelSSH/parallel-ssh
 .. image:: https://img.shields.io/pypi/wheel/parallel-ssh.svg
@@ -44,7 +42,7 @@ Usage Example
 
 See documentation on `read the docs`_ for more complete examples.
 
-Run ``uname`` on two remote hosts in parallel.
+Run ``uname`` on two hosts in parallel.
 
 .. code-block:: python
 
@@ -53,7 +51,7 @@ Run ``uname`` on two remote hosts in parallel.
   hosts = ['localhost', 'localhost']
   client = ParallelSSHClient(hosts)
 
-  output = client.run_command('uname', return_list=True)
+  output = client.run_command('uname')
   for host_output in output:
       for line in host_output.stdout:
           print(line)
@@ -65,15 +63,34 @@ Run ``uname`` on two remote hosts in parallel.
       Linux
       Linux
 
+
+Single Host Client
+*******************
+
+Single host client with similar API for users that do not need parallel functionality.
+
+.. code-block:: python
+
+   from pssh.clients import SSHClient
+
+   host = 'localhost'
+   cmd = 'uname'
+   client = SSHClient(host)
+
+   host_out = client.run_command(cmd)
+   for line in host_out.stdout:
+       print(line)
+
+
 **************
 Native clients
 **************
 
-Starting from version ``1.2.0``, the default client in ``parallel-ssh`` has changed to a native client based on ``ssh2-python`` - ``libssh2`` C library - which offers much greater performance and reduced overhead compared to other Python SSH libraries.
+The default client in ``parallel-ssh`` is a native client based on ``ssh2-python`` - ``libssh2`` C library - which offers much greater performance and reduced overhead compared to other Python SSH libraries.
 
 See `this post <https://parallel-ssh.org/post/parallel-ssh-libssh2>`_ for a performance comparison of different Python SSH libraries.
 
-An alternative client based on ``ssh-python`` (``libssh``) is also available. See `client documentation <http://parallel-ssh.readthedocs.io/en/latest/clients.html>`_ for a feature comparison of the available clients in the library.
+Alternative clients based on ``ssh-python`` (``libssh``) are also available under ``pssh.clients.ssh``. See `client documentation <http://parallel-ssh.readthedocs.io/en/latest/clients.html>`_ for a feature comparison of the available clients in the library.
 
 ``parallel-ssh`` makes use of clients and an event loop solely based on C libraries providing native code levels of performance and stability with an easy to use Python API.
 
@@ -84,15 +101,15 @@ Native Code Client Features
 
 * Highest performance and least overhead of any Python SSH library
 * Thread safe - makes use of native threads for CPU bound calls like authentication
-* Natively non-blocking utilising ``libssh2`` via ``ssh2-python``
+* Natively asynchronous utilising ``libssh2`` via ``ssh2-python``
 * Significantly reduced overhead in CPU and memory usage
 
 
 ***********
 Exit codes
 ***********
 
-Once *either* standard output is iterated on *to completion*, or ``client.join(output, consume_output=True)`` is called, exit codes become available in host output.
+Once *either* standard output is iterated on *to completion*, or ``client.join()`` is called, exit codes become available in host output.
 
 Iteration ends *only when remote command has completed*, though it may be interrupted and resumed at any point.
 
@@ -126,23 +143,22 @@ After ``join`` returns, commands have finished and all output can be read withou
 
 .. code-block:: python
 
-  client.join(output)
+  client.join()
 
   for host_out in output:
       for line in host_output.stdout:
           print(line)
       print(host_out.exit_code)
 
-Similarly, exit codes are available after ``client.join(output, consume_output=True)``.
+Similarly, exit codes are available after ``client.join()`` without reading output.
 
-``consume_output`` flag must be set to get exit codes when not reading from ``stdout``. Future releases aim to remove the need for `consume_output` to be set.
 
 .. code-block:: python
 
   output = client.run_command('uname')
 
   # Wait for commands to complete and consume output so can get exit codes
-  client.join(output, consume_output=True)
+  client.join()
 
   for host_output in output:
       print(host_out.exit_code)

README.rst

@@ -18,7 +18,7 @@ SFTP copy to/from hosts           Yes                   No
 OpenSSH config parsing            Not yet implemented   Not yet implemented
 ECDSA keys support                Yes                   Yes
 ED25519 keys support              Yes                   Yes
-Certificate authentication        Not supported         Not yet implemented
+Certificate authentication        Not supported         Yes
 SCP functionality                 Yes                   No
 Keep-alive functionality          Yes                   No
 ===============================  ====================== ======================

doc/clients.rst

@@ -60,7 +60,7 @@
 
 # General information about the project.
 project = u'Parallel-SSH'
-copyright = u'2014-2017, P Kittenis'
+copyright = u'2014-2020, P Kittenis'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/conf.py

@@ -17,7 +17,7 @@ Examples all assume a valid key is available on a running SSH agent. See `Progra
 Complete Example
 -----------------
 
-Host list can contain identical hosts. Commands are executed concurrently on every host given to the client regardless.
+Host list can contain identical hosts. Commands are executed concurrently on every host given to the client regardless, up to pool size.
 
 .. code-block:: python
 
@@ -45,7 +45,7 @@ Output:
 Single Host Client
 ====================
 
-``parallel-ssh`` has a fully featured, non-blocking single host client that it uses for all its parallel commands.
+``parallel-ssh`` has a fully featured, asynchronous single host client that it uses for all its parallel commands.
 
 Users that do not need the parallel capabilities can use the single host client for a simpler way to run asynchronous non-blocking commands on a remote host.
 
@@ -150,7 +150,7 @@ Complete Example
 
   client = ParallelSSHClient(['localhost', 'localhost'])
   output = client.run_command('whoami')
-  client.join(output)
+  client.join()
 
   for host_output in output:
       hostname = host_output.host

doc/quickstart.rst

@@ -0,0 +1,13 @@
+from pssh.clients import ParallelSSHClient, SSHClient
+
+
+hosts = ['localhost']
+cmd = 'uname'
+
+client = ParallelSSHClient(hosts)
+output = client.run_command(cmd)
+
+for host_out in output:
+    for line in host_out.stdout:
+        print(line)
+print("Host %s: exit code %s" % (host_out.host, host_out.exit_code))

examples/pssh_local.py

@@ -268,11 +268,10 @@ def _join(self, host_out, consume_output=False, timeout=None,
               encoding="utf-8"):
         if host_out is None:
             return
-        channel = host_out.channel
         client = host_out.client
         if client is None:
             return
-        client.wait_finished(channel, timeout=timeout)
+        client.wait_finished(host_out, timeout=timeout)
         if consume_output:
             self._consume_output(host_out.stdout, host_out.stderr)
         return host_out