Updated documentation

Author: Dan

doc/agent.rst

@@ -0,0 +1,5 @@
+SSH Agent
+=========
+
+.. automodule:: pssh.agent
+    :member-order: groupwise

doc/index.rst

@@ -15,6 +15,8 @@ Parallel-SSH's documentation
 
    pssh_client
    ssh_client
+   output
+   agent
    exceptions
 
 Welcome to ParallelSSH's API documentation.

doc/output.rst

@@ -0,0 +1,5 @@
+Host Output
+============
+
+.. automodule:: pssh.output
+    :member-order: groupwise

pssh/agent.py

@@ -15,17 +15,35 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
+"""SSH agent module of ParallelSSH"""
+
 import paramiko.agent
 
 class SSHAgent(paramiko.agent.AgentSSH):
-    """:mod:`paramiko.agent.AgentSSH` compatible class for programmatically
+    """:py:class:`paramiko.agent.Agent` compatible class for programmatically
     supplying an SSH agent"""
 
     def __init__(self):
+        """**Example Usage**
+
+        .. code-block:: python
+
+          from pssh.agent import SSHAgent
+          from pssh.utils import load_private_key
+          from pssh import ParallelSSHClient
+
+          agent = SSHAgent()
+          agent.add_key(load_private_key('my_private_key_filename'))
+          agent.add_key(load_private_key('my_other_private_key_filename'))
+          hosts = ['my_host', 'my_other_host']
+
+          client = ParallelSSHClient(hosts, agent=agent)
+          client.run_command('uname')
+        """
         paramiko.agent.AgentSSH.__init__(self)
         self._conn = None
         self.keys = []
-    
+
     def add_key(self, key):
         """Add key to agent.
         :param key: Key to add

pssh/output.py

@@ -1,9 +1,35 @@
+#!/usr/bin/env python
+
+# This file is part of parallel-ssh.
+
+# Copyright (C) 2015- Panos Kittenis
+
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation, version 2.1.
+
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+
+"""Output module of ParallelSSH"""
+
 from os import linesep
 
+
 class HostOutput(dict):
+    """Class to hold host output"""
+
     __slots__ = ('host', 'cmd', 'channel', 'stdout', 'stderr', 'stdin', 'exit_code', 'exception')
 
-    def __init__(self, host, cmd, channel, stdout, stderr, stdin, exit_code=None, exception=None):
+    def __init__(self, host, cmd, channel, stdout, stderr, stdin,
+                 exit_code=None, exception=None):
         dict.__init__(self, (('host', host), ('cmd', cmd), ('channel', channel),
                              ('stdout', stdout), ('stderr', stderr),
                              ('stdin', stdin), ('exit_code', exit_code),
@@ -22,6 +48,7 @@ def __setattr__(self, name, value):
         dict.__setitem__(self, name, value)
 
     def update(self, update_dict):
+        """Override of dict update function for backwards compatibility"""
         dict.update(self, update_dict)
         for key in update_dict:
             object.__setattr__(self, key, update_dict[key])

pssh/pssh_client.py

@@ -16,7 +16,7 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 
-"""Package containing ParallelSSHClient class."""
+"""Package containing ParallelSSHClient class"""
 
 import sys
 if 'threading' in sys.modules:
@@ -139,19 +139,23 @@ def __init__(self, hosts,
         .. code-block:: python
         
           pprint(output)
-          
-            {'myhost1': {'exit_code': None,
-                         'stdout' : <generator>,
-                         'stderr' : <generator>,
-                         'cmd' : <greenlet>,
-                         'exception' : None,
-                         },
-             'myhost2': {'exit_code': None,
-                         'stdout' : <generator>,
-                         'stderr' : <generator>,
-                         'cmd' : <greenlet>,
-                         'exception' : None,
-            }}
+            {'myhost1': 
+                  host=myhost1
+                  cmd=<Greenlet>
+                  channel=<channel>
+                  stdout=<generator>
+                  stderr=<generator>
+                  stdin=<channel>
+                  exception=None
+             'myhost2': 
+                  host=myhost2
+                  cmd=<Greenlet>
+                  channel=<channel>
+                  stdout=<generator>
+                  stderr=<generator>
+                  stdin=<channel>
+                  exception=None
+            }
         
         **Enabling host logger**
         
@@ -378,8 +382,9 @@ def run_command(self, *args, **kwargs):
         host list - :py:class:`pssh.exceptions.HostArgumentException` is raised \
         otherwise
         :type host_args: tuple or list
-        :rtype: Dictionary with host as key as per \
-          :py:func:`pssh.pssh_client.ParallelSSHClient.get_output`
+        :rtype: Dictionary with host as key and \
+        :py:class:`pssh.output.HostOutput` as value as per \
+        :py:func:`pssh.pssh_client.ParallelSSHClient.get_output`
         
         :raises: :py:class:`pssh.exceptions.AuthenticationException` on \
         authentication error
@@ -528,13 +533,14 @@ def run_command(self, *args, **kwargs):
         
           client.hosts = ['otherhost']
           print(client.run_command('exit 0'))
-          {'otherhost': {'exit_code': None}, <..>}
+          {'otherhost': exit_code=None, <..>}
         
         **Run multiple commands in parallel**
         
-        This short example demonstrates running long running commands in
-        parallel, how long it takes for all commands to start, blocking until
-        they complete and how long it takes for all commands to complete.
+        This short example demonstrates running multiple long running commands
+        in parallel on the same host, how long it takes for all commands to
+        start, blocking until they complete and how long it takes for all
+        commands to complete.
         
         See examples directory for complete script. ::
         
@@ -562,7 +568,7 @@ def run_command(self, *args, **kwargs):
           Started 10 commands in 0:00:00.428629
           All commands finished in 0:00:05.014757
         
-        *Output dictionary*
+        *Output format*
         
         ::
         
@@ -668,7 +674,8 @@ def get_output(self, cmd, output):
         
         :param cmd: Command to get output from
         :type cmd: :py:class:`gevent.Greenlet`
-        :param output: Dictionary containing output to be updated with output \
+        :param output: Dictionary containing \
+        :py:class:`pssh.output.HostOutput` values to be updated with output \
         from cmd
         :type output: dict
         :rtype: None
@@ -677,12 +684,14 @@ def get_output(self, cmd, output):
         
         ::
         
-          {'myhost1': {'exit_code': exit code if ready else None,
-                       'channel' : SSH channel of command,
-                       'stdout'  : <iterable>,
-                       'stderr'  : <iterable>,
-                       'cmd'     : <greenlet>,
-                       'exception' : <exception object if applicable>}}
+          {'myhost1':
+                exit_code=exit code if ready else None
+                channel=SSH channel of command
+                stdout=<iterable>
+                stderr=<iterable>
+                cmd=<greenlet>
+                exception=<exception object if applicable>
+          }
         
         Stdout and stderr are also logged via the logger named ``host_logger``
         which can be enabled by calling ``enable_host_logger``
@@ -735,6 +744,7 @@ def _update_host_output(self, output, host, exit_code, channel, stdout,
                            "key for %s to %s", host, host, new_host)
             host = new_host
         output[host] = HostOutput(host, cmd, channel, stdout, stderr, stdin,
+                                  exit_code=exit_code,
                                   exception=exception)
 
     def join(self, output):
@@ -782,7 +792,7 @@ def get_exit_code(self, host_output):
 
     def _get_exit_code(self, channel):
         """Get exit code from channel if ready"""
-        if not channel or not channel.exit_status_ready():
+        if channel is None or not channel.exit_status_ready():
             return
         channel.close()
         return channel.recv_exit_status()