feat: Allow transport objects to be closed

The base transport class now has a close method, which marks the
transport as closed and additionally will throw an exception if the call
method is called on a closed transport object. In addition, the close
method will be called by __del__, so the transport will be automatically
closed prior to it being destructed.

Transports should override the _close method if they need to free any
transport-specific resources (currently only DatabaseTransport and
SshTransport need to do so).

Fixes #64

Author: kadler

src/itoolkit/__init__.py

@@ -16,6 +16,7 @@
 from .itoolkit import iSqlFree
 from .itoolkit import iSqlParm
 from .itoolkit import iXml
+from .errors import TransportClosedException
 
 __all__ = [
     'iToolKit',
@@ -34,4 +35,5 @@
     'iSqlParm',
     'iSqlFree',
     'iXml',
+    'TransportClosedException',
 ]

src/itoolkit/errors.py

@@ -0,0 +1,8 @@
+__all__ = [
+    'TransportClosedException',
+]
+
+
+class TransportClosedException(Exception):
+    """Raised when an operation is performed on a closed transport"""
+    pass

src/itoolkit/itoolkit.py

@@ -1158,6 +1158,9 @@ def call(self, itrans):
 
         Returns:
           none
+
+        Raises:
+          TransportClosedException: If the transport has been closed.
         """
         if self.trace_fd:
             self.trace_write('***********************')

src/itoolkit/transport/base.py

@@ -1,3 +1,6 @@
+from ..errors import TransportClosedException
+
+
 class XmlServiceTransport(object):
     """XMLSERVICE transport base class
 
@@ -12,6 +15,10 @@ def __init__(self, ctl="*here *cdata", ipc="*na"):
         self.ctl = ctl
 
         self.trace_attrs = ["ipc", "ctl"]
+        self._is_open = True
+
+    def __del__(self):
+        self.close()
 
     def trace_data(self):
         output = ""
@@ -35,10 +42,34 @@ def call(self, tk):
         Returns:
           str: The XML returned from XMLSERVICE
         """
+        self._ensure_open()
+
         return self._call(tk)
 
     def _call(self, tk):
         """Called by :py:func:`call`. This should be overridden by subclasses
         to the call function instead of overriding :py:func:`call` directly.
         """
         raise NotImplementedError
+
+    def _ensure_open(self):
+        """This should be called by any subclass function which uses
+        resources which may have been released when `close` is called."""
+        if not self._is_open:
+            raise TransportClosedException()
+
+    def close(self):
+        """Close the connection now rather than when :py:func:`__del__` is
+        called.
+
+        The transport will be unusable from this point forward and a
+        :py:exc:`TransportClosedException` exception will be raised if any
+        operation is attempted with the transport.
+        """
+        self._close()
+        self._is_open = False
+
+    def _close(self):
+        """Called by `close`. This should be overridden by subclasses to close
+        any resources specific to that implementation."""
+        pass

src/itoolkit/transport/database.py

@@ -77,3 +77,6 @@ def _call(self, tk):
         getattr(cursor, self.func)(self.query, parms)
 
         return "".join(row[0] for row in cursor).rstrip('\0')
+
+    def _close(self):
+        self.conn.close()

src/itoolkit/transport/ssh.py

@@ -103,3 +103,6 @@ def _call(self, tk):
         stdout.channel.close()
         stderr.channel.close()
         return xml_out
+
+    def _close(self):
+        self.conn.close()

tests/test_unit_transport_database.py

@@ -1,6 +1,7 @@
-from itoolkit import iToolKit
-from itoolkit.transport import DatabaseTransport
+import pytest
 
+from itoolkit import iToolKit, TransportClosedException
+from itoolkit.transport import DatabaseTransport
 
 def test_database_transport_callproc(database_callproc):
     transport = DatabaseTransport(database_callproc)
@@ -60,3 +61,13 @@ def test_database_transport_callproc_schema(database_execute):
 
     assert len(cursor.execute.call_args[0]) > 0
     assert schema in cursor.execute.call_args[0][0]
+
+
+def test_database_transport_call_raises_when_closed(database_execute):
+    schema = 'MYSCHEMA'
+    transport = DatabaseTransport(database_execute, schema=schema)
+    transport.close()
+
+    with pytest.raises(TransportClosedException):
+        tk = iToolKit()
+        out = transport.call(tk)

tests/test_unit_transport_direct.py

@@ -1,7 +1,7 @@
 import pytest
 import sys
 
-from itoolkit import iToolKit
+from itoolkit import iToolKit, TransportClosedException
 from itoolkit.transport import DirectTransport
 import itoolkit.transport.direct
 
@@ -63,3 +63,14 @@ def test_direct_transport(mocker):
 
     assert_xmlservice_params_correct(mock)
     assert isinstance(out, (bytes, str))
+
+
+def test_direct_transport_call_raises_when_closed(mocker):
+    mock = mock_direct(mocker)
+
+    transport = DirectTransport()
+    transport.close()
+
+    with pytest.raises(TransportClosedException):
+        tk = iToolKit()
+        out = transport.call(tk)

tests/test_unit_transport_http.py

@@ -1,6 +1,7 @@
+import pytest
 import sys
 
-from itoolkit import iToolKit
+from itoolkit import iToolKit, TransportClosedException
 from itoolkit.transport import HttpTransport
 
 if sys.version_info >= (3, 0):
@@ -104,3 +105,19 @@ def test_http_transport_with_database(mocker):
         pwd=password,
         db2=database
     )
+
+
+def test_http_transport_call_raises_when_closed(mocker):
+    mock_urlopen = mock_http_urlopen(mocker)
+
+    url = 'http://example.com/cgi-bin/xmlcgi.pgm'
+    user = 'dummy'
+    password = 'passw0rd'
+    database = 'MYDB'
+
+    transport = HttpTransport(url, user, password, database=database)
+    transport.close()
+
+    with pytest.raises(TransportClosedException):
+        tk = iToolKit()
+        out = transport.call(tk)

tests/test_unit_transport_ssh.py

@@ -1,4 +1,6 @@
-from itoolkit import iToolKit
+import pytest
+
+from itoolkit import iToolKit, TransportClosedException
 from itoolkit.transport import SshTransport
 
 
@@ -29,3 +31,14 @@ def test_ssh_transport_minimal(mocker):
 
     command = "/QOpenSys/pkgs/bin/xmlservice-cli"
     ssh_client.exec_command.assert_called_once_with(command)
+
+
+def test_ssh_transport_raises_when_closed(mocker):
+    ssh_client = mock_ssh(mocker)
+
+    transport = SshTransport(ssh_client)
+    transport.close()
+
+    with pytest.raises(TransportClosedException):
+        tk = iToolKit()
+        out = transport.call(tk)