Doc updates.

Author: anthony-tuininga

README.md

@@ -70,7 +70,7 @@ with oracledb.connect(user=un, password=pw, dsn=cs) as connection:
   available when optional Oracle Client libraries are loaded by
   python-oracledb.  Libraries are available in the free [Oracle Instant
   Client][instantclient] packages. Python-oracledb can use Oracle Client
-  libraries 11.2 through 23ai.
+  libraries versions 11.2 through 23, inclusive.
 
 - Oracle Database
 

doc/src/api_manual/async_connection.rst

@@ -159,7 +159,7 @@ AsyncConnection Methods
 
     .. note::
 
-        True pipelining requires Oracle Database 23ai.
+        True pipelining requires Oracle Database version 23, or later.
 
         When you connect to an older database, operations are sequentially
         executed by python-oracledb. Each operation concludes before the next

doc/src/api_manual/connect_params.rst

@@ -230,7 +230,7 @@ All properties are read only.
     pooled DRCP or PRCP connections are implicitly released back to the DRCP or
     PRCP pool when either one of the methods :meth:`Connection.commit()` or
     :meth:`Connection.rollback()` are called.  This attribute requires the use
-    of DRCP or PRCP with Oracle Database 23ai (or later). See
+    of DRCP or PRCP with Oracle Database version 23, or later. See
     :ref:`implicitconnpool` for more information.
 
     This attribute is supported in both python-oracledb Thin and Thick modes.

doc/src/api_manual/deprecations.rst

@@ -23,8 +23,10 @@ used for new development.
 
     * - Name
       - Comments
-    * - The x86_64 macOS and 32-bit Windows platforms are deprecated. They will be desupported when the `cryptography <https://pypi.org/project/cryptography/>`__ package desupports them, see the `cryptography deprecation announcement <https://mail.python.org/archives/list/python-announce-list@python.org/thread/R4BZNC36MSFLKULA74KILLFY6GP3VCPA/>`__.
+    * - The x86_64 macOS and 32-bit Windows platforms are deprecated. They will be desupported before, or when, the `cryptography <https://pypi.org/project/cryptography/>`__ package desupports them. See the `cryptography deprecation announcement <https://mail.python.org/archives/list/python-announce-list@python.org/thread/R4BZNC36MSFLKULA74KILLFY6GP3VCPA/>`__.
       - Use arm64 macOS or 64-bit Windows instead.
+    * - Connectivity and interoperability with Oracle Database and Oracle Client libraries older than version 19 is deprecated and will be removed in a future version of python-oracledb. Production use, and availability of database and client software, is detailed in `Release Schedule of Current Database Releases <https://support.oracle.com/epmos/faces/ DocumentDisplay?id=742060.1>`__.
+      - Upgrade the database and client library versions.
 
 .. list-table-with-summary:: Deprecated in python-oracledb 3.0
     :header-rows: 1

doc/src/api_manual/pipeline.rst

@@ -12,7 +12,8 @@ information about pipelining.
 
 .. note::
 
-    True pipelining is only available when connected to Oracle Database 23ai.
+    True pipelining is only available when connected to Oracle Database version
+    23, or later.
 
 .. versionadded:: 2.4.0
 

doc/src/index.rst

@@ -21,6 +21,7 @@ User Guide
     user_guide/installation.rst
     user_guide/initialization.rst
     user_guide/connection_handling.rst
+    user_guide/authentication_methods.rst
     user_guide/sql_execution.rst
     user_guide/plsql_execution.rst
     user_guide/bind.rst

doc/src/release_notes.rst

@@ -79,9 +79,10 @@ Common Changes
     support
     (`issue 512 <https://github.com/oracle/python-oracledb/issues/512>`__).
 #)  The x86_64 macOS and 32-bit Windows platforms are :ref:`deprecated
-    <deprecations>`. They will be desupported when the `cryptography
-    <https://pypi.org/project/cryptography/>`__ package desupports them, see
-    the `cryptography deprecation announcement <https://mail.python.org/
+    <deprecations>`. They will be desupported in a future release before, or
+    when, the `cryptography <https://pypi.org/project/cryptography/>`__ package
+    desupports them. See the `cryptography deprecation announcement
+    <https://mail.python.org/
     archives/list/python-announce-list@python.org/thread/
     R4BZNC36MSFLKULA74KILLFY6GP3VCPA/>`__.
 #)  Connectivity and interoperability with Oracle Database and Oracle Client
@@ -135,7 +136,7 @@ Common Changes
 
 #)  Pre-built binaries are now being created for Python 3.14. Note this Python
     version is currently in release candidate phase.
-#)  Added support for Oracle Database 23ai :ref:`Sessionless Transactions
+#)  Added support for Oracle Database 23.6 :ref:`Sessionless Transactions
     <sessionlesstxns>`.
 #)  Changes to :ref:`data frame <dataframeformat>` support:
 
@@ -166,7 +167,7 @@ Common Changes
     - Fixed bug when fetching numeric data with precision that exceeds 38 as
       decimal data.
     - Fixed bug when fetching large amounts of data in one round-trip when
-      using asyncio with Oracle Database versions before 23ai.
+      using asyncio with Oracle Database 21c and earlier.
 
     Note the data frame support in python-oracledb 3.3 is a pre-release, and
     may change in a future version.
@@ -193,8 +194,8 @@ Thin Mode Changes
     closed connection
     (`issue 482 <https://github.com/oracle/python-oracledb/issues/482>`__).
 #)  Fixed bug when connecting with asyncio using the parameter ``https_proxy``.
-#)  Fixed bug when fetching LOBs with asyncio from databases prior to Oracle
-    Database 23ai
+#)  Fixed bug when fetching LOBs with asyncio from Oracle Database 21c and
+    earlier
     (`issue 500 <https://github.com/oracle/python-oracledb/issues/500>`__).
 #)  Fixed regression when connecting where only the host specified by the
     ``https_proxy`` parameter can successfully perform name resolution.
@@ -243,7 +244,7 @@ Common Changes
       (`issue 505 <https://github.com/oracle/python-oracledb/issues/505>`__).
 
 #)  Added parameter ``pool_name`` to connection and pool creation methods to
-    support Oracle Database 23ai multi-pool :ref:`drcp`.
+    support Oracle Database 23.4 multi-pool :ref:`drcp`.
 #)  :ref:`GitHub Action <installghactions>` workflow updates:
 
     - Use GitHub Arm Linux runner for builds. Supplied by wojiushixiaobai
@@ -705,13 +706,13 @@ oracledb `2.4.0 <https://github.com/oracle/python-oracledb/compare/v2.3.0...v2.4
 Thin Mode Changes
 +++++++++++++++++
 
-#)  Added support for Oracle Database 23ai :ref:`statement pipelining
+#)  Added support for Oracle Database 23.4 :ref:`statement pipelining
     <pipelining>`.
 #)  Fixed bug resulting in a segfault when a closed cursor is bound as a REF
     CURSOR
     (`issue 368 <https://github.com/oracle/python-oracledb/issues/368>`__).
-#)  Fixed bug resulting in an inability to connect to Oracle Database 23ai
-    instances which have fast authentication disabled.
+#)  Fixed bug resulting in an inability to connect to Oracle Database version
+    23 instances which have fast authentication disabled.
 #)  Fixed error message when idle time is exceeded by a connection. The error
     ``DPY-4033: the database closed the connection because the connection's
     idle time has been exceeded`` is now raised when this situation is
@@ -787,7 +788,7 @@ Thick Mode Changes
 Common Changes
 ++++++++++++++
 
-#)  Added support for Oracle Database 23ai
+#)  Added support for Oracle Database 23.5
     :ref:`BINARY vector format <binaryformat>`.
 #)  Replaced integer constants for
     :ref:`connection authorization modes <connection-authorization-modes>`,
@@ -888,12 +889,12 @@ Thin Mode Changes
 #)  Fixed bug that would cause an internal error to be raised when attempting
     to close a connection that has been forcibly closed by the database.
 #)  Internal change: further efforts to tighten code looking for the end of a
-    database request made to Oracle Database 23ai.
+    database request made to Oracle Database version 23.
 
 Common Changes
 ++++++++++++++
 
-#)  Added support for Oracle Database 23ai columns of type :ref:`VECTOR
+#)  Added support for Oracle Database 23.4 columns of type :ref:`VECTOR
     <vectors>`.
 #)  Added support for columns of type INTERVAL YEAR TO MONTH which can be
     represented in Python by instances of the new
@@ -962,7 +963,7 @@ oracledb `2.1.0 <https://github.com/oracle/python-oracledb/compare/v2.0.1...v2.1
 Thin Mode Changes
 +++++++++++++++++
 
-#)  Oracle Database 23ai feature support:
+#)  Oracle Database version 23 feature support:
 
     - Added support for
       :ref:`implicit connection pooling with DRCP and PRCP <implicitconnpool>`,
@@ -1010,8 +1011,8 @@ Thin Mode Changes
 Thick Mode Changes
 ++++++++++++++++++
 
-#)  Added support for internal use of JSON in SODA with Oracle Client 23. This
-    allows for seamless transfer of extended data types.
+#)  Added support for internal use of JSON in SODA with Oracle Client version
+    23. This allows for seamless transfer of extended data types.
 #)  Fixed bug when calling :meth:`SodaDoc.getContent()` for SODA documents
     that do not contain JSON.
 #)  Corrected support for Oracle Sharding.
@@ -1031,7 +1032,7 @@ Common Changes
     returned by SODA in Oracle Database 23.4 and later in the ``_id``
     attribute of documents stored in native collections.
 #)  Added support for columns of type VECTOR usable with a limited
-    availability release of Oracle Database 23.
+    availability release of Oracle Database version 23.
 #)  Errors raised when calling :meth:`Cursor.executemany()` with PL/SQL now
     have the :data:`oracledb._Error.offset` attribute populated with the last
     iteration that succeeded
@@ -1126,8 +1127,8 @@ Thin Mode Changes
 #)  Added parameter :data:`ConnectParams.ssl_context` to modify the SSL context
     used when connecting via TLS
     (`issue 259 <https://github.com/oracle/python-oracledb/issues/259>`__).
-#)  Added support for an Oracle Database 23ai JSON feature allowing field names
-    with more than 255 UTF-8 encoded bytes.
+#)  Added support for an Oracle Database version 23 JSON feature allowing
+    fieldnames with more than 255 UTF-8 encoded bytes.
 #)  Added support for the ``FAILOVER`` clause in full connect descriptors.
 #)  Fixed bug in detecting the current time zone
     (`issue 257 <https://github.com/oracle/python-oracledb/issues/257>`__).
@@ -1137,8 +1138,8 @@ Thin Mode Changes
     multiple line comments with multiple asterisks before the closing slash.
 #)  A more meaningful error is raised when the wrong type of data is passed to
     :meth:`LOB.write()`.
-#)  Internal change to support an Oracle Database 23ai JSON feature improving
-    JSON storage usage.
+#)  Internal change to support an Oracle Database version 23 JSON feature
+    improving JSON storage usage.
 #)  Internal change to ensure that all connections in a pool have been closed
     gracefully before the pool is closed.
 #)  Internal changes to improve handling of the network protocol between
@@ -1175,8 +1176,9 @@ Common Changes
     17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ and `annotations
     <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-1AC16117-
     BBB6-4435-8794-2B99F8F68052>`__ associated with columns that are being
-    fetched. SQL domains and annotations require Oracle Database 23ai. If using
-    python-oracledb Thick mode, Oracle Client 23ai is also required.
+    fetched. SQL domains and annotations require Oracle Database version 23,
+    or later. If using python-oracledb Thick mode, Oracle Client version 23,
+    or later, is also required.
 #)  Added parameter ``data`` to :meth:`Connection.createlob()` to allow data to
     be written at LOB creation time.
 #)  Added type :data:`~oracledb.DB_TYPE_XMLTYPE` to represent data of type
@@ -1196,7 +1198,7 @@ Common Changes
 #)  Errors that have entries in the
     :ref:`troubleshooting documentation <troubleshooting>` now have links to
     that documentation shown in the message text.
-#)  Fixed bug with binding boolean values with Oracle Database 23ai
+#)  Fixed bug with binding boolean values with Oracle Database version 23
     (`issue 263 <https://github.com/oracle/python-oracledb/issues/263>`__).
 #)  Fixed bug with getting unknown attributes from :ref:`Oracle Object
     <dbobject>` instances.
@@ -1266,9 +1268,9 @@ oracledb `1.4.0 <https://github.com/oracle/python-oracledb/compare/v1.3.2...v1.4
 Thin Mode Changes
 +++++++++++++++++
 
-#)  Added support for an Oracle Database 23ai feature that can improve the
-    performance of connection creation by reducing the number of round trips
-    required to create the second and subsequent connections to the same
+#)  Added support for an Oracle Database version 23 feature that can improve
+    the performance of connection creation by reducing the number of round
+    trips required to create the second and subsequent connections to the same
     database.
 #)  Added support for shrinking the connection pool back to the specified
     minimum size when the pool is idle for :data:`ConnectionPool.timeout`
@@ -1280,13 +1282,13 @@ Thin Mode Changes
     created. The default connection class will be of the form ``DPY:`` followed
     by a 16-byte unique identifier converted to base64 encoding.
 #)  Changed internal connection feature negotiation for more accurate Oracle
-    Database 23ai support.
+    Database version 23 support.
 #)  Added support for sending a generated connection identifier to the
     database used for tracing. An application specific prefix is prepended to
     this value if specified via a new ``connection_id_prefix`` parameter when
     creating standalone connections or connection pools.
 #)  Added URL to the Oracle Database Error Help Portal in Oracle Database
-    error messages similar to when Thick mode uses Oracle Client 23ai.
+    error messages similar to when Thick mode uses Oracle Client version 23.
 #)  Added support for the ``ORA_SDTZ`` environment variable used to set the
     session time zone used by the database.
 #)  Fixed bug when a dynamically sized connection pool is created with an
@@ -1360,8 +1362,8 @@ Common Changes
     same value as the SQL expression
     ``sys_context('userenv', 'instance_name')``.
 #)  Added support for relational queries on the underlying tables of SODA
-    collections created in Oracle Database 23ai if they contain JSON documents
-    with embedded OIDs.
+    collections created in Oracle Database version 23 if they contain JSON
+    documents with embedded OIDs.
 #)  Automatically retry a query if the error ``ORA-00932: inconsistent data
     types`` is raised (which can occur if a table or view is recreated with a
     data type that is incompatible with the column's previous data type).
@@ -1392,7 +1394,7 @@ Thin Mode Changes
 #)  Fixed bug which could cause a redirect loop with improperly configured
     listener redirects.
 #)  Fixed bug when executing PL/SQL with a large number of binds.
-#)  Fixed bug when using DRCP with Oracle Database 23ai.
+#)  Fixed bug when using DRCP with Oracle Database version 23
 
 Thick Mode Changes
 ++++++++++++++++++
@@ -1420,8 +1422,8 @@ Thin Mode Changes
 
 #)  Improved performance of regular expressions used for parsing SQL
     (`issue 172 <https://github.com/oracle/python-oracledb/issues/172>`__).
-#)  Fixed bug with Oracle Database 23ai when SQL is executed after first being
-    parsed.
+#)  Fixed bug with Oracle Database version 23 when SQL is executed after first
+    being parsed.
 #)  Fixed bug when :data:`ConnectionPool.timeout` is not *None* when creating a
     connection pool
     (`issue 166 <https://github.com/oracle/python-oracledb/issues/166>`__).

doc/src/user_guide/appendix_a.rst

@@ -169,7 +169,7 @@ For more details see :ref:`driverdiff` and :ref:`upgrading83`.
       - Yes
       - Yes
       - Yes
-    * - Oracle Database 23ai Implicit Connection Pooling with :ref:`DRCP <drcp>` and PRCP (see :ref:`implicitconnpool`)
+    * - Oracle Database version 23 Implicit Connection Pooling with :ref:`DRCP <drcp>` and PRCP (see :ref:`implicitconnpool`)
       - Yes
       - Yes
       - No
@@ -249,7 +249,7 @@ For more details see :ref:`driverdiff` and :ref:`upgrading83`.
       - Yes
       - No
       - No
-    * - Oracle Database 23ai JSON-Relational Duality Views (see :ref:`jsondualityviews`)
+    * - Oracle Database version 23 JSON-Relational Duality Views (see :ref:`jsondualityviews`)
       - Yes
       - Yes
       - No
@@ -309,7 +309,7 @@ For more details see :ref:`driverdiff` and :ref:`upgrading83`.
       - Yes
       - No
       - No
-    * - Oracle Database 23ai Pipelining (see :ref:`pipelining`)
+    * - Oracle Database version 23 Pipelining (see :ref:`pipelining`)
       - Yes
       - No
       - No
@@ -325,7 +325,7 @@ For more details see :ref:`driverdiff` and :ref:`upgrading83`.
       - Yes
       - Yes
       - Yes
-    * - Oracle Database 23ai Sessionless Transactions (see :ref:`sessionlesstxns`)
+    * - Oracle Database version 23 Sessionless Transactions (see :ref:`sessionlesstxns`)
       - Yes
       - Yes
       - No
@@ -401,7 +401,7 @@ example when binding numeric values.
       - :data:`~oracledb.DB_TYPE_DATE`
       - datetime.date, datetime.datetime
       - No relevant notes
-    * - BOOLEAN (PL/SQL and Oracle Database 23ai SQL)
+    * - BOOLEAN (PL/SQL and Oracle Database version 23 SQL)
       - :data:`~oracledb.DB_TYPE_BOOLEAN`
       - Any type convertible to bool
       - No relevant notes

doc/src/user_guide/aq.rst

@@ -48,7 +48,7 @@ types which are detailed below.
         Array enqueuing and dequeuing is not supported for JSON payloads.
     * - JMS
       - Supported
-      - Supported for single and array message enqueuing and dequeuing when using Oracle Client 19c (or later) and Oracle Database 23ai.
+      - Supported for single and array message enqueuing and dequeuing when using Oracle Client 19 (or later) and Oracle Database version 23 (or later).
 
 **Usage Notes**
 

doc/src/user_guide/asyncio.rst

@@ -381,7 +381,8 @@ about Oracle Database Pipelining.
 
 .. note::
 
-    True pipelining only occurs when you are connected to Oracle Database 23ai.
+    True pipelining only occurs when you are connected to Oracle Database
+    version 23, or later.
 
     When you connect to an older database, operations are sequentially
     executed by python-oracledb. Each operation concludes before the next is