Skip to content

Commit 4996524

Browse files
pkittenispkittenis
authored
Updated readme (#163)
1 parent 83ca859 commit 4996524

File tree

2 files changed

+12
-217
lines changed

2 files changed

+12
-217
lines changed

‎README.rst

+10-215
Original file line numberDiff line numberDiff line change
@@ -35,28 +35,17 @@ Binary wheel packages are provided for Linux, OSX and Windows, all Python versio
3535
3636
For from source installation instructions, including building against system provided libssh2, `see documentation <https://ssh2-python.readthedocs.io/en/latest/installation.html#installation-from-source>`_.
3737

38-
For creating native system packages for Centos/RedHat, Ubuntu, Debian and Fedora, see `instructions in the documentation <http://ssh2-python.readthedocs.io/en/latest/installation.html#system-binary-packages>`_.
39-
40-
4138
Who Should Use This
4239
___________________
4340

44-
Developers of bespoke SSH clients.
45-
46-
47-
Who Should Not Use This
48-
_______________________
49-
50-
Developers looking for ready made SSH clients.
51-
52-
This library is not an SSH client.
41+
Most developers will want to use the `high level clients <https://parallel-ssh.readthedocs.io/en/latest/quickstart.html#single-host-client>`_
42+
in `parallel-ssh <https://github.com/ParallelSSH/parallel-ssh>`_
43+
based on this library.
5344

54-
Developers looking for high level easy to use clients based on this library should use `parallel-ssh <https://github.com/ParallelSSH/parallel-ssh>`_. It provides both `single <https://parallel-ssh.readthedocs.io/en/latest/native_single.html>`_ and `parallel <https://parallel-ssh.readthedocs.io/en/latest/native_parallel.html>`_ clients.
55-
56-
This library provides bindings to libssh2 and its API closely matches libssh2.
57-
58-
If the examples seem long, this is not the right library. Use `parallel-ssh <https://github.com/ParallelSSH/parallel-ssh>`_.
45+
This library provides bindings to the low-level libssh2 C-API. It is *not* high level, nor easy to use. A *lot* of code
46+
would need to be written to use this library that is already provided by `parallel-ssh`.
5947

48+
Use `parallel-ssh <https://github.com/ParallelSSH/parallel-ssh>`_ unless *really* sure using a C-API is what is wanted.
6049

6150
API Feature Set
6251
________________
@@ -67,207 +56,13 @@ Complete example scripts for various operations can be found in the `examples di
6756

6857
In addition, as ``ssh2-python`` is a thin wrapper of ``libssh2`` with Python semantics, `its code examples <https://libssh2.org/examples/>`_ can be ported straight over to Python with only minimal changes.
6958

70-
71-
Library Features
72-
----------------
73-
74-
The library uses `Cython`_ based native code extensions as wrappers to ``libssh2``.
75-
76-
Extension features:
77-
78-
* Thread safe - GIL is released as much as possible. Note that libssh2 does not support sharing sessions across threads
79-
* Very low overhead
80-
* Super fast as a consequence of the excellent C library it uses and prodigious use of native code
81-
* Object oriented - memory freed automatically and safely as objects are garbage collected by Python
82-
* Use Python semantics where applicable, such as context manager and iterator support for opening and reading from SFTP file handles
83-
* Raise errors as Python exceptions
84-
* Provide access to ``libssh2`` error code definitions
85-
86-
87-
Quick Start
59+
Examples
8860
_____________
8961

90-
Both byte and unicode strings are accepted as arguments and encoded appropriately. To change default encoding, ``utf-8``, change the value of ``ssh2.utils.ENCODING``. Output is always in byte strings.
91-
92-
See `Complete Example`_ for an example including socket connect.
93-
94-
Please use either the issue tracker for reporting issues with code or the `mail group`_ for discussion and questions.
95-
96-
Contributions are most welcome!
97-
98-
99-
Authentication Methods
100-
-------------------------
101-
102-
103-
Connect and get available authentication methods.
104-
105-
106-
.. code-block:: python
107-
108-
from __future__ import print_function
109-
110-
from ssh2.session import Session
111-
112-
sock = <create and connect socket>
113-
114-
session = Session()
115-
session.handshake(sock)
116-
print(session.userauth_list())
117-
118-
119-
Output will vary depending on SSH server configuration. For example:
120-
121-
.. code-block:: python
122-
123-
['publickey', 'password', 'keyboard-interactive']
124-
125-
126-
Agent Authentication
127-
------------------------
128-
129-
.. code-block:: python
130-
131-
session.agent_auth(user)
132-
133-
134-
Command Execution
135-
------------------------
136-
137-
.. code-block:: python
138-
139-
channel = session.open_session()
140-
channel.execute('echo Hello')
141-
142-
143-
Reading Output
144-
---------------
145-
146-
.. code-block:: python
147-
148-
size, data = channel.read()
149-
while(size > 0):
150-
print(data)
151-
size, data = channel.read()
152-
153-
.. code-block:: python
154-
155-
Hello
156-
157-
158-
Exit Code
159-
--------------
160-
161-
.. code-block:: python
162-
163-
print("Exit status: %s" % (channel.get_exit_status()))
164-
165-
166-
.. code-block:: python
167-
168-
Exit status: 0
169-
170-
171-
Public Key Authentication
172-
----------------------------
173-
174-
.. code-block:: python
175-
176-
session.userauth_publickey_fromfile(
177-
username, 'private_key_file')
178-
179-
180-
Passphrase can be provided with the ``passphrase`` keyword param - see `API documentation <https://ssh2-python.readthedocs.io/en/latest/session.html#ssh2.session.Session.userauth_publickey_fromfile>`_.
181-
182-
183-
Password Authentication
184-
----------------------------
185-
186-
.. code-block:: python
187-
188-
session.userauth_password(
189-
username, '<my password>')
190-
191-
SFTP Read
192-
-----------
193-
194-
.. code-block:: python
195-
196-
from ssh2.sftp import LIBSSH2_FXF_READ, LIBSSH2_SFTP_S_IRUSR
197-
198-
sftp = session.sftp_init()
199-
with sftp.open(<remote file to read>,
200-
LIBSSH2_FXF_READ, LIBSSH2_SFTP_S_IRUSR) as remote_fh, \
201-
open(<local file to write>, 'wb') as local_fh:
202-
for size, data in remote_fh:
203-
local_fh.write(data)
204-
205-
206-
Complete Example
207-
__________________
208-
209-
A simple usage example looks very similar to ``libssh2`` `usage examples <https://www.libssh2.org/examples/>`_.
210-
211-
See `examples directory <https://github.com/ParallelSSH/ssh2-python/tree/master/examples>`_ for more complete example scripts.
212-
213-
As mentioned, ``ssh2-python`` is intentionally a thin wrapper over ``libssh2`` and directly maps most of its API.
214-
215-
Clients using this library can be much simpler to use than interfacing with the ``libssh2`` API directly.
216-
217-
.. code-block:: python
218-
219-
from __future__ import print_function
220-
221-
import os
222-
import socket
223-
224-
from ssh2.session import Session
225-
226-
host = 'localhost'
227-
user = os.getlogin()
228-
229-
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
230-
sock.connect((host, 22))
231-
232-
session = Session()
233-
session.handshake(sock)
234-
session.agent_auth(user)
235-
236-
channel = session.open_session()
237-
channel.execute('echo me; exit 2')
238-
size, data = channel.read()
239-
while size > 0:
240-
print(data)
241-
size, data = channel.read()
242-
channel.close()
243-
print("Exit status: %s" % channel.get_exit_status())
244-
245-
246-
:Output:
247-
248-
me
249-
250-
Exit status: 2
251-
252-
253-
SSH Functionality currently implemented
254-
________________________________________
255-
256-
257-
* SSH channel operations (exec,shell,subsystem) and methods
258-
* SSH agent functionality
259-
* Public key authentication and management
260-
* SFTP operations
261-
* SFTP file handles and attributes
262-
* SSH port forwarding and tunnelling
263-
* Non-blocking mode
264-
* SCP send and receive
265-
* Listener for port forwarding
266-
* Subsystem support
267-
* Host key checking and manipulation
268-
269-
And more, as per `libssh2`_ functionality.
62+
See `examples directory <https://github.com/ParallelSSH/ssh2-python/tree/master/examples>`_ for complete examples.
27063

64+
Again, most developers will want to use `parallel-ssh <https://github.com/ParallelSSH/parallel-ssh>`_ rather than this
65+
library directly.
27166

27267
Comparison with other Python SSH libraries
27368
-------------------------------------------

‎setup.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -124,12 +124,12 @@
124124
'Operating System :: OS Independent',
125125
'Programming Language :: C',
126126
'Programming Language :: Python',
127-
'Programming Language :: Python :: 2',
128-
'Programming Language :: Python :: 2.7',
129127
'Programming Language :: Python :: 3',
130128
'Programming Language :: Python :: 3.6',
131129
'Programming Language :: Python :: 3.7',
132130
'Programming Language :: Python :: 3.8',
131+
'Programming Language :: Python :: 3.9',
132+
'Programming Language :: Python :: 3.10',
133133
'Topic :: System :: Shells',
134134
'Topic :: System :: Networking',
135135
'Topic :: Software Development :: Libraries',

0 commit comments

Comments
 (0)