Updated tests. Updated readme. Added helper functions module.

Author: Pan

README.rst

@@ -1 +1,82 @@
-Wrapper for libssh C library.
+ssh-python
+============
+
+Wrapper for libssh_ C library.
+
+
+Installation
+_____________
+
+Currently only installation from source is provided. Binary wheels to follow.
+
+To install from source, run the following after cloning the repository
+
+.. code-block:: shell
+
+   python setup.py install
+
+
+Prerequisites
+--------------
+
+* OpenSSL library and development headers
+* Optionally Zlib library and development headers for compression
+
+``Libssh`` source code is embedded in this project and will be built when installation is triggered per above instructions. Versions of ``libssh`` other than the one embedded in this project are not supported.
+
+
+Quick Start
+_____________
+
+
+.. code-block:: python
+
+   from __future__ import print_function
+
+   import os
+   import pwd
+
+   from ssh.session import Session
+   from ssh import options
+
+   USERNAME = pwd.getpwuid(os.geteuid()).pw_name
+   HOST = 'localhost'
+
+   s = Session()
+   s.options_set(options.HOST, HOST)
+   s.connect()
+
+   # Authenticate with agent
+   s.userauth_agent(USERNAME)
+
+   chan = s.channel_new()
+   chan.open_session()
+   chan.request_exec('echo me')
+   size, data = chan.read()
+   while size > 0:
+       print(data.strip())
+       size, data = chan.read()
+   chan.close()
+
+Output:
+
+.. code-block:: shell
+
+  me
+
+
+Features
+_________
+
+The library uses `Cython`_ based native code extensions as wrappers to ``libssh``.
+
+* Thread safe - GIL is released as much as possible
+* Very low overhead
+* Super fast as a consequence of the excellent C library it uses and prodigious use of native code
+* Object oriented - memory freed automatically and safely as objects are garbage collected by Python
+* Use Python semantics where applicable, such as context manager and iterator support for opening and reading from channels and SFTP file handles
+* Raise errors as Python exceptions
+
+
+.. _libssh: https://www.libssh.org
+.. _Cython: https://www.cython.org

ssh/helper.pyx

@@ -0,0 +1,37 @@
+# This file is part of ssh-python.
+# Copyright (C) 2017-2018 Panos Kittenis
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation, version 2.1.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+from select import select
+
+from session cimport Session
+
+from c_ssh cimport SSH_READ_PENDING, SSH_WRITE_PENDING, ssh_get_poll_flags
+
+
+def wait_socket(_socket not None, Session session, timeout=1):
+    """Helper function for testing non-blocking mode.
+
+    This function blocks the calling thread for <timeout> seconds -
+    to be used only for testing purposes.
+    """
+    cdef int directions = ssh_get_poll_flags(session._session)
+    if directions == 0:
+        return 0
+    readfds = (_socket,) \
+        if (directions & SSH_READ_PENDING) else ()
+    writefds = (_socket,) \
+        if (directions & SSH_WRITE_PENDING) else ()
+    return select(readfds, writefds, (), timeout)

ssh/session.pyx

@@ -32,6 +32,13 @@ cimport c_ssh
 from c_sftp cimport sftp_session, sftp_new, sftp_init
 
 
+# SSH status flags
+SSH_CLOSED = c_ssh.SSH_CLOSED
+SSH_READ_PENDING = c_ssh.SSH_READ_PENDING
+SSH_CLOSED_ERROR = c_ssh.SSH_CLOSED_ERROR
+SSH_WRITE_PENDING = c_ssh.SSH_WRITE_PENDING
+
+
 cdef bint _check_connected(c_ssh.ssh_session session) nogil except -1:
     if not c_ssh.ssh_is_connected(session):
         with gil:
@@ -51,9 +58,9 @@ cdef class Session:
     def __dealloc__(self):
         if self._session is not NULL:
             c_ssh.ssh_free(self._session)
-        self._session = NULL
+            self._session = NULL
 
-    def set_socket(self, socket):
+    def set_socket(self, socket not None):
         """Set socket to use for session.
 
         Not part of libssh API but needs to be done in C to be able to
@@ -122,6 +129,8 @@ cdef class Session:
         return handle_ssh_error_codes(rc, self._session)
 
     def disconnect(self):
+        if self._session is NULL:
+            return
         with nogil:
             c_ssh.ssh_disconnect(self._session)
 
@@ -327,16 +336,16 @@ cdef class Session:
             rc = c_ssh.ssh_set_agent_channel(self._session, channel._channel)
         return handle_ssh_error_codes(rc, self._session)
 
-    def set_agent_socket(self, c_ssh.socket_t fd):
+    def set_agent_socket(self, socket not None):
         cdef int rc
+        cdef c_ssh.socket_t _sock = PyObject_AsFileDescriptor(socket)
         with nogil:
-            rc = c_ssh.ssh_set_agent_socket(self._session, fd)
+            rc = c_ssh.ssh_set_agent_socket(self._session, _sock)
         return handle_ssh_error_codes(rc, self._session)
 
     def set_blocking(self, int blocking):
         with nogil:
             c_ssh.ssh_set_blocking(self._session, blocking)
-        return
 
     def set_counters(self, scounter, rcounter):
         raise NotImplementedError
@@ -456,7 +465,7 @@ cdef class Session:
             rc = c_ssh.ssh_userauth_kbdint_getnprompts(self._session)
         return rc
 
-    def userauth_kbdint_getprompt(self, unsigned int i, bytes echo):
+    def userauth_kbdint_getprompt(self, unsigned int i, bytes echo not None):
         cdef const_char *_prompt
         cdef bytes b_prompt
         cdef char *c_echo = echo
@@ -484,7 +493,7 @@ cdef class Session:
         b_answer = _answer
         return b_answer
 
-    def userauth_kbdint_setanswer(self, unsigned int i, bytes answer):
+    def userauth_kbdint_setanswer(self, unsigned int i, bytes answer not None):
         cdef char *c_answer = answer
         cdef int rc
         with nogil:
@@ -601,3 +610,11 @@ cdef class Session:
         with nogil:
             rc = c_ssh.ssh_get_error_code(self._session)
         return rc
+
+    def scp_new(self, int mode, location not None):
+        cdef c_ssh.ssh_scp _scp
+        cdef bytes b_location = to_bytes(location)
+        cdef char *c_location = b_location
+        raise NotImplementedError
+        with nogil:
+            pass

tests/test_session.py

@@ -51,6 +51,17 @@ def test_should_not_segfault(self):
         self.assertIsNotNone(session.get_error_code())
         session.connector_new()
 
+    def test_disconnect(self):
+        session = Session()
+        session.options_set(options.HOST, self.host)
+        session.options_set_port(self.port)
+        session.options_set(options.USER, self.user)
+        self.assertEqual(session.connect(), 0)
+        self.assertEqual(
+            session.userauth_publickey(self.pkey), 0)
+        session.disconnect()
+        del session
+
     def test_socket_connect(self):
         sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         sock.connect((self.host, self.port))

tests/test_sftp.py

@@ -31,6 +31,8 @@
 from ssh.sftp_attributes import SFTPAttributes
 from ssh.exceptions import InvalidAPIUse, SFTPHandleError, SFTPError
 from ssh.error_codes import SSH_AGAIN
+from ssh.helper import wait_socket
+
 
 from .base_test import SSHTestCase
 
@@ -387,21 +389,20 @@ def test_handle_open_nonblocking(self):
     #                                    'remote_test_file'])
     #     with open(remote_filename, 'wb') as test_fh:
     #         test_fh.write(test_file_data)
-    #     self.session.set_blocking(False)
+    #     # self.session.set_blocking(False)
     #     try:
     #         with sftp.open(remote_filename, os.O_RDONLY, 0) as remote_fh:
     #             self.assertIsInstance(remote_fh, SFTPFile)
     #             remote_fh.set_nonblocking()
     #             remote_data = b""
     #             async_id = remote_fh.async_read_begin()
     #             self.assertNotEqual(async_id, 0)
-    #             # import ipdb; ipdb.set_trace()
+    #             import ipdb; ipdb.set_trace()
     #             size, data = remote_fh.async_read(async_id)
     #             while size > 0 or size == SSH_AGAIN:
     #                 if size == SSH_AGAIN:
     #                     print("Would try again")
-    #                     select((sock,), (sock,), ())
-    #                     time.sleep(1)
+    #                     wait_socket(sock, self.session, timeout=1)
     #                     size, data = remote_fh.async_read(async_id)
     #                     continue
     #                 remote_data += data