Add asyncio support, cursor enhancements, test runner refactor and documentation

README.md

@@ -18,6 +18,8 @@ For more information on the APIs supported by ibm_db, please refer to below link
 
 https://github.com/ibmdb/python-ibmdb/wiki/APIs
 
+For the asyncio APIs, please refer to [ASYNC_APIs_WIKI.md](ASYNC_APIs_WIKI.md).
+
 <a name="prereq"></a>
 
 ## Pre-requisites
@@ -744,29 +746,38 @@ later of Db2. While Db2 v8.x is fully supported, two of the tests
 (test_195.py and test_52949.py) utilize XML functionality. These tests will
 fail on version 8.x of Db2.
 
-## Running the driver testsuite on Linux
+## Running the driver testsuite
 
-In order to run the entire python driver testsuite on Linux, run this
-command at the command prompt:
+Run the entire testsuite (sync + async):
 
 ```
   python ibmdb_tests.py
 ```
 
-To run a single test, set the environment variable, **SINGLE_PYTHON_TEST**, to
-the test filename you would like to run, followed by the previous command.
+Run only sync or async tests, or a single test file:
 
-## Running the driver testsuite on Windows
+```
+  python ibmdb_tests.py --async                                # Run only async tests
+  python ibmdb_tests.py --sync                                 # Run only sync tests
+  python ibmdb_tests.py --async --test test_05_async_fetch.py   # Run a single async test
+  python ibmdb_tests.py --sync  --test test_006_ConnPassingOpts.py  # Run a single sync test
+```
 
-In order to run the entire python driver testsuite on Windows, run this
-command at the command prompt:
+Legacy: To run a single test, set the environment variable **SINGLE_PYTHON_TEST**:
 
 ```
-  python ibmdb_tests.py
+  Windows:
+  set SINGLE_PYTHON_TEST=test_006_ConnPassingOpts.py
+
+  Other platforms:
+  export SINGLE_PYTHON_TEST=test_006_ConnPassingOpts.py
 ```
 
-To run a single test, set the environment variable, **SINGLE_PYTHON_TEST**, to
-the test filename you would like to run, followed by the previous command.
+Then run:
+
+```
+  python ibmdb_tests.py
+```
 
 ## Known Limitations for the Python driver
 

asyncio_testsuite/test_01_async_connect.py

@@ -0,0 +1,50 @@
+from __future__ import print_function
+import asyncio
+import sys
+import unittest
+import ibm_db_dbi
+import config
+from testfunctions import IbmDbTestFunctions
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_01_async_connect(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expect(self.run_test_01)
+
+    def run_test_01(self):
+        async def main():
+            # Cataloged connection
+            conn = await ibm_db_dbi.connect_async(config.database, config.user, config.password)
+            if conn:
+                print("Cataloged connection succeeded.")
+                conn.close()
+            else:
+                print("Cataloged connection failed.")
+
+            # Uncataloged connection
+            conn = await ibm_db_dbi.connect_async(
+                "DATABASE=%s;HOSTNAME=%s;PORT=%d;PROTOCOL=TCPIP;UID=%s;PWD=%s;" % (
+                    config.database, config.hostname, config.port,
+                    config.user, config.password),
+                '', '')
+            if conn:
+                print("Uncataloged connection succeeded.")
+                conn.close()
+            else:
+                print("Uncataloged connection failed.")
+        asyncio.run(main())
+
+#__END__
+#__LUW_EXPECTED__
+#Cataloged connection succeeded.
+#Uncataloged connection succeeded.
+#__ZOS_EXPECTED__
+#Cataloged connection succeeded.
+#Uncataloged connection succeeded.
+#__SYSTEMI_EXPECTED__
+#Cataloged connection succeeded.
+#Uncataloged connection succeeded.
+#__IDS_EXPECTED__
+#Cataloged connection succeeded.
+#Uncataloged connection succeeded.

asyncio_testsuite/test_02_async_pconnect.py

@@ -0,0 +1,46 @@
+from __future__ import print_function
+import asyncio
+import sys
+import unittest
+import ibm_db_dbi
+import config
+from testfunctions import IbmDbTestFunctions
+
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_02_async_pconnect(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expectf(self.run_test_02)
+
+    def run_test_02(self):
+        async def main():
+            conn = await ibm_db_dbi.pconnect_async(
+                "DATABASE=%s;HOSTNAME=%s;PORT=%d;PROTOCOL=TCPIP;UID=%s;PWD=%s;" % (
+                    config.database, config.hostname, config.port,
+                    config.user, config.password),
+                '', '')
+            print("Persistent connection:", conn)
+            info = conn.server_info()
+            print("Server info:", info)
+            conn.close()
+            print("Connection closed.")
+        asyncio.run(main())
+
+#__END__
+#__LUW_EXPECTED__
+#Persistent connection: <ibm_db_dbi.Connection object at %s>
+#Server info: (%s)
+#Connection closed.
+#__ZOS_EXPECTED__
+#Persistent connection: <ibm_db_dbi.Connection object at %s>
+#Server info: (%s)
+#Connection closed.
+#__SYSTEMI_EXPECTED__
+#Persistent connection: <ibm_db_dbi.Connection object at %s>
+#Server info: (%s)
+#Connection closed.
+#__IDS_EXPECTED__
+#Persistent connection: <ibm_db_dbi.Connection object at %s>
+#Server info: (%s)
+#Connection closed.

asyncio_testsuite/test_03_async_connection_class.py

@@ -0,0 +1,44 @@
+from __future__ import print_function
+import asyncio
+import sys
+import unittest
+import config
+from ibm_db_dbi import AsyncConnection
+from testfunctions import IbmDbTestFunctions
+
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_03_async_connection_class(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expectf(self.run_test_03)
+
+    def run_test_03(self):
+        async def main():
+            conn = await AsyncConnection.connect(
+                "DATABASE=%s;HOSTNAME=%s;PORT=%d;PROTOCOL=TCPIP;UID=%s;PWD=%s;" % (
+                    config.database, config.hostname, config.port,
+                    config.user, config.password),
+                '', '')
+            print("Connected via AsyncConnection.connect():", conn)
+
+            cursor = await conn.cursor()
+            print("Cursor created:", cursor)
+
+            await cursor.close()
+            await conn.close()
+        asyncio.run(main())
+
+#__END__
+#__LUW_EXPECTED__
+#Connected via AsyncConnection.connect(): <ibm_db_dbi.AsyncConnection object at %s>
+#Cursor created: <ibm_db_dbi.AsyncCursor object at %s>
+#__ZOS_EXPECTED__
+#Connected via AsyncConnection.connect(): <ibm_db_dbi.AsyncConnection object at %s>
+#Cursor created: <ibm_db_dbi.AsyncCursor object at %s>
+#__SYSTEMI_EXPECTED__
+#Connected via AsyncConnection.connect(): <ibm_db_dbi.AsyncConnection object at %s>
+#Cursor created: <ibm_db_dbi.AsyncCursor object at %s>
+#__IDS_EXPECTED__
+#Connected via AsyncConnection.connect(): <ibm_db_dbi.AsyncConnection object at %s>
+#Cursor created: <ibm_db_dbi.AsyncCursor object at %s>

asyncio_testsuite/test_04_async_context_manager.py

@@ -0,0 +1,59 @@
+from __future__ import print_function
+import asyncio
+import sys
+import unittest
+import config
+from ibm_db_dbi import AsyncConnection
+from testfunctions import IbmDbTestFunctions
+
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_04_async_context_manager(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expect(self.run_test_04)
+
+    def run_test_04(self):
+        async def main():
+            conn = await AsyncConnection.connect(
+                "DATABASE=%s;HOSTNAME=%s;PORT=%d;PROTOCOL=TCPIP;UID=%s;PWD=%s;" % (
+                    config.database, config.hostname, config.port,
+                    config.user, config.password),
+                '', '')
+
+            async with conn:
+                cursor = await conn.cursor()
+                async with cursor:
+                    await cursor.execute("SELECT ID, NAME FROM STAFF FETCH FIRST 3 ROWS ONLY")
+                    rows = await cursor.fetchall()
+                    for row in rows:
+                        print(row)
+                print("Cursor auto-closed via __aexit__")
+            print("Connection auto-closed via __aexit__")
+        asyncio.run(main())
+
+#__END__
+#__LUW_EXPECTED__
+#(10, 'Sanders')
+#(20, 'Pernal')
+#(30, 'Marenghi')
+#Cursor auto-closed via __aexit__
+#Connection auto-closed via __aexit__
+#__ZOS_EXPECTED__
+#(10, 'Sanders')
+#(20, 'Pernal')
+#(30, 'Marenghi')
+#Cursor auto-closed via __aexit__
+#Connection auto-closed via __aexit__
+#__SYSTEMI_EXPECTED__
+#(10, 'Sanders')
+#(20, 'Pernal')
+#(30, 'Marenghi')
+#Cursor auto-closed via __aexit__
+#Connection auto-closed via __aexit__
+#__IDS_EXPECTED__
+#(10, 'Sanders')
+#(20, 'Pernal')
+#(30, 'Marenghi')
+#Cursor auto-closed via __aexit__
+#Connection auto-closed via __aexit__

asyncio_testsuite/test_05_async_fetch.py

@@ -0,0 +1,59 @@
+from __future__ import print_function
+import asyncio
+import sys
+import unittest
+import config
+from ibm_db_dbi import AsyncConnection
+from testfunctions import IbmDbTestFunctions
+
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_05_async_fetch(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expect(self.run_test_05)
+
+    def run_test_05(self):
+        async def main():
+            conn = await AsyncConnection.connect(
+                "DATABASE=%s;HOSTNAME=%s;PORT=%d;PROTOCOL=TCPIP;UID=%s;PWD=%s;" % (
+                    config.database, config.hostname, config.port,
+                    config.user, config.password),
+                '', '')
+            cursor = await conn.cursor()
+
+            await cursor.execute("SELECT ID, NAME, JOB FROM STAFF FETCH FIRST 10 ROWS ONLY")
+
+            # fetchone
+            row = await cursor.fetchone()
+            print("fetchone:", row)
+
+            # fetchmany
+            rows = await cursor.fetchmany(size=3)
+            print("fetchmany(3):", rows)
+
+            # fetchall (remaining)
+            remaining = await cursor.fetchall()
+            print("fetchall remaining:", remaining)
+
+            await cursor.close()
+            await conn.close()
+        asyncio.run(main())
+
+#__END__
+#__LUW_EXPECTED__
+#fetchone: (10, 'Sanders', 'Mgr  ')
+#fetchmany(3): [(20, 'Pernal', 'Sales'), (30, 'Marenghi', 'Mgr  '), (40, 'OBrien', 'Sales')]
+#fetchall remaining: [(50, 'Hanes', 'Mgr  '), (60, 'Quigley', 'Sales'), (70, 'Rothman', 'Sales'), (80, 'James', 'Clerk'), (90, 'Koonitz', 'Sales'), (100, 'Plotz', 'Mgr  ')]
+#__ZOS_EXPECTED__
+#fetchone: (10, 'Sanders', 'Mgr  ')
+#fetchmany(3): [(20, 'Pernal', 'Sales'), (30, 'Marenghi', 'Mgr  '), (40, 'OBrien', 'Sales')]
+#fetchall remaining: [(50, 'Hanes', 'Mgr  '), (60, 'Quigley', 'Sales'), (70, 'Rothman', 'Sales'), (80, 'James', 'Clerk'), (90, 'Koonitz', 'Sales'), (100, 'Plotz', 'Mgr  ')]
+#__SYSTEMI_EXPECTED__
+#fetchone: (10, 'Sanders', 'Mgr  ')
+#fetchmany(3): [(20, 'Pernal', 'Sales'), (30, 'Marenghi', 'Mgr  '), (40, 'OBrien', 'Sales')]
+#fetchall remaining: [(50, 'Hanes', 'Mgr  '), (60, 'Quigley', 'Sales'), (70, 'Rothman', 'Sales'), (80, 'James', 'Clerk'), (90, 'Koonitz', 'Sales'), (100, 'Plotz', 'Mgr  ')]
+#__IDS_EXPECTED__
+#fetchone: (10, 'Sanders', 'Mgr  ')
+#fetchmany(3): [(20, 'Pernal', 'Sales'), (30, 'Marenghi', 'Mgr  '), (40, 'OBrien', 'Sales')]
+#fetchall remaining: [(50, 'Hanes', 'Mgr  '), (60, 'Quigley', 'Sales'), (70, 'Rothman', 'Sales'), (80, 'James', 'Clerk'), (90, 'Koonitz', 'Sales'), (100, 'Plotz', 'Mgr  ')]

asyncio_testsuite/test_06_async_iteration.py

@@ -0,0 +1,65 @@
+from __future__ import print_function
+import asyncio
+import sys
+import unittest
+import config
+from ibm_db_dbi import AsyncConnection
+from testfunctions import IbmDbTestFunctions
+
+
+class IbmDbTestCase(unittest.TestCase):
+
+    def test_06_async_iteration(self):
+        obj = IbmDbTestFunctions()
+        obj.assert_expect(self.run_test_06)
+
+    def run_test_06(self):
+        async def main():
+            conn = await AsyncConnection.connect(
+                "DATABASE=%s;HOSTNAME=%s;PORT=%d;PROTOCOL=TCPIP;UID=%s;PWD=%s;" % (
+                    config.database, config.hostname, config.port,
+                    config.user, config.password),
+                '', '')
+            cursor = await conn.cursor()
+
+            await cursor.execute("SELECT ID, NAME FROM STAFF FETCH FIRST 5 ROWS ONLY")
+
+            count = 0
+            async for row in cursor:
+                print(row)
+                count += 1
+            print("Iterated over %d rows" % count)
+
+            await cursor.close()
+            await conn.close()
+        asyncio.run(main())
+
+#__END__
+#__LUW_EXPECTED__
+#(10, 'Sanders')
+#(20, 'Pernal')
+#(30, 'Marenghi')
+#(40, 'OBrien')
+#(50, 'Hanes')
+#Iterated over 5 rows
+#__ZOS_EXPECTED__
+#(10, 'Sanders')
+#(20, 'Pernal')
+#(30, 'Marenghi')
+#(40, 'OBrien')
+#(50, 'Hanes')
+#Iterated over 5 rows
+#__SYSTEMI_EXPECTED__
+#(10, 'Sanders')
+#(20, 'Pernal')
+#(30, 'Marenghi')
+#(40, 'OBrien')
+#(50, 'Hanes')
+#Iterated over 5 rows
+#__IDS_EXPECTED__
+#(10, 'Sanders')
+#(20, 'Pernal')
+#(30, 'Marenghi')
+#(40, 'OBrien')
+#(50, 'Hanes')
+#Iterated over 5 rows