Updated ssh2 client sftp functions.

Updated travis, appveyor cfgs.
Updated readme.
Updated documentation.
Updated sftp tests.

Author: Pan

.appveyor.yml

@@ -76,16 +76,16 @@ install:
   # about it being out of date.
   - "pip install --disable-pip-version-check --user --upgrade pip"
 
+  - git submodule update --init --recursive
+  - "%CMD_IN_ENV% ci\\appveyor\\build_ssh2.bat"
   # Install the build dependencies of the project. If some dependencies contain
   # compiled extensions and are not provided as pre-built wheel packages,
   # pip will build them from source using the MSVC compiler matching the
   # target Python version and architecture
   - "%CMD_IN_ENV% pip install -r requirements.txt"
   - "%CMD_IN_ENV% pip install -U wheel setuptools twine"
-  - git submodule update --init --recursive
 
 build_script:
-  - "%CMD_IN_ENV% ci\\appveyor\\build_ssh2.bat"
   # Build the compiled extension
   - "%CMD_IN_ENV% python setup.py build_ext -i"
 

.travis.yml

@@ -22,7 +22,7 @@ before_install:
 install:
   - pip install -r requirements_dev.txt
 script:
-  - nosetests --with-coverage --cover-package=pssh tests/test_ssh2_client.py tests/test_pssh_ssh2_client.py
+  - nosetests --with-coverage --cover-package=pssh
   - flake8 pssh
   - cd doc; make html; cd ..
 after_success:

Changelog.rst

@@ -7,7 +7,7 @@ Change Log
 Changes
 ---------
 
-* New ``ssh2-python`` (``libssh2``) based clients
+* New ``ssh2-python`` (``libssh2``) native library based clients
 
 Fixes
 --------

README.rst

@@ -16,8 +16,8 @@ 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://coveralls.io/repos/ParallelSSH/parallel-ssh/badge.png?branch=master
-  :target: https://coveralls.io/r/ParallelSSH/parallel-ssh?branch=master
+.. 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
 .. image:: https://readthedocs.org/projects/parallel-ssh/badge/?version=latest
@@ -63,19 +63,21 @@ Run ``uname`` on two remote hosts in parallel with ``sudo``.
       Linux
       Linux
 
-*******************
-Native code client
-*******************
+**************
+Native client
+**************
 
-As of version ``1.2.0``, a new client is supported in ``ParallelSSH`` which offers much greater performance and reduced overhead than the current default client library. Binary wheel packages with ``libssh2`` included are provided for Linux, OSX and Windows platforms and all supported Python versions.
+Starting from version ``1.2.0``, a new client is supported in ``parallel-ssh`` which offers much greater performance and reduced overhead than the current default client.
 
-The new client is based on ``libssh2`` via the ``ssh2-python`` extension library and supports non-blocking mode natively. In addition, SFTP push/pull operations in the new client have also been implemented in native code, allowing for much greater performance and significantly reduced overhead.
+The new client is based on ``libssh2`` via the ``ssh2-python`` extension library and supports non-blocking mode natively. Binary wheel packages with ``libssh2`` included are provided for Linux, OSX and Windows platforms and all supported Python versions.
 
 See `this post <https://parallel-ssh.org/post/parallel-ssh-libssh2>`_ for a performance comparison of the available clients.
 
 To make use of this new client, ``ParallelSSHClient`` can be imported from ``pssh.pssh2_client`` instead. Their respective APIs are almost identical.
 
-Note that the new client will become the default and will replace the current ``pssh.pssh_client`` in a new major version of the library - ``2.x.x`` - once remaining features have been implemented. The current client will remain available as an option under a new name.
+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 current default client will remain available as an option under a new name.
 
 For example:
 
@@ -101,9 +103,8 @@ Native Code Client Features
 ****************************
 
 * Highest performance and least overhead of any Python SSH libraries
-* Thread safe - utilises both native threads for blocking calls like authentication and non-blocking I/O
+* Thread safe - makes use of native threads for blocking calls like authentication
 * Natively non-blocking utilising ``libssh2`` via ``ssh2-python`` - **no monkey patching of the Python standard library**
-* Native binary-like SFTP speeds thanks to SFTP and local file read/write native code implementations
 * Significantly reduced overhead in CPU and memory usage
 
 

doc/Changelog.rst

@@ -0,0 +1 @@
+../Changelog.rst

doc/advanced.rst

@@ -20,7 +20,7 @@ will disable this behaviour.
 Programmatic Private Keys
 --------------------------
 
-By default, ``ParallelSSH`` will use all keys in an available SSH agent and identity keys under the user's SSH directory - ``id_rsa`` and ``id_dsa`` in ``~/.ssh``.
+By default, ``parallel-ssh`` will use all keys in an available SSH agent and identity keys under the user's SSH directory - ``id_rsa``, ``id_dsa`` and ``identity`` in ``~/.ssh``.
 
 A private key can also be provided programmatically.
 
@@ -55,7 +55,7 @@ Use of an available SSH agent can also be disabled.
 
    If the number of hosts is large enough, available connections to the system SSH agent may be exhausted which will stop the client from working on a subset of hosts.
 
-   This is a limitation of the underlying SSH client used by ``ParallelSSH``.
+   This is a limitation of the underlying SSH client used by ``parallel-ssh``.
 
 Programmatic SSH Agent
 -----------------------
@@ -85,6 +85,32 @@ It is also possible to programmatically provide an SSH agent for the client to u
    :py:class:`pssh.agent.SSHAgent`
 
 
+Native clients
+*****************
+
+Starting from version ``1.2.0``, a new client is supported in ``parallel-ssh`` which offers much greater performance and reduced overhead than the current default client.
+
+The new client is based on ``libssh2`` via the ``ssh2-python`` extension library and supports non-blocking mode natively. Binary wheel packages with ``libssh2`` included are provided for Linux, OSX and Windows platforms and all supported Python versions.
+
+See `this post <https://parallel-ssh.org/post/parallel-ssh-libssh2>`_ for a performance comparison of the available clients.
+
+To make use of this new client, ``ParallelSSHClient`` can be imported from ``pssh.pssh2_client`` instead. Their respective APIs are almost identical. 
+
+.. code-block:: python
+
+  from pssh.pssh2_client import ParallelSSHClient
+
+  hosts = ['my_host', 'my_other_host']
+  client = ParallelSSHClient(hosts)
+  client.run_command(<..>)
+
+
+.. seealso::
+
+   `Feature comparison <ssh2.html>`_ for how the client features compare.
+
+   API documentation for `parallel <pssh2_client.html>`_ and `single <ssh2_client.html>`_ native clients.
+
 Tunneling
 **********
 
@@ -119,7 +145,7 @@ In the above example, connections to the target hosts are made via ``my_proxy_us
 
    Proxy host connections are asynchronous and use the SSH protocol's native TCP tunneling - aka local port forward. No external commands or processes are used for the proxy connection, unlike the `ProxyCommand` directive in OpenSSH and other utilities.
 
-   While connections initiated by ``ParallelSSH`` are asynchronous, connections from proxy host -> target hosts may not be, depending on SSH server implementation. If only one proxy host is used to connect to a large number of target hosts and proxy SSH server connections are *not* asynchronous, this may adversely impact performance on the proxy host.
+   While connections initiated by ``parallel-ssh`` are asynchronous, connections from proxy host -> target hosts may not be, depending on SSH server implementation. If only one proxy host is used to connect to a large number of target hosts and proxy SSH server connections are *not* asynchronous, this may adversely impact performance on the proxy host.
 
 Per-Host Configuration
 ***********************
@@ -205,7 +231,7 @@ See :py:func:`run_command API documentation <pssh.pssh_client.ParallelSSHClient.
 Run with sudo
 ---------------
 
-``ParallelSSH`` can be instructed to run its commands under ``sudo``:
+``parallel-ssh`` can be instructed to run its commands under ``sudo``:
 
 .. code-block:: python
 
@@ -248,7 +274,7 @@ Contents of ``stdout`` will be `UTF-16` encoded.
 Disabling use of pseudo terminal emulation
 --------------------------------------------
 
-By default, ``ParallelSSH`` uses the user's configured shell to run commands with. As a shell is used by default, a pseudo terminal (`PTY`) is also requested by default.
+By default, ``parallel-ssh`` uses the user's configured shell to run commands with. As a shell is used by default, a pseudo terminal (`PTY`) is also requested by default.
 
 For cases where use of a `PTY` is not wanted, such as having separate stdout and stderr outputs, the remote command is a daemon that needs to fork and detach itself or when use of a shell is explicitly disabled, use of PTY can also be disabled.
 
@@ -425,7 +451,7 @@ Hosts list can be modified in place. A call to ``run_command`` will create new c
 Additional options for underlying SSH libraries
 ************************************************
 
-Not all SSH library configuration options are used directly by ``Parallel-SSH``.
+Not all SSH library configuration options are used directly by ``parallel-ssh``.
 
 Additional options can be passed on to the underlying SSH libraries used via an optional keyword argument.
 

doc/index.rst

@@ -1,8 +1,3 @@
-.. Parallel-SSH documentation master file, created by
-   sphinx-quickstart on Mon Mar 10 17:08:38 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 ===========================
 Parallel-SSH Documentation
 ===========================
@@ -15,16 +10,17 @@ 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://coveralls.io/repos/ParallelSSH/parallel-ssh/badge.png?branch=master
-  :target: https://coveralls.io/r/ParallelSSH/parallel-ssh?branch=master
+.. 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
 .. 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.
 
-``parallel-ssh`` is a parallel SSH client library.
-
-It uses asynchronous non-blocking SSH connections 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 for Python, as well as the only non-blocking *parallel* SSH client library available for Python.
 
 .. toctree::
    :maxdepth: 2
@@ -34,6 +30,7 @@ It uses asynchronous non-blocking SSH connections and is, to date, the only publ
    quickstart
    ssh2
    advanced
+   Changelog
    api
 
 In a nutshell

doc/installation.rst

@@ -43,7 +43,6 @@ To install from source run:
 
 .. code-block:: shell
 
-  pip install -r requirements.txt
   python setup.py install
 
 Or with `pip`'s development mode which will ensure local changes are made available:

doc/introduction.rst

@@ -2,7 +2,7 @@
 Design And Goals
 *****************
 
-``Parallel-SSH``'s design goals and motivation are to provide a *library* for running *asynchronous* SSH commands in parallel with little to no load induced on the system by doing so with the intended usage being completely programmatic and non-interactive.
+``parallel-ssh``'s design goals and motivation are to provide a *library* for running *asynchronous* SSH commands in parallel with little to no load induced on the system by doing so with the intended usage being completely programmatic and non-interactive.
 
 To meet these goals, API driven solutions are preferred first and foremost. This frees up the developer to drive the library via any method desired, be that environment variables, CI driven tasks, command line tools, existing OpenSSH or new configuration files, from within an application et al.
 

doc/quickstart.rst

@@ -2,16 +2,20 @@
 Quickstart
 ***********
 
-First, make sure that ``parallel-ssh`` is `installed <installation>`_.
+First, make sure that ``parallel-ssh`` is `installed <installation.html>`_.
 
 .. note::
 
-   ParallelSSH uses gevent's monkey patching to enable asynchronous use of the Python standard library's network I/O.
+   ``parallel-ssh`` uses gevent's monkey patching to enable asynchronous use of the Python standard library's network I/O.
 
    Make sure that ParallelSSH imports come **before** any other imports in your code. Otherwise, patching may not be done before the standard library is loaded which will then cause ParallelSSH to block.
 
    If you are seeing messages like ``This operation would block forever``, this is the cause.
 
+   Monkey patching is only done for the clients under ``pssh.pssh_client`` and ``pssh.ssh_client`` for parallel and single host clients respectively.
+
+   New native library based clients under ``pssh.pssh2_client`` and ``pssh.ssh2_client`` **do not perform monkey patching** and are an option if monkey patching is not suitable. These clients are currently in beta and will become the default in a future major release - ``2.0.0``.
+
 Run a command on hosts in parallel
 ------------------------------------
 
@@ -207,4 +211,4 @@ With this flag, the ``exception`` attribute will contain the exception on any fa
 
 .. seealso::
 
-   Possible exceptions can be found in :mod:`pssh.exceptions` module.
+   Exceptions raised by the library can be found in :mod:`pssh.exceptions` module.