Documentation updates, including changes for PEP 8 compliance, to take

into account the fact that the default branch has changed to main, etc.

Author: anthony-tuininga

README.md

@@ -39,21 +39,21 @@ See [/test][11].
 
 ## Contributing
 
-See [CONTRIBUTING](https://github.com/oracle/python-cx_Oracle/blob/master/CONTRIBUTING.md)
+See [CONTRIBUTING](https://github.com/oracle/python-cx_Oracle/blob/main/CONTRIBUTING.md)
 
 ## License
 
 cx_Oracle is licensed under a BSD license which you can find [here][3].
 
 [1]: https://www.python.org/dev/peps/pep-0249
 [2]: http://cx-oracle.readthedocs.io
-[3]: https://github.com/oracle/python-cx_Oracle/blob/master/LICENSE.txt
+[3]: https://github.com/oracle/python-cx_Oracle/blob/main/LICENSE.txt
 [5]: http://lists.sourceforge.net/lists/listinfo/cx-oracle-users
-[6]: https://github.com/oracle/python-cx_Oracle/tree/master/samples/tutorial
+[6]: https://github.com/oracle/python-cx_Oracle/tree/main/samples/tutorial
 [7]: http://cx-oracletools.sourceforge.net
 [8]: http://cx-pyoraclelib.sourceforge.net
 [9]: https://github.com/oracle/python-cx_Oracle/issues
-[11]: https://github.com/oracle/python-cx_Oracle/tree/master/test
-[12]: https://github.com/oracle/python-cx_Oracle/tree/master/samples
+[11]: https://github.com/oracle/python-cx_Oracle/tree/main/test
+[12]: https://github.com/oracle/python-cx_Oracle/tree/main/samples
 [14]: https://cx-oracle.readthedocs.io/en/latest/release_notes.html
 [15]: https://cx-oracle.readthedocs.io/en/latest/user_guide/installation.html

doc/src/api_manual/connection.rst

@@ -74,13 +74,18 @@ Connection Object
     that a single round-trip to the database may take before a timeout will
     occur. A value of 0 means that no timeout will take place.
 
+    If a timeout occurs, the error *DPI-1067* will be returned if the
+    connection is still usable.  Alternatively the error *DPI-1080* will be
+    returned if the connection has become invalid and can no longer be used.
+
     .. versionadded:: 7.0
 
     .. versionchanged:: 8.2
 
         For consistency and compliance with the PEP 8 naming style, the
         attribute `callTimeout` was renamed to `call_timeout`. The old name
-        will continue to work for a period of time.
+        will continue to work for a period of time.  The error *DPI-1080* was
+        also introduced in this release.
 
     .. note::
 

doc/src/api_manual/cursor.rst

@@ -67,7 +67,7 @@ Cursor Object
     Array variables can only be used for PL/SQL associative arrays with
     contiguous keys. For PL/SQL associative arrays with sparsely populated keys
     or for varrays and nested tables, the approach shown in this
-    `example <https://github.com/oracle/python-cx_Oracle/blob/master/
+    `example <https://github.com/oracle/python-cx_Oracle/blob/main/
     samples/plsql_collection.py>`__ needs to be used.
 
     .. note::

doc/src/api_manual/deprecations.rst

@@ -35,7 +35,7 @@ if applicable. The most recent deprecations are listed first.
     * - Positional parameters to :meth:`cx_Oracle.connect()`
       - Replace with keyword parameters in order to comply with the Python
         database API.
-    * - positional parameters to :meth:`cx_Oracle.SessionPool()`
+    * - Positional parameters to :meth:`cx_Oracle.SessionPool()`
       - Replace with keyword parameters in order to comply with the Python
         database API.
     * - `threaded` parameter to :meth:`cx_Oracle.SessionPool()`

doc/src/api_manual/module.rst

@@ -97,7 +97,7 @@ Module Interface
     See the :ref:`globalization <globalization>` section for details on the
     encoding and nencoding parameters.  Note the default encoding and nencoding
     values changed to "UTF-8" in cx_Oracle 8, and any character set in NLS_LANG
-    is ignored.
+    is ignored. In a future release of cx_Oracle, only UTF-8 will be supported.
 
     The edition parameter is expected to be a string if specified and sets the
     edition to use for the session. It is only relevant if both the client and
@@ -208,7 +208,7 @@ Module Interface
 
 
 .. function:: SessionPool(user=None, password=None, dsn=None, min=1, max=2, \
-        increment=1, connectiontype=cx_Oracle.Connection, threaded=False, \
+        increment=1, connectiontype=cx_Oracle.Connection, threaded=True, \
         getmode=cx_Oracle.SPOOL_ATTRVAL_NOWAIT, events=False, \
         homogeneous=True, externalauth=False, encoding=None, nencoding=None, \
         edition=None, timeout=0, wait_timeout=0, max_lifetime_session=0, \
@@ -275,7 +275,8 @@ Module Interface
     values transferred between cx_Oracle and Oracle Database, see
     :ref:`Character Sets and Globalization <globalization>`. Note the default
     encoding and nencoding values changed to "UTF-8" in cx_Oracle 8, and any
-    character set in NLS_LANG is ignored.
+    character set in NLS_LANG is ignored. In a future release of cx_Oracle,
+    only UTF-8 will be supported.
 
     The edition parameter is expected to be a string, if specified, and sets the
     edition to use for the sessions in the pool. It is only relevant if both the
@@ -285,7 +286,9 @@ Module Interface
     The timeout parameter is expected to be an integer, if specified, and sets
     the length of time (in seconds) after which idle sessions in the pool are
     terminated. Note that termination only occurs when the pool is accessed.
-    The default value of 0 means that no idle sessions are terminated.
+    The default value of 0 means that no idle sessions are terminated. The
+    initial pool timeout must be non-zero if you subsequently want to change
+    the timeout with :meth:`SessionPool.reconfigure()`.
 
     The wait_timeout parameter is expected to be an integer, if specified, and
     sets the length of time (in milliseconds) that the caller should wait for
@@ -350,7 +353,8 @@ Module Interface
         `session_callback` and the parameter `maxSessionsPerShard` was renamed
         to `max_sessions_per_shard`. The old names will continue to work as
         keyword parameters for a period of time. The `threaded` parameter value
-        is ignored and threading is always enabled.
+        is ignored and threading is always enabled; in previous versions the
+        default was False.
 
 
 .. function:: Time(hour, minute, second)

doc/src/api_manual/session_pool.rst

@@ -71,6 +71,20 @@ SessionPool Object
     connection has been established.
 
 
+.. attribute:: SessionPool.getmode
+
+    This read-write attribute determines how connections are returned from the
+    pool. If :data:`~cx_Oracle.SPOOL_ATTRVAL_FORCEGET` is specified, a new
+    connection will be returned even if there are no free sessions in the pool.
+    :data:`~cx_Oracle.SPOOL_ATTRVAL_NOWAIT` will raise an exception if there
+    are no free sessions are available in the pool. If
+    :data:`~cx_Oracle.SPOOL_ATTRVAL_WAIT` is specified and there are no free
+    sessions in the pool, the caller will wait until a free session is
+    available.  :data:`~cx_Oracle.SPOOL_ATTRVAL_TIMEDWAIT` uses the value of
+    :data:`~SessionPool.wait_timeout` to determine how long the caller should
+    wait for a session to become available before returning an error.
+
+
 .. attribute:: SessionPool.homogeneous
 
     This read-write boolean attribute indicates whether the pool is considered
@@ -128,11 +142,11 @@ SessionPool Object
     This read-write integer attribute specifies the pool ping interval in
     seconds. When a connection is acquired from the pool, a check is first made
     to see how long it has been since the connection was put into the pool. If
-    this idle time exceeds ``ping_interval``, then a :ref:`round-trip <roundtrips>`
-    ping to the database is performed. If the connection is unusable, it is
-    discarded and a different connection is selected to be returned by
-    :meth:`SessionPool.acquire()`.  Setting ``ping_interval`` to a negative
-    value disables pinging.  Setting it to 0 forces a ping for every
+    this idle time exceeds ``ping_interval``, then a :ref:`round-trip
+    <roundtrips>` ping to the database is performed. If the connection is
+    unusable, it is discarded and a different connection is selected to be
+    returned by :meth:`SessionPool.acquire()`.  Setting ``ping_interval`` to a
+    negative value disables pinging.  Setting it to 0 forces a ping for every
     ``aquire()`` and is not recommended.
 
     Prior to cx_Oracle 8.2, the ping interval was fixed at 60 seconds.

doc/src/api_manual/soda.rst

@@ -256,9 +256,11 @@ SODA Collection Object
 
     The hint parameter, if specified, supplies a hint to the database when
     processing the SODA operation. This is expected to be a string in the same
-    format as SQL hints but without the enclosing comment characters. Use of
-    this parameter requires Oracle Client 21.3 or higher (or Oracle Client 19
-    from 19.11).
+    format as SQL hints but without any comment characters, for example
+    ``hint="MONITOR"``. While you could use this to pass any SQL hint, the
+    hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
+    monitoring) are the most useful. Use of the hint parameter requires Oracle
+    Client 21.3 or higher (or Oracle Client 19 from 19.11).
 
     .. note::
 
@@ -288,9 +290,11 @@ SODA Collection Object
 
     The hint parameter, if specified, supplies a hint to the database when
     processing the SODA operation. This is expected to be a string in the same
-    format as SQL hints but without the enclosing comment characters. Use of
-    this parameter requires Oracle Client 21.3 or higher (or Oracle Client 19
-    from 19.11).
+    format as SQL hints but without any comment characters, for example
+    ``hint="MONITOR"``. While you could use this to pass any SQL hint, the
+    hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
+    monitoring) are the most useful. Use of the hint parameter requires Oracle
+    Client 21.3 or higher (or Oracle Client 19 from 19.11).
 
     .. versionadded:: 7.0
 
@@ -339,9 +343,11 @@ SODA Collection Object
 
     The hint parameter, if specified, supplies a hint to the database when
     processing the SODA operation. This is expected to be a string in the same
-    format as SQL hints but without the enclosing comment characters. Use of
-    this parameter requires Oracle Client 21.3 or higher (or Oracle Client 19
-    from 19.11).
+    format as SQL hints but without any comment characters, for example
+    ``hint="MONITOR"``. While you could use this to pass any SQL hint, the
+    hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
+    monitoring) are the most useful. Use of the hint parameter requires Oracle
+    Client 21.3 or higher (or Oracle Client 19 from 19.11).
 
     This method requires Oracle Client 19.9 or higher in addition to the usual
     SODA requirements.
@@ -560,8 +566,10 @@ SODA Operation Object
 
     Specifies a hint that will be provided to the SODA operation when it is
     performed. This is expected to be a string in the same format as SQL hints
-    but without the enclosing comment characters. Use of this method
-    requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
+    but without any comment characters. While you could use this to pass any SQL
+    hint, the hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn
+    off monitoring) are the most useful. Use of this method requires Oracle
+    Client 21.3 or higher (or Oracle Client 19 from 19.11).
 
     As a convenience, the SodaOperation object is returned so that further
     criteria can be specified by chaining methods together.

doc/src/conf.py

@@ -28,8 +28,8 @@
 # The suffix of source filenames.
 source_suffix = '.rst'
 
-# The master toctree document.
-master_doc = 'index'
+# The main toctree document.
+main_doc = 'index'
 
 # General substitutions.
 project = 'cx_Oracle'

doc/src/release_notes.rst

@@ -5,23 +5,16 @@
 cx_Oracle Release Notes
 =======================
 
+For any deprecations, see :ref:`Deprecations <deprecations>`.
+
 Version 8.2 (TBD)
 -----------------
 
 #)  Updated embedded ODPI-C to `version 4.2.0
     <https://oracle.github.io/odpi/doc/releasenotes.html#
     version-4-2-tbd>`__.
-#)  Added :ref:`SODA metadata cache <sodametadatacache>` support to connection
-    pools. This significantly improves the performance of methods
-    :meth:`SodaDatabase.createCollection()` (when not specifying a value for
-    the metadata parameter) and :meth:`SodaDatabase.openCollection()`. Caching
-    is available when using Oracle Client version 19.11 and higher.
-#)  Added support for supplying hints to SODA operations. A new non-terminal
-    method :meth:`~SodaOperation.hint()` was added and a `hint` parameter was
-    added to the methods :meth:`SodaCollection.insertOneAndGet()`,
-    :meth:`SodaCollection.insertManyAndGet()` and
-    :meth:`SodaCollection.saveAndGet()`. All of these require Oracle Client
-    21.3 or higher (or Oracle Client 19 from 19.11).
+#)  Threaded mode is now always enabled when creating connection pools with
+    :meth:`cx_Oracle.SessionPool()`. Any `threaded` parameter value is ignored.
 #)  Added parameter `stmtcachesize` to :meth:`cx_Oracle.connect()` and
     :meth:`cx_Oracle.SessionPool()` in order to permit specifying the size of
     the statement cache during the creation of pools and standalone
@@ -31,20 +24,39 @@ Version 8.2 (TBD)
     attribute :data:`SessionPool.ping_interval` was added in order to permit
     making adjustments after the pool has been created.  In previous cx_Oracle
     releases a fixed ping interval of 60 seconds was used.
+#)  Added parameter `soda_metadata_cache` to :meth:`cx_Oracle.SessionPool()` for
+    :ref:`SODA metadata cache <sodametadatacache>` support.  In addition, the
+    attribute :data:`SessionPool.soda_metadata_cache` was added in order to
+    permit making adjustments after the pool has been created. This feature
+    significantly improves the performance of methods
+    :meth:`SodaDatabase.createCollection()` (when not specifying a value for the
+    metadata parameter) and :meth:`SodaDatabase.openCollection()`. Caching is
+    available when using Oracle Client version 19.11 and higher.
+#)  Added support for supplying hints to SODA operations. A new non-terminal
+    method :meth:`~SodaOperation.hint()` was added and a `hint` parameter was
+    added to the methods :meth:`SodaCollection.insertOneAndGet()`,
+    :meth:`SodaCollection.insertManyAndGet()` and
+    :meth:`SodaCollection.saveAndGet()`. All of these require Oracle Client
+    21.3 or higher (or Oracle Client 19 from 19.11).
 #)  Added parameter `bypass_decode` to :meth:`Cursor.var()` in order to allow
     the `decode` step to be bypassed when converting data from Oracle Database
     into Python strings
     (`issue 385 <https://github.com/oracle/python-cx_Oracle/issues/385>`__).
     Initial work was done in `PR 549
     <https://github.com/oracle/python-cx_Oracle/pull/549>`__.
-#)  Threaded mode is now always enabled when creating connection pools with
-    :meth:`cx_Oracle.SessionPool()`. Any `threaded` parameter value is ignored.
+#)  Enhanced dead connection detection.  If an Oracle Database error indicates
+    that a connection is no longer usable, the error `DPI-1080: connection was
+    closed by ORA-%d` is now returned.  The `%d` will be the Oracle error
+    causing the connection to be closed.  Using the connection after this will
+    give `DPI-1010: not connected`.  This behavior also applies for
+    :data:`Connection.call_timeout` errors that result in an unusable
+    connection.
 #)  Eliminated a memory leak when calling :meth:`SodaOperation.filter()` with a
     dictionary.
 #)  The distributed transaction handle assosciated with the connection is now
     cleared on commit or rollback (`issue 530
     <https://github.com/oracle/python-cx_Oracle/issues/530>`__).
-#)  Added check to ensure that when setting variables or object attributes, the
+#)  Added a check to ensure that when setting variables or object attributes, the
     type of the temporary LOB must match the expected type.
 #)  A small number of parameter, method, and attribute names were updated to
     follow the PEP 8 style guide. This brings better consistency to the
@@ -1020,10 +1032,10 @@ Version 6.0 beta 1 (April 2017)
     tagging.
 #)  Added parameter edition to the :meth:`cx_Oracle.SessionPool` method.
 #)  Added support for
-    `universal rowids <https://github.com/oracle/python-cx_Oracle/blob/master/
+    `universal rowids <https://github.com/oracle/python-cx_Oracle/blob/main/
     samples/universal_rowids.py>`__.
 #)  Added support for `DML Returning of multiple rows
-    <https://github.com/oracle/python-cx_Oracle/blob/master/samples/
+    <https://github.com/oracle/python-cx_Oracle/blob/main/samples/
     dml_returning_multiple_rows.py>`__.
 #)  Added attributes :attr:`Variable.actualElements` and
     :attr:`Variable.values` to variables.
@@ -1053,19 +1065,19 @@ Version 6.0 beta 1 (April 2017)
 #)  Dropped deprecated parameters action, module and clientinfo from the
     :meth:`cx_Oracle.connect` method. The appcontext parameter should be used
     instead as shown in this `sample <https://github.com/oracle/
-    python-cx_Oracle/blob/master/samples/app_context.py>`__.
+    python-cx_Oracle/blob/main/samples/app_context.py>`__.
 #)  Dropped deprecated attribute numbersAsString from
     :ref:`cursor objects <cursorobj>`. Use an output type handler instead as
     shown in this `sample <https://github.com/oracle/python-cx_Oracle/blob/
-    master/samples/return_numbers_as_decimals.py>`__.
+    main/samples/return_numbers_as_decimals.py>`__.
 #)  Dropped deprecated attributes cqqos and rowids from
     :ref:`subscription objects <subscrobj>`. Use the qos attribute instead as
     shown in this `sample <https://github.com/oracle/python-cx_Oracle/blob/
-    master/samples/cqn.py>`__.
+    main/samples/cqn.py>`__.
 #)  Dropped deprecated parameters cqqos and rowids from the
     :meth:`Connection.subscribe()` method. Use the qos parameter instead as
     shown in this `sample <https://github.com/oracle/python-cx_Oracle/blob/
-    master/samples/cqn.py>`__.
+    main/samples/cqn.py>`__.
 
 
 Version 5.3 (March 2017)