Skip to content

Commit 6569221

Browse files
author
Pan
committed
Updated documentation and in code doc strings
1 parent cc1f0a6 commit 6569221

File tree

12 files changed

+86
-553
lines changed

12 files changed

+86
-553
lines changed

‎doc/advanced.rst‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,7 @@
1-
.. contents::
2-
3-
41
Advanced Usage
52
=================
63

7-
There are several more advanced use cases of `ParallelSSH`, such as tunneling (aka proxying) via an intermediate SSH server and per-host configuration and command substitution among others.
4+
There are several more advanced usage features of ``parallel-ssh``, such as tunnelling (aka proxying) via an intermediate SSH server and per-host configuration and command substitution among others.
85

96
Agents and Private Keys
107
*************************

‎doc/api.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ API Documentation
66

77
pssh_client
88
ssh_client
9+
pssh2_client
10+
ssh2_client
911
output
1012
agent
1113
utils

‎doc/index.rst‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,26 +22,29 @@ Parallel-SSH Documentation
2222
:alt: Latest documentation
2323

2424

25-
``Parallel-SSH`` is a parallel SSH client library. It uses asynchronous SSH connections and is, to date, the only publicly available asynchronous SSH client library for Python, as well as the only asynchronous *parallel* SSH client library available for Python.
25+
``parallel-ssh`` is a parallel SSH client library.
26+
27+
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.
2628

2729
.. toctree::
2830
:maxdepth: 2
2931

3032
introduction
3133
installation
3234
quickstart
35+
ssh2
3336
advanced
3437
api
3538

3639
In a nutshell
3740
**************
3841

3942
.. code-block:: python
40-
43+
4144
from __future__ import print_function
42-
45+
4346
from pssh.pssh_client import ParallelSSHClient
44-
47+
4548
client = ParallelSSHClient(['localhost'])
4649
output = client.run_command('whoami')
4750
for line in output['localhost'].stdout:
@@ -52,6 +55,34 @@ In a nutshell
5255
5356
<your username here>
5457
58+
`ssh2-python` (`libssh2`) based clients
59+
******************************************
60+
61+
As of version ``1.2.0``, new single host and parallel clients are available based on the ``libssh2`` C library via its ``ssh2-python`` wrapper.
62+
63+
They offer significantly enhanced performance and stability, at much less overhead, with a native non-blocking mode meaning *no monkey patching of the Python standard library* when using the new clients.
64+
65+
To use them, import from ``pssh2_client`` or ``ssh2_client`` for the parallel and single clients respectively.
66+
67+
.. code-block:: python
68+
69+
from __future__ import print_function
70+
71+
from pssh.pssh2_client import ParallelSSHClient
72+
73+
client = ParallelSSHClient(['localhost'])
74+
output = client.run_command('whoami')
75+
for line in output['localhost'].stdout:
76+
print(line)
77+
78+
The API is mostly identical to the current clients, though some features are not yet supported. See `client feature comparison <ssh2.html>`_ section for how feature support differs between the two clients.
79+
80+
.. note::
81+
82+
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.
83+
84+
85+
5586
Indices and tables
5687
==================
5788

‎doc/installation.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ To install from source run:
4343

4444
.. code-block:: shell
4545
46+
pip install -r requirements.txt
4647
python setup.py install
4748
4849
Or with `pip`'s development mode which will ensure local changes are made available:

‎doc/pssh2_client.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
ParallelSSH2Client
2+
===================
3+
4+
API documentation for the `ssh2-python` (`libssh2`) based parallel client.
5+
6+
.. automodule:: pssh.pssh2_client
7+
:member-order: groupwise

‎doc/quickstart.rst‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
.. contents::
2-
31
***********
42
Quickstart
53
***********
@@ -69,7 +67,7 @@ There is nothing special needed to ensure output is available.
6967

7068
Please note that retrieving all of a command's standard output by definition requires that the command has completed.
7169

72-
Iterating over ``stdout`` for any host *to completion* will therefor *block* until that host's command has completed unless interrupted.
70+
Iterating over ``stdout`` for any host *to completion* will therefor *only complete* when that host's command has completed unless interrupted.
7371

7472
``stdout`` is a generator. Iterating over it will consume the remote standard output stream via the network as it becomes available. To retrieve all of stdout can wrap it with list, per below.
7573

‎doc/ssh2.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Clients Feature Comparison
2+
============================
3+
4+
For the ``ssh2-python`` (``libssh2``) based clients, not all features supported by the paramiko based clients are currently supported by the underlying library or implemented in ``parallel-ssh``.
5+
6+
Below is a comparison of the differing feature support for the two client types.
7+
8+
============================== ========= ======================
9+
Feature Paramiko ssh2-python (libssh2)
10+
============================== ========= ======================
11+
Agent forwarding Yes Not supported
12+
Proxying/tunnelling Yes Not yet implemented
13+
Kerberos (GSS) authentication Yes Not supported
14+
Per-channel timeout setting Yes Not supported
15+
Public key from memory Yes Not yet implemented
16+
============================== ========= ======================
17+
18+
If any of these features are required for a use case, then the paramiko based clients should be used instead. In all other cases the ``ssh2-python`` clients are preferred.

‎doc/ssh2_client.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
SSH2Client
2+
===========
3+
4+
API documentation for the `ssh2-python` (`libssh2`) based single host client.
5+
6+
.. automodule:: pssh.ssh2_client
7+
:member-order: groupwise

‎pssh/pssh2_client.py‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,28 +15,23 @@
1515
# License along with this library; if not, write to the Free Software
1616
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
1717

18+
import logging
1819

19-
"""Package containing ParallelSSHClient class"""
20+
import gevent.pool
21+
import gevent.hub
2022

2123
from .base_pssh import BaseParallelSSHClient
2224
from .constants import DEFAULT_RETRIES, RETRY_DELAY
2325
from .ssh2_client import SSHClient
2426

25-
import logging # noqa: E402
26-
27-
import gevent.pool # noqa: E402
28-
import gevent.hub # noqa: E402
2927

3028
gevent.hub.Hub.NOT_ERROR = (Exception,)
3129
logger = logging.getLogger(__name__)
3230

33-
try:
34-
xrange
35-
except NameError:
36-
xrange = range
37-
3831

3932
class ParallelSSHClient(BaseParallelSSHClient):
33+
"""ssh2-python based parallel client."""
34+
4035
def __init__(self, hosts, user=None, password=None, port=None, pkey=None,
4136
num_retries=DEFAULT_RETRIES, timeout=None, pool_size=10,
4237
allow_agent=True, host_config=None, retry_delay=RETRY_DELAY):

0 commit comments

Comments
 (0)