Updated exception names, added tests. Updated changelog. (#233)

* Updated exception names, added tests.
* Removed top level pssh module exception imports. 
* Updated documentation. 
* Updated exception handling for renamed exceptions - backwards compatible.
* Updated init.
* Updated changelog.

Author: pkittenis

Changelog.rst

@@ -28,6 +28,8 @@ See `Upgrading to API 2.0 <https://parallel-ssh.readthedocs.io/en/latest/api_upg
 * Renamed ``run_command`` ``timeout`` to ``read_timeout=<seconds>)`` for setting output read timeout individually - defaults to global timeout setting.
 * Removed ``pssh.native`` package and native code.
 * ``ParallelSSHClient.scp_send`` now supports ``copy_args`` keyword argument for providing per-host file name arguments like rest of ``scp_*`` and ``copy_*`` functionality.
+* Changed exception names to end in ``Error`` from ``Exception`` - backwards compatible.
+* ``UnknownHostException``, ``AuthenticationException``, ``ConnectionErrorException``, ``SSHException`` no longer available as imports ``from pssh`` - use ``from pssh.exceptions``.
 
 
 Fixes

doc/installation.rst

@@ -17,18 +17,20 @@ Pip Install
 
 If ``pip`` is not available on your Python platform, `see this installation guide <http://docs.python-guide.org/en/latest/starting/installation/>`_.
 
-Dependencies
---------------
+From Source Dependencies
+-------------------------
 
-When installing from source, dependencies must be satisfied by ``pip install -r requirements.txt``. For pre-built binary wheel packages with dependencies included, see `Pip Install`_.
+When installing from source, dependencies must be satisfied by ``pip install -r requirements.txt`` or by system packages.
 
-===============    ================
+For binary packages, see `Pip Install`_.
+
+===============    =====================
 Dependency         Minimum Version
-===============    ================
-``ssh2-python``    ``0.19.0``
-``ssh-python``     ``0.6.0``
-``gevent``         ``1.1``
-===============    ================
+===============    =====================
+``ssh2-python``    per requirements.txt
+``ssh-python``     per requirements.txt
+``gevent``         per requirements.txt
+===============    =====================
 
 
 Building from Source
@@ -54,54 +56,3 @@ Or for developing changes:
 
   pip install -r requirements_dev.txt
 
-Building System Packages
---------------------------
-
-For convenience, a script making use of Docker is provided at `ci/docker/build-packages.sh <https://github.com/ParallelSSH/parallel-ssh/blob/master/ci/docker/build-packages.sh>`_ that will build system packages for Centos/RedHat 6/7, Ubuntu 14.04/16.04, Debian 7/8 and Fedora 22/23/24.
-
-This script and docker files can be adapted for other distributions.
-
-Note that these packages make use of system libraries that may need to be updated to be compatible with ``parallel-ssh`` - see `Dependencies`_.
-
-.. code-block:: shell
-
-   git clone [email protected]:ParallelSSH/parallel-ssh.git
-   cd parallel-ssh
-   # Checkout a tag for tagged builds - git tag; git checkout <tag>
-   ./ci/docker/build-packages.sh
-   ls -1tr
-
-.. code-block:: shell
-
-   python-parallel-ssh-1.2.0+4.ga811e69.dirty-1.el6.x86_64.rpm
-   python-parallel-ssh-1.2.0+4.ga811e69.dirty-1.el7.x86_64.rpm
-   python-parallel-ssh-1.2.0+4.ga811e69.dirty-1.fc22.x86_64.rpm
-   python-parallel-ssh-1.2.0+4.ga811e69.dirty-1.fc23.x86_64.rpm
-   python-parallel-ssh-1.2.0+4.ga811e69.dirty-1.fc24.x86_64.rpm
-   python-parallel-ssh_1.2.0+4.ga811e69.dirty-debian7_amd64.deb
-   python-parallel-ssh_1.2.0+4.ga811e69.dirty-debian8_amd64.deb
-
-Specific System Package Build
-_______________________________
-
-To build for only a specific system/distribution, run the two following commands, substituting distribution with the desired one from `ci/docker <https://github.com/ParallelSSH/parallel-ssh/blob/master/ci/docker>`_. See `existing Dockerfiles <https://github.com/ParallelSSH/parallel-ssh/tree/master/ci/docker/ubuntu16.04/Dockerfile>`_ for examples on how to create system packages for other distributions.
-
-Debian based
-+++++++++++++
-
-.. code-block:: shell
-
-   docker build --cache-from parallelssh/parallel-ssh-pkgs:debian7 ci/docker/debian7 -t debian7
-   docker run -v "$(pwd):/src/" debian7 --iteration debian7 -s python -t deb setup.py
-
-
-RPM based
-++++++++++
-
-.. code-block:: shell
-
-   docker build --cache-from parallelssh/parallel-ssh-pkgs:centos7 ci/docker/centos7 -t centos7
-   docker run -v "$(pwd):/src/" centos7 --rpm-dist el7 -s python -t rpm setup.py
-
-
-See `fpm <http://fpm.readthedocs.io/en/latest/>`_ for making system packages of various types.

doc/quickstart.rst

@@ -333,7 +333,7 @@ With this flag, the ``exception`` output attribute will contain the exception on
    .. code-block:: python
 
       host1: 0, None
-      host2: None, AuthenticationException <..>
+      host2: None, AuthenticationError <..>
 
 .. seealso::
 

pssh/__init__.py

@@ -1,16 +1,16 @@
 # This file is part of parallel-ssh.
-
+#
 # Copyright (C) 2014-2020 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
@@ -20,25 +20,20 @@
 Run SSH commands over many - hundreds/hundreds of thousands - number of servers
 asynchronously and with minimal system load on the client host.
 
-New users should start with
-:py:func:`pssh.clients.ParallelSSHClient.run_command`
+New users should start with `pssh.clients.ParallelSSHClient.run_command` and
+`pssh.clients.SSHClient.run_command`
 
-See also :py:class:`pssh.ParallelSSHClient` and :py:class:mod:`pssh.SSHClient`
+See also `pssh.clients.ParallelSSHClient` and pssh.clients.SSHClient`
 for class documentation.
 """
 
-# flake8: noqa: E402, F401, F402
 
-import logging
+from logging import getLogger, NullHandler
 from ._version import get_versions
 __version__ = get_versions()['version']
 del get_versions
-from .exceptions import UnknownHostException, \
-    AuthenticationException, ConnectionErrorException, SSHException
-
 
-host_logger = logging.getLogger('pssh.host_logger')
-logger = logging.getLogger('pssh')
-if hasattr(logging, 'NullHandler'):
-    host_logger.addHandler(logging.NullHandler())
-    logger.addHandler(logging.NullHandler())
+host_logger = getLogger('pssh.host_logger')
+logger = getLogger('pssh')
+host_logger.addHandler(NullHandler())
+logger.addHandler(NullHandler())

pssh/clients/base/parallel.py

@@ -25,7 +25,7 @@
 from gevent.hub import Hub
 
 from ...constants import DEFAULT_RETRIES, RETRY_DELAY
-from ...exceptions import HostArgumentException, Timeout
+from ...exceptions import HostArgumentError, Timeout
 from ...output import HostOutput
 
 
@@ -92,7 +92,7 @@ def run_command(self, command, user=None, stop_on_errors=True,
                     *args, **kwargs)
                         for host_i, host in enumerate(self.hosts)]
             except IndexError:
-                raise HostArgumentException(
+                raise HostArgumentError(
                     "Number of host arguments provided does not match "
                     "number of hosts ")
         else:
@@ -328,15 +328,15 @@ def copy_file(self, local_file, remote_file, recurse=False, copy_args=None):
         :param copy_args: (Optional) format local_file and remote_file strings
           with per-host arguments in ``copy_args``. ``copy_args`` length must
           equal length of host list -
-          :py:class:`pssh.exceptions.HostArgumentException` is raised otherwise
+          :py:class:`pssh.exceptions.HostArgumentError` is raised otherwise
         :type copy_args: tuple or list
 
         :rtype: List(:py:class:`gevent.Greenlet`) of greenlets for remote copy
           commands
 
         :raises: :py:class:`ValueError` when a directory is supplied to
           local_file and recurse is not set
-        :raises: :py:class:`pssh.exceptions.HostArgumentException` on number of
+        :raises: :py:class:`pssh.exceptions.HostArgumentError` on number of
           per-host copy arguments not equal to number of hosts
         :raises: :py:class:`IOError` on I/O errors writing files
         :raises: :py:class:`OSError` on OS errors like permission denied
@@ -355,7 +355,7 @@ def copy_file(self, local_file, remote_file, recurse=False, copy_args=None):
                                         {'recurse': recurse})
                         for host_i, host in enumerate(self.hosts)]
             except IndexError:
-                raise HostArgumentException(
+                raise HostArgumentError(
                     "Number of per-host copy arguments provided does not match "
                     "number of hosts")
         else:
@@ -412,13 +412,13 @@ def copy_remote_file(self, remote_file, local_file, recurse=False,
         :param copy_args: (Optional) Format remote_file and local_file strings
           with per-host arguments in ``copy_args``. ``copy_args`` length must
           equal length of host list -
-          :py:class:`pssh.exceptions.HostArgumentException` is raised otherwise
+          :py:class:`pssh.exceptions.HostArgumentError` is raised otherwise
         :type copy_args: tuple or list
         :rtype: list(:py:class:`gevent.Greenlet`) of greenlets for remote copy
           commands
         :raises: :py:class:`ValueError` when a directory is supplied to
           local_file and recurse is not set
-        :raises: :py:class:`pssh.exceptions.HostArgumentException` on number of
+        :raises: :py:class:`pssh.exceptions.HostArgumentError` on number of
           per-host copy arguments not equal to number of hosts
         :raises: :py:class:`IOError` on I/O errors writing files
         :raises: :py:class:`OSError` on OS errors like permission denied
@@ -440,7 +440,7 @@ def copy_remote_file(self, remote_file, local_file, recurse=False,
                     local_file % copy_args[host_i], recurse=recurse, **kwargs)
                     for host_i, host in enumerate(self.hosts)]
             except IndexError:
-                raise HostArgumentException(
+                raise HostArgumentError(
                     "Number of per-host copy arguments provided does not match "
                     "number of hosts")
         else:

pssh/clients/base/single.py

@@ -31,8 +31,8 @@
 
 from ..common import _validate_pkey_path
 from ...constants import DEFAULT_RETRIES, RETRY_DELAY
-from ...exceptions import UnknownHostException, AuthenticationException, \
-    ConnectionErrorException
+from ...exceptions import UnknownHostError, AuthenticationError, \
+    ConnectionError
 from ...output import HostOutput
 
 
@@ -98,7 +98,7 @@ def _auth_retry(self, retries=1):
                 sleep(self.retry_delay)
                 return self._auth_retry(retries=retries+1)
             msg = "Authentication error while connecting to %s:%s - %s"
-            raise AuthenticationException(msg, self.host, self.port, ex)
+            raise AuthenticationError(msg, self.host, self.port, ex)
 
     def disconnect(self):
         raise NotImplementedError
@@ -143,9 +143,9 @@ def _connect(self, host, port, retries=1):
             if retries < self.num_retries:
                 sleep(self.retry_delay)
                 return self._connect(host, port, retries=retries+1)
-            ex = UnknownHostException("Unknown host %s - %s - retry %s/%s",
-                                      host, str(ex.args[1]), retries,
-                                      self.num_retries)
+            ex = UnknownHostError("Unknown host %s - %s - retry %s/%s",
+                                  host, str(ex.args[1]), retries,
+                                  self.num_retries)
             ex.host = host
             ex.port = port
             raise ex
@@ -156,7 +156,7 @@ def _connect(self, host, port, retries=1):
                 sleep(self.retry_delay)
                 return self._connect(host, port, retries=retries+1)
             error_type = ex.args[1] if len(ex.args) > 1 else ex.args[0]
-            ex = ConnectionErrorException(
+            ex = ConnectionError(
                 "Error connecting to host '%s:%s' - %s - retry %s/%s",
                 host, port, str(error_type), retries,
                 self.num_retries,)
@@ -182,7 +182,7 @@ def _identity_auth(self):
                 logger.debug("Authentication succeeded with identity file %s",
                              identity_file)
                 return
-        raise AuthenticationException("No authentication methods succeeded")
+        raise AuthenticationError("No authentication methods succeeded")
 
     def _init_session(self, retries=1):
         raise NotImplementedError

pssh/clients/native/parallel.py

@@ -25,7 +25,7 @@
 from ..common import _validate_pkey_path
 from ..base.parallel import BaseParallelSSHClient
 from ...constants import DEFAULT_RETRIES, RETRY_DELAY
-from ...exceptions import ProxyError, Timeout, HostArgumentException
+from ...exceptions import ProxyError, Timeout, HostArgumentError
 
 
 logger = logging.getLogger(__name__)
@@ -181,7 +181,7 @@ def run_command(self, command, sudo=False, user=None, stop_on_errors=True,
         :type use_pty: bool
         :param host_args: (Optional) Format command string with per-host
           arguments in ``host_args``. ``host_args`` length must equal length of
-          host list - :py:class:`pssh.exceptions.HostArgumentException` is
+          host list - :py:class:`pssh.exceptions.HostArgumentError` is
           raised otherwise
         :type host_args: tuple or list
         :param encoding: Encoding to use for output. Must be valid
@@ -204,13 +204,13 @@ def run_command(self, command, sudo=False, user=None, stop_on_errors=True,
           :py:class:`pssh.output.HostOutput` as value
           *or* list(:py:class:`pssh.output.HostOutput`) when
           ``return_list=True``
-        :raises: :py:class:`pssh.exceptions.AuthenticationException` on
+        :raises: :py:class:`pssh.exceptions.AuthenticationError` on
           authentication error
-        :raises: :py:class:`pssh.exceptions.UnknownHostException` on DNS
+        :raises: :py:class:`pssh.exceptions.UnknownHostError` on DNS
           resolution error
-        :raises: :py:class:`pssh.exceptions.ConnectionErrorException` on error
+        :raises: :py:class:`pssh.exceptions.ConnectionError` on error
           connecting
-        :raises: :py:class:`pssh.exceptions.HostArgumentException` on number of
+        :raises: :py:class:`pssh.exceptions.HostArgumentError` on number of
           host arguments not equal to number of hosts
         :raises: :py:class:`TypeError` on not enough host arguments for cmd
           string format
@@ -328,15 +328,15 @@ def copy_file(self, local_file, remote_file, recurse=False, copy_args=None):
         :param copy_args: (Optional) format local_file and remote_file strings
           with per-host arguments in ``copy_args``. ``copy_args`` length must
           equal length of host list -
-          :py:class:`pssh.exceptions.HostArgumentException` is raised otherwise
+          :py:class:`pssh.exceptions.HostArgumentError` is raised otherwise
         :type copy_args: tuple or list
 
         :rtype: list(:py:class:`gevent.Greenlet`) of greenlets for remote copy
           commands
 
         :raises: :py:class:`ValueError` when a directory is supplied to
           local_file and recurse is not set
-        :raises: :py:class:`pssh.exceptions.HostArgumentException` on number of
+        :raises: :py:class:`pssh.exceptions.HostArgumentError` on number of
           per-host copy arguments not equal to number of hosts
         :raises: :py:class:`pss.exceptions.SFTPError` on SFTP initialisation
           errors
@@ -393,7 +393,7 @@ def copy_remote_file(self, remote_file, local_file, recurse=False,
         :param copy_args: (Optional) format remote_file and local_file strings
           with per-host arguments in ``copy_args``.   ``copy_args`` length must
           equal length of host list -
-          :py:class:`pssh.exceptions.HostArgumentException` is raised otherwise
+          :py:class:`pssh.exceptions.HostArgumentError` is raised otherwise
         :type copy_args: tuple or list
         :param encoding: Encoding to use for file paths.
         :type encoding: str
@@ -403,7 +403,7 @@ def copy_remote_file(self, remote_file, local_file, recurse=False,
 
         :raises: :py:class:`ValueError` when a directory is supplied to
           local_file and recurse is not set
-        :raises: :py:class:`pssh.exceptions.HostArgumentException` on number of
+        :raises: :py:class:`pssh.exceptions.HostArgumentError` on number of
           per-host copy arguments not equal to number of hosts
         :raises: :py:class:`pss.exceptions.SFTPError` on SFTP initialisation
           errors
@@ -482,7 +482,7 @@ def scp_send(self, local_file, remote_file, recurse=False, copy_args=None):
                                     recurse=recurse)
                     for host_i, host in enumerate(self.hosts)]
         except IndexError:
-            raise HostArgumentException(
+            raise HostArgumentError(
                 "Number of per-host copy arguments provided does not match "
                 "number of hosts")
 
@@ -528,15 +528,15 @@ def scp_recv(self, remote_file, local_file, recurse=False, copy_args=None,
         :param copy_args: (Optional) format remote_file and local_file strings
           with per-host arguments in ``copy_args``. ``copy_args`` length *must*
           equal length of host list -
-          :py:class:`pssh.exceptions.HostArgumentException` is raised otherwise
+          :py:class:`pssh.exceptions.HostArgumentError` is raised otherwise
         :type copy_args: tuple or list
 
         :rtype: list(:py:class:`gevent.Greenlet`) of greenlets for remote copy
           commands.
 
         :raises: :py:class:`ValueError` when a directory is supplied to
           local_file and recurse is not set.
-        :raises: :py:class:`pssh.exceptions.HostArgumentException` on number of
+        :raises: :py:class:`pssh.exceptions.HostArgumentError` on number of
           per-host copy arguments not equal to number of hosts.
         :raises: :py:class:`pss.exceptions.SCPError` on errors copying file.
         :raises: :py:class:`OSError` on local OS errors like permission denied.
@@ -563,6 +563,6 @@ def scp_recv(self, remote_file, local_file, recurse=False, copy_args=None,
                 local_file % copy_args[host_i], recurse=recurse)
                     for host_i, host in enumerate(self.hosts)]
         except IndexError:
-            raise HostArgumentException(
+            raise HostArgumentError(
                 "Number of per-host copy arguments provided does not match "
                 "number of hosts")