Preparing to release cx_Oracle 6.0.

Author: anthony-tuininga

README.md

@@ -4,35 +4,41 @@ cx_Oracle is a Python extension module that enables access to Oracle Database.
 It conforms to the [Python database API 2.0 specification][1] with a
 considerable number of additions and a couple of exclusions.
 
-cx_Oracle is licensed under a [BSD license] which you can find [here][3].
+cx_Oracle is licensed under a BSD license which you can find [here][3].
 
-cx_Oracle 6 has been tested with Python version 2.7, and with versions 3.4 and
-higher. You can use cx_Oracle with Oracle 11.2, 12.1 and 12.2 client libraries,
-allowing connection to multiple Oracle Database versions. Oracle's standard
-client-server version interoperability allows connection to both older and
-newer databases, for example Oracle 12.2 client libraries can connect to Oracle
+cx_Oracle 6 has been tested with Python version 2.7, and with versions
+3.4 and higher. You can use cx_Oracle with Oracle 11.2, 12.1 and 12.2
+client libraries. Oracle's standard client-server version
+interoperability allows connection to both older and newer databases,
+for example Oracle 12.2 client libraries can connect to Oracle
 Database 11.2 or later.
 
+## Documentation
+
+See the [cx_Oracle Documentation][2] and [Release Notes][14].
+
 ## Help
 
 Issues and questions can be raised with the cx_Oracle community on
 [GitHub][9] or on the [mailing list][5].
 
-## Documentation
-
-See the [cx_Oracle Documentation][2] and [Release Notes][14].
-
 ## Installation
 
 See [cx_Oracle Installation][15] for detailed instructions.
 
-- The simplest way to install cx_Oracle 6 RC2 is with pip:
+- The simplest way to install cx_Oracle 6 is with pip:
 
-  `python -m pip install cx_Oracle --pre`
+```
+  python -m pip install cx_Oracle --upgrade
+```
 
   If a binary wheel package is not available on [PyPI][6] for your platform, the
   source package will be used.
 
+  Note that if you download a source zip file directly from GitHub
+  that you will also need to download an [ODPI-C][10] source zip file
+  and extract it inside the directory called "odpi".
+
 - After cx_Oracle is installed, Oracle client libraries must also be installed
   and configured. These can be from Oracle Instant Client, from a local Oracle
   Database, or from a full Oracle Client installation.
@@ -42,44 +48,40 @@ See [cx_Oracle Installation][15] for detailed instructions.
   platform-specific library path loading environment.  See
   the [installation notes for ODPI-C][13] for help.
 
-Versions 11.2, 12.1 and 12.2 of the Oracle Client libraries on Linux,
-Windows and macOS are supported.  Users have also reported success
-with other platforms.
-
-Note that if you download a source zip file directly from GitHub that
-you will also need to download an [ODPI-C][10] source zip file and
-extract it inside the directory called "odpi".
+  Versions 11.2, 12.1 and 12.2 of the Oracle Client libraries on Linux,
+  Windows and macOS are supported.  Users have also reported success
+  with other platforms.
 
+If you require cx_Oracle 5.3, download a Windows installer from
+[PyPI][16] or use `python -m pip install cx-oracle==5.3` to
+install from source.
 
-## Usage Example
+Very old versions of cx_Oracle can be found in the files section at
+[SourceForce][17].
 
+## Example
 
 ```python
-from __future__ import print_function   # needed for Python 2.x
+from __future__ import print_function
 
 import cx_Oracle
 
-# connect via SQL*Net string or by each segment in a separate argument
-#connection = cx_Oracle.connect("user/password@TNS")
-connection = cx_Oracle.connect("user", "password", "TNS")
+connection = cx_Oracle.connect("hr", "welcome", "localhost/orclpdb")
 
 cursor = connection.cursor()
 cursor.execute("""
-        select Col1, Col2, Col3
-        from SomeTable
-        where Col4 = :arg_1
-          and Col5 between :arg_2 and :arg_3""",
-        arg_1 = "VALUE",
-        arg_2 = 5,
-        arg_3 = 15)
-for column_1, column_2, column_3 in cursor:
-    print("Values:", column_1, column_2, column_3)
+    SELECT first_name, last_name
+    FROM employees
+    WHERE department_id = :did AND employee_id > :eid""",
+    did = 50,
+    eid = 190)
+for fname, lname in cursor:
+print("Values:", fname, lname)
 ```
 
-
 For more examples, please see the [test suite][11] and the
-[samples][12]. You can also look at the scripts in the [cx_OracleTools][7] and
-the modules in the [cx_PyOracleLib][8] projects.
+[samples][12]. You can also look at the scripts in [cx_OracleTools][7] and
+the modules in [cx_PyOracleLib][8].
 
 ## Features
 
@@ -94,15 +96,10 @@ the modules in the [cx_PyOracleLib][8] projects.
 - Connect to Oracle Database 9.2, 10, 11 or 12 (depending on the
   Oracle Client version used).
 
-- SQL and PL/SQL Execution, with full support for OCI features like
-  statement caching and statement caching auto-tuning.  Oracle OCI
-  (which is the database access layer used by cx_Oracle) has
-  significant optimizations, including compressed fetch, pre-fetching,
-  client and server result set caching, and statement caching.
-  cx_Oracle applications can additionally make full use of PL/SQL to
-  keep business logic near the data in the database, where it can be
-  processed without having to ship large volumes of data to the
-  application.
+- SQL and PL/SQL Execution. The underlying Oracle Client libraries
+  have significant optimizations including compressed fetch,
+  pre-fetching, client and server result set caching, and statement
+  caching with auto-tuning.
 
 - Full use of Oracle Network Service infrastructure, including
   encrypted network traffic and security features.
@@ -182,3 +179,5 @@ for more information.
 [13]: https://oracle.github.io/odpi/doc/installation.html
 [14]: http://cx-oracle.readthedocs.io/en/latest/releasenotes.html
 [15]: http://cx-oracle.readthedocs.io/en/latest/installation.html
+[16]: https://pypi.python.org/pypi/cx_Oracle/5.3
+[17]: https://sourceforge.net/projects/cx-oracle/files/

doc/src/conf.py

@@ -42,7 +42,7 @@
 # The short X.Y version.
 version = '6.0'
 # The full version, including alpha/beta/rc tags.
-release = '6.0rc2'
+release = '6.0'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

doc/src/installation.rst

@@ -11,16 +11,33 @@ Before cx_Oracle can be installed, an installation of
 `Python <https://www.python.org/downloads>`__ is needed first. Python 2.7 and
 Python 3.4 and higher are supported.
 
-The simplest method of installation is to `Install Using Pip`_. You can also
-`Install Using GitHub`_. If you run into trouble, check out the section on
-`Troubleshooting`_.
+The simplest method of installing cx_Oracle is to `Install Using Pip`_. You
+can also `Install Using GitHub`_. If you run into trouble, check out the
+section on `Troubleshooting`_. cx_Oracle uses `ODPI-C
+<https://github.com/oracle/odpi>`__, which means that the `ODPI-C installation
+instructions <https://oracle.github.io/odpi/doc/installation.html>`__ can be
+useful to review.
 
 After cx_Oracle has been installed, you must also `Install Oracle Client`_, if
 that has not been done already. Oracle Client versions 12.2, 12.1 and 11.2
 are supported.
 
-Note installation has changed from cx_Oracle 5.  When using Oracle
-Instant Client, you should not set ``ORACLE_HOME``.
+Finally, you need an `Oracle Database`_ for Python to connect to. Oracle's
+standard client-server version interoperability allows cx_Oracle to connect to
+both older and newer databases. Python can be local or remote to the database.
+
+
+Upgrading from cx_Oracle 5
+==========================
+
+If you are upgrading from cx_Oracle 5 note these installation changes:
+
+    - When using Oracle Instant Client, you should not set ``ORACLE_HOME``.
+
+    - On Linux, cx_Oracle 6 no longer uses Instant Client RPMs automatically.
+      You must set ``LD_LIBRARY_PATH`` or use ``ldconfig`` to locate the Oracle
+      client library.
+
 
 Install Using Pip
 =================
@@ -29,17 +46,17 @@ Pip is the generic tool for installing Python packages. If you do not have pip,
 see the `pip installation documentation
 <http://pip.readthedocs.io/en/latest/installing/>`__.
 
-The command to install the current Release Candidate of cx_Oracle 6 using pip
-on all platforms is::
+The command to install cx_Oracle 6 using pip on all platforms is::
 
-    python -m pip install cx_Oracle --upgrade --pre
+    python -m pip install cx_Oracle --upgrade
 
 This will download and install a pre-compiled binary matching your platform
 and architecture automatically, if one is available. Pre-compiled binaries are
-available for Windows and Linux.
+available for Windows and Linux. See
+`PyPI <https://pypi.python.org/pypi/cx_Oracle>`__.
 
 If a pre-compiled binary is not available, the source will be
-downloaded, compiled, and the resulting binary installed.  On Linux if
+downloaded, compiled, and the resulting binary installed. On Linux if
 cx_Oracle needs to be compiled for the default python package, you
 will need the ``python-devel`` package or equivalent, which provides
 the `Python.h` header file.
@@ -106,13 +123,13 @@ Oracle Client libraries allow connection to older and newer databases.
 In summary, Oracle Client 12.2 can connect to Oracle Database 11.2 or
 greater. Oracle Client 12.1 can connect to Oracle Database 10.2 or
 greater. Oracle Client 11.2 can connect to Oracle Database 9.2 or
-greater.  For additional information on which Oracle Database releases
+greater. For additional information on which Oracle Database releases
 are supported by which Oracle client versions, please see `Doc ID 207303.1
 <https://support.oracle.com/epmos/faces/DocumentDisplay?id=207303.1>`__.
 
 Since a single cx_Oracle binary can use multiple client versions and access
 multiple database versions, it is important your application is tested in your
-intended release environments.  Newer Oracle clients support new features, such
+intended release environments. Newer Oracle clients support new features, such
 as the `oraaccess.xml <https://docs.oracle.com/database/122/LNOCI/
 more-oci-advanced-topics.htm#LNOCI73052>`__ external configuration file
 available with 12.1 or later clients, and `session pool enhancements
@@ -138,15 +155,6 @@ errors. These include:
     - when attempting to get array DML row counts with Oracle Client
       11.2 you will get the error "DPI-1013: not supported"
 
-cx_Oracle is an `ODPI-C <https://github.com/oracle/odpi>`__ application, which
-means that the installation instructions for
-`Linux <https://oracle.github.io/odpi/doc/installation.html#linux>`__,
-`Windows <https://oracle.github.io/odpi/doc/installation.html#windows>`__
-and `macOS <https://oracle.github.io/odpi/doc/installation.html#macos>`__
-are applicable. For other platforms like Solaris or AIX, follow the same
-general directions as for Linux.
-
-
 Troubleshooting
 ===============
 

doc/src/releasenotes.rst

@@ -4,6 +4,44 @@ cx_Oracle Release Notes
 6.x releases
 ############
 
+Version 6.0 (August 2017)
+-------------------------
+
+#)  Update to `ODPI-C 2.0 <https://oracle.github.io/odpi/doc/releasenotes.html
+    #version-2-0-august-14-2017>`__.
+
+    -   Prevent closing the connection when there are any open statements or
+        LOBs and add new error "DPI-1054: connection cannot be closed when open
+        statements or LOBs exist" when this situation is detected; this is
+        needed to prevent crashes under certain conditions when statements or
+        LOBs are being acted upon while at the same time (in another thread) a
+        connection is being closed; it also prevents leaks of statements and
+        LOBs when a connection is returned to a session pool.
+    -   On platforms other than Windows, if the regular method for loading the
+        Oracle Client libraries fails, try using $ORACLE_HOME/lib/libclntsh.so
+        (`ODPI-C issue 20 <https://github.com/oracle/odpi/issues/20>`__).
+    -   Use the environment variable DPI_DEBUG_LEVEL at runtime, not compile
+        time.
+    -   Added support for DPI_DEBUG_LEVEL_ERRORS (reports errors and has the
+        value 8) and DPI_DEBUG_LEVEL_SQL (reports prepared SQL statement text
+        and has the value 16) in order to further improve the ability to debug
+        issues.
+    -   Correct processing of :meth:`Cursor.scroll()` in some circumstances.
+
+#)  Delay initialization of the ODPI-C library until the first standalone
+    connection or session pool is created so that manipulation of the
+    environment variable NLS_LANG can be performed after the module has been
+    imported; this also has the added benefit of reducing the number of errors
+    that can take place when the module is imported.
+#)  Prevent binding of null values from generating the exception "ORA-24816:
+    Expanded non LONG bind data supplied after actual LONG or LOB column" in
+    certain circumstances
+    (`issue 50 <https://github.com/oracle/python-cx_Oracle/issues/50>`__).
+#)  Added information on how to run the test suite
+    (`issue 33 <https://github.com/oracle/python-cx_Oracle/issues/33>`__).
+#)  Documentation improvements.
+
+
 Version 6.0 rc 2 (July 2017)
 ----------------------------
 

setup.py

@@ -20,7 +20,7 @@
     from distutils.extension import Extension
 
 # define build constants
-BUILD_VERSION = "6.0rc2"
+BUILD_VERSION = "6.0"
 
 # define the list of files to be included as documentation for Windows
 dataFiles = None