Rework build to use setuptools exclusively and enable use of pyproject.toml;

rework test suite to use tox and simplify test suite (also added a test number
to each test case for easier reference).

Author: anthony-tuininga

.gitignore

@@ -1,4 +1,5 @@
 *.pyc
+.tox/
 build/
 dist/
 doc/build

README.md

@@ -7,7 +7,7 @@ of exclusions.  See the
 [homepage](https://oracle.github.io/python-cx_Oracle/index.html) for a
 feature list.
 
-cx_Oracle 8 has been tested with Python versions 3.5 through 3.8. You can use
+cx_Oracle 8 has been tested with Python versions 3.6 through 3.9. You can use
 cx_Oracle with Oracle 11.2, 12c, 18c and 19c client libraries. Oracle's
 standard client-server version interoperability allows connection to both older
 and newer databases. For example Oracle 19c client libraries can connect to

doc/src/release_notes.rst

@@ -11,12 +11,18 @@ Version 8.1 (TBD)
 #)  Updated embedded ODPI-C to `version 4.1.0
     <https://oracle.github.io/odpi/doc/releasenotes.html#
     version-4-1-0-tbd>`__.
+#)  Dropped support for Python 3.5. Added support for Python 3.9.
 #)  Added internal methods for getting/setting OCI attributes that are
     otherwise not supported by cx_Oracle. These methods should only be used as
     directed by Oracle.
 #)  Minor code improvement supplied by Alex Henrie
     (`PR 472 <https://github.com/oracle/python-cx_Oracle/pull/472>`__).
-#)  Improved documentation.
+#)  Builds are now done with setuptools and most metadata has moved from
+    `setup.py` to `setup.cfg` in order to take advantage of Python packaging
+    improvements.
+#)  Tests can now be run with tox in order to automate testing of the different
+    environments that are supported.
+#)  Improved documentation and test suite.
 
 
 Version 8.0.1 (August 2020)

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools >= 40.6.0", "wheel"]
+build-backend = "setuptools.build_meta"

setup.cfg

@@ -0,0 +1,27 @@
+[metadata]
+name = cx_Oracle
+description = Python interface to Oracle
+long_description = file: README.md
+long_description_content_type = text/markdown
+keywords = Oracle, database
+author = "Anthony Tuininga",
+author_email = "[email protected]",
+license = BSD License
+url = https://oracle.github.io/python-cx_Oracle
+project_urls =
+    Installation = https://cx-oracle.readthedocs.io/en/latest/user_guide/installation.html
+    Samples = https://github.com/oracle/python-cx_Oracle/tree/master/samples
+    Documentation = http://cx-oracle.readthedocs.io
+    Release Notes = https://cx-oracle.readthedocs.io/en/latest/release_notes.html#releasenotes
+    Issues = https://github.com/oracle/python-cx_Oracle/issues
+    Source = https://github.com/oracle/python-cx_Oracle
+python_requires = >=3.6
+classifiers =
+    Development Status :: 6 - Mature
+    Intended Audience :: Developers
+    License :: OSI Approved :: BSD License
+    Natural Language :: English
+    Operating System :: OS Independent
+    Programming Language :: C
+    Programming Language :: Python :: 3 :: Only
+    Topic :: Database

setup.py

@@ -1,4 +1,4 @@
-"""Distutils script for cx_Oracle.
+"""Setup script for cx_Oracle.
 
 Windows platforms:
     python setup.py build --compiler=mingw32 install
@@ -8,21 +8,18 @@
 
 """
 
-import distutils.core
 import os
+import pkg_resources
+import setuptools
 import sys
 
 # check minimum supported Python version
-if sys.version_info[:2] < (3, 5):
-    raise Exception("Python 3.5 or higher is required. " +
+if sys.version_info[:2] < (3, 6):
+    raise Exception("Python 3.6 or higher is required. " +
             "For python 2, use 'pip install cx_Oracle==7.3'")
 
-# if setuptools is detected, use it to add support for eggs
-try:
-    from setuptools import setup, Extension
-except:
-    from distutils.core import setup
-    from distutils.extension import Extension
+# check minimum supported version of setuptools
+pkg_resources.require("setuptools>=40.6.0")
 
 # define build constants
 BUILD_VERSION = "8.1.0-dev"
@@ -39,43 +36,12 @@
 elif sys.platform == "darwin":
     extraLinkArgs.append("-shared-libgcc")
 
-class test(distutils.core.Command):
-    description = "run the test suite for the extension"
-    user_options = []
-
-    def finalize_options(self):
-        pass
-
-    def initialize_options(self):
-        pass
-
-    def run(self):
-        self.run_command("build")
-        buildCommand = self.distribution.get_command_obj("build")
-        sys.path.insert(0, os.path.abspath("test"))
-        sys.path.insert(0, os.path.abspath(buildCommand.build_lib))
-        fileName = os.path.join("test", "test.py")
-        exec(open(fileName).read())
-
-# define classifiers for the package index
-classifiers = [
-        "Development Status :: 6 - Mature",
-        "Intended Audience :: Developers",
-        "License :: OSI Approved :: BSD License",
-        "Natural Language :: English",
-        "Operating System :: OS Independent",
-        "Programming Language :: C",
-        "Programming Language :: Python :: 3 :: Only",
-        "Topic :: Database"
-]
-
 # define cx_Oracle sources
 sourceDir = "src"
 sources = [os.path.join(sourceDir, n) \
         for n in sorted(os.listdir(sourceDir)) if n.endswith(".c")]
 depends = ["src/cxoModule.h"]
 
-
 # define ODPI-C sources, libraries and include directories; if the environment
 # variables ODPIC_INC_DIR and ODPIC_LIB_DIR are both set, assume these
 # locations contain a compiled installation of ODPI-C; otherwise, use the
@@ -98,7 +64,7 @@ def run(self):
     libraryDirs = []
 
 # setup the extension
-extension = Extension(
+extension = setuptools.Extension(
         name = "cx_Oracle",
         include_dirs = includeDirs,
         extra_compile_args = extraCompileArgs,
@@ -110,22 +76,7 @@ def run(self):
         library_dirs = libraryDirs)
 
 # perform the setup
-setup(
-        name = "cx_Oracle",
+setuptools.setup(
         version = BUILD_VERSION,
-        description = "Python interface to Oracle",
-        cmdclass = dict(test = test),
         data_files = [ ("cx_Oracle-doc", ["LICENSE.txt", "README.txt"]) ],
-        long_description = \
-            "Python interface to Oracle Database conforming to the Python DB "
-            "API 2.0 specification.\n"
-            "See http://www.python.org/topics/database/DatabaseAPI-2.0.html.",
-        author = "Anthony Tuininga",
-        author_email = "[email protected]",
-        url = "https://oracle.github.io/python-cx_Oracle",
-        python_requires = ">=3.5",
-        ext_modules = [extension],
-        keywords = "Oracle",
-        license = "BSD License",
-        classifiers = classifiers)
-
+        ext_modules = [extension])

test/README.md

@@ -2,46 +2,45 @@ This directory contains the test suite for cx_Oracle.
 
 1. The schemas and SQL objects that are referenced in the test suite can be
    created by running the Python script [SetupTest.py][1]. The script requires
-   SYSDBA privileges and will prompt for these credentials as well as the
-   names of the schemas that will be created, unless a number of environment
-   variables are set as documented in the Python script [TestEnv.py][2]. Run
-   the script using the following command:
+   administrative privileges and will prompt for these credentials as well as
+   the names of the schemas that will be created, unless a number of
+   environment variables are set as documented in the Python script
+   [TestEnv.py][2]. Run the script using the following command:
 
        python SetupTest.py
 
    Alternatively, the [SQL script][3] can be run directly via SQL\*Plus, which
    will always prompt for the names of the schemas that will be created. Run
    the script using the following command:
 
-       sqlplus sys/syspassword@hostname/servicename @sql/SetupTest.sql
+       sqlplus system/systempassword@hostname/servicename @sql/SetupTest.sql
 
 2. Run the test suite by issuing the following command in the top-level
    directory of your cx_Oracle installation:
 
-       python setup.py test
+       tox
 
    Alternatively, you can run the test suite directly within this directory:
 
-       python test.py
+       python TestEnv.py
 
 3. After running the test suite, the schemas can be dropped by running the
-   Python script [DropTest.py][4]. The script requires SYSDBA privileges and
-   will prompt for these credentials as well as the names of the schemas
-   that will be dropped, unless a number of environment variables are set as
-   documented in the Python script [TestEnv.py][2]. Run the script using the
-   following command:
+   Python script [DropTest.py][4]. The script requires administrative
+   privileges and will prompt for these credentials as well as the names of the
+   schemas that will be dropped, unless a number of environment variables are
+   set as documented in the Python script [TestEnv.py][2]. Run the script using
+   the following command:
 
        python DropTest.py
 
    Alternatively, the [SQL script][5] can be run directly via SQL\*Plus, which
    will always prompt for the names of the schemas that will be dropped. Run
    the script using the following command:
 
-       sqlplus sys/syspassword@hostname/servicename @sql/DropTest.sql
+       sqlplus system/systempassword@hostname/servicename @sql/DropTest.sql
 
 [1]: https://github.com/oracle/python-cx_Oracle/blob/master/test/SetupTest.py
 [2]: https://github.com/oracle/python-cx_Oracle/blob/master/test/TestEnv.py
 [3]: https://github.com/oracle/python-cx_Oracle/blob/master/test/sql/SetupTest.sql
 [4]: https://github.com/oracle/python-cx_Oracle/blob/master/test/DropTest.py
 [5]: https://github.com/oracle/python-cx_Oracle/blob/master/test/sql/DropTest.sql
-

test/TestEnv.py

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2016, 2019, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
 #
 # Portions Copyright 2007-2015, Anthony Tuininga. All rights reserved.
 #
@@ -146,6 +146,14 @@ def RunSqlScript(conn, scriptName, **kwargs):
         print("    %s/%s %s" % (lineNum, position, text))
 
 def RunTestCases():
+    print("Running tests for cx_Oracle version", cx_Oracle.version,
+            "built at", cx_Oracle.buildtime)
+    print("File:", cx_Oracle.__file__)
+    print("Client Version:",
+            ".".join(str(i) for i in cx_Oracle.clientversion()))
+    with GetConnection() as connection:
+        print("Server Version:", connection.version)
+        print()
     unittest.main(testRunner=unittest.TextTestRunner(verbosity=2))
 
 def GetConnection(**kwargs):
@@ -161,7 +169,32 @@ def GetPool(user=None, password=None, **kwargs):
             encoding="UTF-8", nencoding="UTF-8", **kwargs)
 
 def GetClientVersion():
-    return cx_Oracle.clientversion()
+    name = "CLIENT_VERSION"
+    value = PARAMETERS.get(name)
+    if value is None:
+        value = cx_Oracle.clientversion()[:2]
+        PARAMETERS[name] = value
+    return value
+
+def GetServerVersion():
+    name = "SERVER_VERSION"
+    value = PARAMETERS.get(name)
+    if value is None:
+        conn = GetConnection()
+        value = tuple(int(s) for s in conn.version.split("."))[:2]
+        PARAMETERS[name] = value
+    return value
+
+def SkipSodaTests():
+    client = GetClientVersion()
+    if client < (18, 3):
+        return True
+    server = GetServerVersion()
+    if server < (18, 0):
+        return True
+    if server > (20, 1) and client < (20, 1):
+        return True
+    return False
 
 class RoundTripInfo:
 
@@ -225,3 +258,9 @@ def tearDown(self):
         del self.cursor
         del self.connection
 
+
+def load_tests(loader, standard_tests, pattern):
+    return loader.discover(os.path.dirname(__file__))
+
+if __name__ == "__main__":
+    RunTestCases()