Improved documentation.

Author: anthony-tuininga

doc/src/api_manual/module.rst

@@ -1317,15 +1317,6 @@ General
     String constant stating the supported DB API level. Currently '2.0'.
 
 
-.. data:: buildtime
-
-    String constant stating the time when the binary was built.
-
-    .. note::
-
-        This constant is an extension to the DB API definition.
-
-
 .. data:: paramstyle
 
     String constant stating the type of parameter marker formatting expected by

doc/src/user_guide/appendix_a.rst

@@ -86,10 +86,18 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - No
       - Yes
       - Yes
+    * - Lightweight Directory Access Protocol (LDAP) connections
+      - No
+      - Yes
+      - Yes
     * - Proxy connections (see :ref:`proxyauth`)
       - Yes
       - Yes
       - Yes
+    * - Socket Secure (SOCKS) Proxy connections
+      - No
+      - No
+      - No
     * - Connection mode privileges (see :ref:`connection-authorization-modes`)
       - Yes
       - Yes - only :data:`~oracledb.AUTH_MODE_SYSDBA` is supported
@@ -114,7 +122,7 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - No
       - Yes - No TIMESTAMP support
       - Yes - No TIMESTAMP support
-    * - Oracle Database Native Network Encryption (see :ref:`nne`)
+    * - Oracle Database Native Network Encryption (NNE) (see :ref:`nne`)
       - No
       - Yes
       - Yes

doc/src/user_guide/installation.rst

@@ -899,8 +899,16 @@ If using python-oracledb fails:
 - If you have multiple versions of Python installed, ensure that you are
   using the correct python and pip (or python3 and pip3) executables.
 
+- If ``import oracledb`` gives a warning like ``Python 3.6 is no longer
+  supported by the Python core team. Therefore, support for it is deprecated in
+  python-oracledb and will be removed in a future release`` then plan to
+  upgrade Python. You can temporarily suppress the warning by importing the
+  `warnings <https://docs.python.org/3/library/warnings.html>`__ module and
+  adding a call like ``warnings.filterwarnings(action='ignore',
+  module="oracledb")`` *before* importing ``oracledb``.
+
 - If you get the error ``DPI-1047: Oracle Client library cannot be
-  loaded``:
+  loaded`` then:
 
   - Review the :ref:`features available in python-oracledb's default Thin mode
     <featuresummary>`.  If Thin mode suits your requirements, then remove calls
@@ -958,17 +966,53 @@ If using python-oracledb fails:
     file in the ``/etc/ld.so.conf.d`` directory contains the path to the
     Instant Client directory, and then run ``ldconfig``.
 
-- If you get the error ``DPY-3010: connections to this database server
-  version are not supported by python-oracledb in thin mode`` when
-  connecting to Oracle Database 11.2, then you need to enable Thick mode by
+- If you get the error ``DPY-3010: connections to this database server version
+  are not supported by python-oracledb in thin mode`` when connecting to Oracle
+  Database 11.2, then you need to enable python-oracledb's Thick mode by
   installing Oracle Client libraries and calling
-  :meth:`oracledb.init_oracle_client()` in your code.  Alternatively,
-  upgrade your database.
+  :meth:`oracledb.init_oracle_client()` in your code.  Alternatively, upgrade
+  your database.
 
 - If you get the error ``DPI-1072: the Oracle Client library version is
-  unsupported``, then review the installation requirements.  The Thick
-  mode of python-oracledb needs Oracle Client libraries 11.2 or later.
-  Note that version 19 is not supported on Windows 7.  Similar steps shown
-  above for ``DPI-1047`` may help.  You may be able to use Thin mode which
-  can be done by removing calls :meth:`oracledb.init_oracle_client()` from
-  your code.
+  unsupported``, then review the installation requirements.  The Thick mode of
+  python-oracledb needs Oracle Client libraries 11.2 or later.  Note that
+  version 19 is not supported on Windows 7.  Similar steps shown above for
+  ``DPI-1047`` may help.  You may be able to use python-oracledb Thin mode
+  which can be done by removing calls :meth:`oracledb.init_oracle_client()`
+  from your code.
+
+- If you get the error ``DPY-3015: password verifier type 0x939 is not
+  supported by python-oracledb in thin mode``, then either :ref:`enable Thick
+  mode <enablingthick>` or:
+
+  1. Make sure the database initialization parameter
+     ``sec_case_sensitive_logon`` is not FALSE. To check the value, connect as
+     SYSDBA in SQL*Plus and run ``show parameter sec_case_sensitive_logon``.
+     Note this parameter has been `removed in Oracle Database 21c
+     <https://docs.oracle.com/en/database/oracle/oracle-database/21/nfcon/security-solutions.html#GUID-FAF4C7A6-A2CD-4B9B-9A64-3705F693ECF0>`__
+     so only step 2 is required for this, or subsequent, database versions.
+
+  2. Regenerate passwords for users who have old password verifiers.  You can
+     find such users with the query:
+
+     .. code-block:: sql
+
+        select username from dba_users
+        where (password_versions = '10G ' or password_versions = '10G HTTP ')
+        and username <> 'ANONYMOUS';
+
+     You can reset passwords for these users with commands like ``alter user
+     x identified by y``.
+
+    See the Oracle documentation `Finding and Resetting User Passwords That Use
+    the 10G Password Version
+    <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-D7B09DFE-F55D-449A-8F8A-174D89936304>`__
+    for more information.
+
+- If you get the error ``DPY-4011: the database or network closed the
+  connection`` in python-oracledb's default Thin mode, check if the database
+  requires the use of Native Network Encryption (NNE).  The python-oracledb
+  documentation on :ref:`nne` shows a query from V$SESSION_CONNECT_INFO and
+  sample output to confirm this.  To resolve the error, either change the
+  architecture to use TLS instead of NNE, or :ref:`enable python-oracledb Thick
+  mode <enablingthick>`.