Updated readme, documentation, requirements.

Author: Pan

README.rst

@@ -16,10 +16,12 @@ Native code based client with extremely high performance - based on ``libssh2``
   :alt: Latest Version
 .. image:: https://travis-ci.org/ParallelSSH/parallel-ssh.svg?branch=master
   :target: https://travis-ci.org/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
 .. 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
-   :target: https://pypi.python.org/pypi/parallel-ssh
+  :target: https://pypi.python.org/pypi/parallel-ssh
 .. image:: https://readthedocs.org/projects/parallel-ssh/badge/?version=latest
   :target: http://parallel-ssh.readthedocs.org/en/latest/
   :alt: Latest documentation
@@ -46,6 +48,8 @@ Run ``uname`` on two remote hosts in parallel with ``sudo``.
 
 .. code-block:: python
 
+  from __future__ import print_function
+
   from pssh.pssh_client import ParallelSSHClient
 
   hosts = ['myhost1', 'myhost2']
@@ -75,7 +79,7 @@ See `this post <https://parallel-ssh.org/post/parallel-ssh-libssh2>`_ for a perf
 
 To make use of this new client, ``ParallelSSHClient`` can be imported from ``pssh.pssh2_client`` instead. Their respective APIs are almost identical.
 
-The new client will become the default and will replace the current ``pssh.pssh_client`` in a new major version of the library - ``2.0.0`` - once remaining features have been implemented. The native client should be considered as *beta* status until the ``2.0.0`` release when it is made the default.
+The new client will become the default and will replace the current ``pssh.pssh_client`` in a new major version of the library - ``2.0.0`` - once remaining features have been implemented.
 
 The current default client will remain available as an option under a new name.
 
@@ -126,7 +130,7 @@ Once either standard output is iterated on *to completion*, or ``client.join(out
       0
 
 
-The client's ``join`` function can be used to block and wait for all parallel commands to finish:
+The client's ``join`` function can be used to wait for all commands in output object to finish:
 
 .. code-block:: python
 
@@ -136,6 +140,8 @@ Similarly, output and exit codes are available after ``client.join`` is called:
 
 .. code-block:: python
 
+  from pprint import pprint
+
   output = client.run_command('exit 0')
 
   # Wait for commands to complete and gather exit codes. 
@@ -157,11 +163,12 @@ Similarly, output and exit codes are available after ``client.join`` is called:
 
 There is also a built in host logger that can be enabled to log output from remote hosts. The helper function ``pssh.utils.enable_host_logger`` will enable host logging to stdout.
 
-To log output without having to iterate over output generators, the ``consume_output`` flag can be enabled - for example:
+To log output without having to iterate over output generators, the ``consume_output`` flag *must* be enabled - for example:
 
 .. code-block:: python
 
   from pssh.utils import enable_host_logger
+
   enable_host_logger()
   client.join(client.run_command('uname'), consume_output=True)
 
@@ -171,20 +178,20 @@ To log output without having to iterate over output generators, the ``consume_ou
       [localhost]	Linux
 
 
-SFTP/SCP
-********
+SFTP
+******
 
-SFTP is supported natively, no ``scp`` binary required.
+SFTP is supported natively.
 
-For example to copy a local file to remote hosts in parallel:
+To copy a local file to remote hosts in parallel:
 
 .. code-block:: python
 
   from pssh.pssh_client import ParallelSSHClient
-  from pssh import utils
+  from pssh.utils import enable_logger, logger
   from gevent import joinall
 
-  utils.enable_logger(utils.logger)
+  enable_logger(logger)
   hosts = ['myhost1', 'myhost2']
   client = ParallelSSHClient(hosts)
   cmds = client.copy_file('../test', 'test_dir/test')
@@ -238,7 +245,7 @@ Output *generation* is done remotely and has no effect on the event loop until o
 User's group
 *************
 
-here is a public `ParallelSSH Google group <https://groups.google.com/forum/#!forum/parallelssh>`_ setup for this purpose - both posting and viewing are open to the public.
+There is a public `ParallelSSH Google group <https://groups.google.com/forum/#!forum/parallelssh>`_ setup for this purpose - both posting and viewing are open to the public.
 
 .. image:: https://ga-beacon.appspot.com/UA-9132694-7/parallel-ssh/README.rst?pixel
   :target: https://github.com/igrigorik/ga-beacon

ci/docker/build-packages.sh

@@ -12,8 +12,8 @@ for x in `ls -1d ci/docker/{fedora,centos}*`; do
     docker pull $docker_tag || echo
     docker build --cache-from $docker_tag $x -t $name
     docker tag $name $docker_tag
-    docker push $docker_tag
-    sudo rm -rf build dist
+    # docker push $docker_tag
+    # sudo rm -rf build dist
     docker run -v "$(pwd):/src/" "$name" --rpm-dist $dist -s python -t rpm setup.py
 done
 
@@ -23,12 +23,12 @@ for x in `ls -1d ci/docker/{debian,ubuntu}*`; do
     docker pull $docker_tag || echo
     docker build --cache-from $docker_tag $x -t $name
     docker tag $name $docker_tag
-    docker push $docker_tag
-    sudo rm -rf build dist
+    # docker push $docker_tag
+    # sudo rm -rf build dist
     docker run -v "$(pwd):/src/" "$name" --iteration $name -s python -t deb setup.py
 done
 
-sudo chown -R ${USER} *
+# sudo chown -R ${USER} *
 
 ls -ltrh *.{rpm,deb}
 

ci/docker/debian7/Dockerfile

@@ -2,5 +2,6 @@ FROM cdrx/fpm-debian:7
 
 RUN apt-get -y update
 RUN apt-get -y install python-setuptools python-dev libssh2-1-dev python-pip git
+RUN pip install -U pip -i https://pypi.python.org/simple/
 RUN pip install -U setuptools
-RUN pip install -U pip wheel
+RUN pip install -U wheel

doc/index.rst

@@ -10,17 +10,19 @@ Parallel-SSH Documentation
   :alt: Latest Version
 .. image:: https://travis-ci.org/ParallelSSH/parallel-ssh.svg?branch=master
   :target: https://travis-ci.org/ParallelSSH/parallel-ssh
+.. image:: https://ci.appveyor.com/api/projects/status/github/parallelssh/ssh2-python?svg=true&branch=master
+  :target: https://ci.appveyor.com/project/pkittenis/ssh2-python
 .. 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
-   :target: https://pypi.python.org/pypi/parallel-ssh
+  :target: https://pypi.python.org/pypi/parallel-ssh
 .. image:: https://readthedocs.org/projects/parallel-ssh/badge/?version=latest
   :target: http://parallel-ssh.readthedocs.org/en/latest/
   :alt: Latest documentation
 
 ``parallel-ssh`` is a non-blocking parallel SSH client library.
 
-It uses non-blocking asynchronous SSH sessions and is, to date, the only publicly available non-blocking SSH client library for Python, as well as the only non-blocking *parallel* SSH client library available for Python.
+It uses non-blocking asynchronous SSH sessions and is to date the only publicly available non-blocking SSH client library, as well as the only non-blocking *parallel* SSH client library available for Python.
 
 .. toctree::
    :maxdepth: 2
@@ -79,7 +81,6 @@ The API is mostly identical to the current clients, though some features are not
    From version ``2.x.x`` onwards, the ``ssh2-python`` based clients will *become the default*, replacing the current ``pssh_client.ParallelSSHClient``, with the current clients renamed.
 
 
-
 Indices and tables
 ==================
 

doc/installation.rst

@@ -7,9 +7,13 @@ Installation is handled by Python's standard ``setuptools`` library and ``pip``.
 Pip Install
 ------------
 
-::
+``pip`` may need to be updated to be able to install binary wheel packages.
 
-  pip install parallel-ssh
+.. code-block:: shell
+
+   pip install -U pip
+
+   pip install parallel-ssh
 
 If ``pip`` is not available on your Python platform, `see this installation guide <http://docs.python-guide.org/en/latest/starting/installation/>`_.
 
@@ -22,31 +26,94 @@ If you are running a deprecated Python version such as ``2.6`` you may need to i
 
 For example, to install the ``1.0.0`` version, run the following.
 
-.. code-block:: python
+.. code-block:: shell
 
   pip install parallel-ssh==1.0.0
 
 ``1.0.0`` is compatible with all Python versions over or equal to ``2.6``, including all of the ``3.x`` series.
 
 Older versions such as `0.70.x` are compatible with Python ``2.5`` and ``2.x`` but not the ``3.x`` series.
 
-Source Code
--------------
+Dependencies
+--------------
+
+When installing from source, it is responsibility of user to satisfy dependencies. For pre-built binary wheel packages with dependencies included, see `Pip Install`_.
+
+============ ================
+Dependency   Minimum Version
+============ ================
+``libssh2``      ``1.6``
+``gevent``       ``1.1``
+``paramiko``     ``1.15.3``
+============ ================
+
+
+Building from Source
+----------------------
 
-Parallel-SSH is hosted on GitHub and the repository can be cloned with the following
+
+``parallel-ssh`` is hosted on GitHub and the repository can be cloned with the following
 
 .. code-block:: shell
 
   git clone [email protected]:ParallelSSH/parallel-ssh.git
+  cd parallel-ssh
 
 To install from source run:
 
 .. code-block:: shell
 
   python setup.py install
 
-Or with `pip`'s development mode which will ensure local changes are made available:
+Or with ``pip``'s development mode which will ensure local changes are made available:
 
 .. code-block:: shell
 
   pip install -e .
+
+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.
+
+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/ssh2-python: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/ssh2-python:centos7 ci/docker/centos7 -t centos7
+   docker run -v "$(pwd):/src/" centos7 --rpm-dist el7 -s python -t rpm setup.py

doc/quickstart.rst

@@ -129,11 +129,25 @@ User/password authentication can be used by providing user name and password cre
 Programmatic Private Key authentication
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-It is also possible to programmatically use a private key for authentication. 
+It is also possible to programmatically use a private key for authentication.
 
-The helper function :py:func:`load_private_key <pssh.utils.load_private_key>` is provided to easily load all possible key types. It takes either a file path or a file-like object.
+Native Client
+______________
 
-:File path:
+For the native client (``pssh.pssh2_client``), only private key filepath is needed. The corresponding public key *must* be available in the same directory as ``my_pkey.pub`` where private key file is ``my_pkey``. Public key file name and path will be made configurable in a future version.
+
+ .. code-block:: python
+
+   from pssh.pssh2_client import ParallelSSHClient
+
+   client = ParallelSSHClient(hosts, pkey='my_pkey')
+
+Paramiko Client
+__________________
+
+For the paramiko based client, the helper function :py:func:`load_private_key <pssh.utils.load_private_key>` is provided to easily load all possible key types. It takes either a file path or a file-like object.
+
+ :File path:
    .. code-block:: python
 
       from pssh.pssh_client import ParallelSSHClient
@@ -142,6 +156,10 @@ The helper function :py:func:`load_private_key <pssh.utils.load_private_key>` is
       pkey = load_private_key('my_pkey.pem')
       client = ParallelSSHClient(hosts, pkey=pkey)
 
+.. note::
+
+   The two available clients support different key types and authentication mechanisms - see Paramiko and libssh2 documentation for details, as well as `clients features comparison <ssh2.html>`_.
+
 Output for Last Executed Commands
 -----------------------------------
 

requirements.txt

@@ -1,3 +1,3 @@
 paramiko>=1.15.3,<2.2
-gevent
+gevent>=1.1
 ssh2-python>=0.6.0