Skip to content

Commit 224b7a2

Browse files
author
Pan
committed
Updated readme, updated setup. Added exceptions cython file and agent source code file.
1 parent b9dc8ab commit 224b7a2

File tree

6 files changed

+348
-525
lines changed

6 files changed

+348
-525
lines changed

README.rst

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
ssh2-python
2+
============
3+
4+
Super fast SSH2 protocol library. ``ssh2-python`` provides Python bindings for `libssh2`_.
5+
6+
.. image:: https://img.shields.io/badge/License-LGPL%20v2-blue.svg
7+
:target: https://pypi.python.org/pypi/ssh2-python
8+
:alt: License
9+
.. image:: https://img.shields.io/pypi/v/ssh2-python.svg
10+
:target: https://pypi.python.org/pypi/ssh2-python
11+
:alt: Latest Version
12+
13+
Features
14+
---------
15+
16+
Majority of the `libssh2`_ API has been implemented as Python native code extensions. ``ssh2-python`` is a thin wrapper of ``libssh2`` - ``libssh2`` code examples can be ported straight over to Python with only minimal changes.
17+
18+
*Library is usable for testing purposes and at the moment available as source code only. API, module names and documentation not yet finalised. Contributions welcome.*
19+
20+
SSH Functionality provided
21+
++++++++++++++++++++++++++++
22+
23+
* SSH channel operations (exec,shell,subsystem)
24+
* SSH agent
25+
* Public key authentication and management
26+
* SFTP
27+
* SCP
28+
* SSH port forwarding and tunnelling
29+
* Non-blocking mode
30+
* Listener for port forwarding
31+
32+
And more, as per `libssh2`_ functionality.
33+
34+
35+
Native Code Extension Features
36+
+++++++++++++++++++++++++++++++
37+
38+
The library uses `Cython`_ based native code extensions as wrappers to ``libssh2``.
39+
40+
Extension features:
41+
42+
* Thread safe - GIL is released as much as possible
43+
* Very low overhead
44+
* Super fast as a consequence of the excellent C library it uses and that it uses native code prodigiously
45+
* Object oriented - memory freed automatically and safely as objects expire
46+
* Use Python semantics where applicable, such as iterator support for SFTP file handles
47+
* Expose errors as Python exceptions where possible
48+
* Provide access to ``libssh2`` error code definitions
49+
50+
51+
Example
52+
--------
53+
54+
A simple usage example looks very similar to ``libssh2`` `usage examples <https://www.libssh2.org/examples/>`_.
55+
56+
As mentioned, ``ssh2-python`` is intentially a thin wrapper over ``libssh2`` and directly maps most of its API.
57+
58+
Clients using this library can be much simpler to use than interfacing with the ``libssh2`` API directly.
59+
60+
.. code-block:: python
61+
62+
from __future__ import print_function
63+
64+
import os
65+
import socket
66+
67+
from ssh2 import Session
68+
69+
host = 'localhost'
70+
user = os.getlogin()
71+
72+
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
73+
sock.connect((host, 22))
74+
75+
session = Session()
76+
session.handshake(sock)
77+
session.agent_auth(user)
78+
79+
channel = session.open_session()
80+
channel.execute('echo me; exit 2')
81+
size, data = channel.read()
82+
while size > 0:
83+
print(data)
84+
size, data = channel.read()
85+
channel.close()
86+
print("Exit status: %s" % channel.get_exit_status())
87+
88+
89+
:Output:
90+
91+
me
92+
93+
Exit status: 2
94+
95+
96+
Comparison with other Python SSH2 libraries
97+
---------------------------------------------
98+
99+
Performance of above example, compared with Paramiko.
100+
101+
.. code-block:: shell
102+
103+
time python examples/example_echo.py
104+
time python examples/paramiko_comparison.py
105+
106+
:Output:
107+
108+
``ssh2-python``::
109+
110+
real 0m0.141s
111+
user 0m0.037s
112+
sys 0m0.008s
113+
114+
``paramiko``::
115+
116+
real 0m0.592s
117+
user 0m0.351s
118+
sys 0m0.021s
119+
120+
121+
See `examples directory < link >`_ for more complete example scripts.
122+
123+
.. _libssh2: https://www.libssh2.org
124+
.. _Cython: https://www.cython.org

examples/example_echo.py

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
from __future__ import print_function
2+
import os
3+
import socket
4+
5+
from ssh2 import Session
6+
from ssh2.utils import version
7+
8+
# Connection settings
9+
host = 'localhost'
10+
user = os.getlogin()
11+
12+
# Make socket, connect
13+
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
14+
sock.connect((host, 22))
15+
16+
# Initialise
17+
session = Session()
18+
session.handshake(sock)
19+
20+
# List available authentication methods
21+
print(session.userauth_list(user))
22+
23+
# Convenience function for agent based authentication
24+
session.agent_auth(user)
25+
26+
# Agent capabilities
27+
# agent = session.agent_init()
28+
# agent.connect()
29+
# identities = agent.get_identities(user)
30+
# print(identities)
31+
# print(identities[0].magic)
32+
33+
# Public key blob available as identities[0].blob
34+
35+
# Channel initialise, exec and wait for end
36+
channel = session.open_session()
37+
channel.execute('echo me')
38+
channel.wait_eof()
39+
channel.close()
40+
channel.wait_closed()
41+
42+
# Get exit status
43+
print("Exit status: %s" % channel.get_exit_status())
44+
45+
# Print output
46+
size, data = channel.read()
47+
while size > 0:
48+
print(data)
49+
size, data = channel.read()
50+
51+
# SFTP capabilities, uncomment and enter a filename
52+
53+
# sftp = session.sftp_init()
54+
# fh = sftp.open('<my file>', 0, 0)
55+
# for data in fh:
56+
# pass
57+
# del session

examples/paramiko_echo.py

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
from __future__ import print_function
2+
3+
import paramiko
4+
5+
client = paramiko.SSHClient()
6+
client.set_missing_host_key_policy(
7+
paramiko.MissingHostKeyPolicy())
8+
client.connect('localhost')
9+
transport = client.get_transport()
10+
channel = transport.open_session()
11+
stdout = channel.makefile('rb')
12+
channel.exec_command('echo me')
13+
for line in stdout:
14+
print(line)
15+
channel.close()
16+
print("Exit status: %s" % channel.recv_exit_status())

setup.py

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
import platform
44
import os
55
import sys
6-
import glob
76

87
# import versioneer
98
from setuptools import setup, find_packages, Extension
@@ -19,9 +18,6 @@
1918

2019
ext = 'pyx' if USING_CYTHON else 'c'
2120

22-
sources = glob.glob("ssh2/ext/*.%s" % (ext,))
23-
extensions = sources
24-
2521
extensions = [
2622
Extension('ssh2/*',
2723
sources=['ssh2/*.pyx'],

0 commit comments

Comments
 (0)