Doc tweaks.

Author: anthony-tuininga

doc/src/api_manual/async_connection.rst

@@ -147,7 +147,7 @@ AsyncConnection Methods
 
     .. note::
 
-        The data frame support in python-oracledb 3.1 is a pre-release and may
+        The data frame support in python-oracledb 3.2 is a pre-release and may
         change in a future version.
 
     .. versionadded:: 3.0.0
@@ -175,7 +175,7 @@ AsyncConnection Methods
 
     .. note::
 
-        The data frame support in python-oracledb 3.1 is a pre-release and may
+        The data frame support in python-oracledb 3.2 is a pre-release and may
         change in a future version.
 
     .. versionadded:: 3.0.0

doc/src/api_manual/connection.rst

@@ -140,7 +140,7 @@ Connection Methods
 
     .. note::
 
-        The data frame support in python-oracledb 3.1 is a pre-release and may
+        The data frame support in python-oracledb 3.2 is a pre-release and may
         change in a future version.
 
     .. dbapimethodextension::
@@ -172,7 +172,7 @@ Connection Methods
 
     .. note::
 
-        The data frame support in python-oracledb 3.1 is a pre-release and may
+        The data frame support in python-oracledb 3.2 is a pre-release and may
         change in a future version.
 
     .. dbapimethodextension::

doc/src/api_manual/dataframe.rst

@@ -13,7 +13,7 @@ from Oracle Database types to Arrow data types.
 
 .. note::
 
-    The data frame support in python-oracledb 3.1 is a pre-release and may
+    The data frame support in python-oracledb 3.2 is a pre-release and may
     change in a future version.
 
 .. _oracledataframeobj:

doc/src/release_notes.rst

@@ -55,6 +55,13 @@ Common Changes
     support Oracle Database 23ai multi-pool :ref:`drcp`.
 #)  Added Instance Principal authentication support when using
     :ref:`OCI Cloud Native Authentication <cloudnativeauthoci>`.
+#)  Improvements to :ref:`data frames <dataframeformat>`:
+
+    - Fixed date handling to match PyArrow's and avoid localization issues
+      (`issue 499 <https://github.com/oracle/python-oracledb/issues/499>`__).
+    - Fixed bug on Windows when fetching dates prior to 1970 and after 2038
+      (`issue 483 <https://github.com/oracle/python-oracledb/issues/483>`__).
+
 #)  Use GitHub Arm Linux runner for builds. Supplied by wojiushixiaobai
     (`PR 496 <https://github.com/oracle/python-oracledb/pull/496>`__).
 #)  Fix bug with GitHub build action merge artifacts step
@@ -66,14 +73,6 @@ Common Changes
     parameter "min". Previously python-oracledb Thin mode did not raise an
     error and python-oracledb Thick mode raised the exception
     ``ORA-24413: Invalid number of sessions specified``.
-#)  Improvements to :ref:`data frames <dataframeformat>`:
-
-    - Fixed date handling to match PyArrow's and avoid localization issues
-      (`issue 499 <https://github.com/oracle/python-oracledb/issues/499>`__).
-
-    - Fixed bug on Windows when fetching dates prior to 1970 and after 2038
-      (`issue 483 <https://github.com/oracle/python-oracledb/issues/483>`__).
-
 #)  Improved the test suite and documentation.
 
 
@@ -980,14 +979,12 @@ Common Changes
     <https://github.com/oracle/python-oracledb/issues/250>`__).
 #)  Added properties :data:`FetchInfo.domain_schema`,
     :data:`FetchInfo.domain_name` and :data:`FetchInfo.annotations` for the
-    `SQL domain <https://docs.oracle.com/en/database/oracle/oracle-database/
-    23/sqlrf/create-domain.html#GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__
-    and `annotations <https://docs.oracle.com/en/database/oracle/
-    oracle-database/23/sqlrf/annotations_clause.html#
-    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.
+    `SQL domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
+    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.
 #)  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

doc/src/user_guide/bind.rst

@@ -823,16 +823,16 @@ will accept them but there will be no processing benefit.
 It is not uncommon for SQL statements to have low hundreds of
 versions. Sometimes this is expected and not a result of any issue. To
 determine the reason, find the SQL identifier of the statement and then query
-the Oracle Database view `V$SQL_SHARED_CURSOR <https://docs.oracle.com/en/
-database/oracle/oracle-database/23/refrn/V-SQL_SHARED_CURSOR.html>`__.
+the Oracle Database view `V$SQL_SHARED_CURSOR <https://www.oracle.com/pls/topic
+/lookup?ctx=dblatest&id=GUID-4993A6DE-5658-4745-B43E-F5AD9DB8DCCC>`__.
 
 The SQL identifier of a statement can be found in Oracle Database views like
-`V$SQLAREA <https://docs.oracle.com/en/database/oracle/oracle-database/23/
-refrn/V-SQLAREA.html>`__ after you have run a statement, or you can find it
-*before* you execute the statement by using the `DBMS_SQL_TRANSLATOR.SQL_ID()
-<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-DFFB611B-853A-
-434E-808D-D713671C3AA4>`__ function. Make sure to pass in exactly the same SQL
-text, including the same whitespace:
+`V$SQLAREA <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
+09D5169F-EE9E-4297-8E01-8D191D87BDF7>`__ after you have run a statement, or you
+can find it *before* you execute the statement by using the
+`DBMS_SQL_TRANSLATOR.SQL_ID() <https://www.oracle.com/pls/topic/lookup?ctx=
+dblatest&id=GUID-DFFB611B-853A-434E-808D-D713671C3AA4>`__ function. Make sure
+to pass in exactly the same SQL text, including the same whitespace:
 
 .. code-block:: python
 

doc/src/user_guide/connection_handling.rst

@@ -32,32 +32,28 @@ Oracle Client and Oracle Database communicate.
 There are two ways to create a connection to Oracle Database using
 python-oracledb:
 
-*  **Standalone connections**: :ref:`Standalone connections <standaloneconnection>`
-   are useful when the application needs a single connection to a database.
-   Connections are created by calling :meth:`oracledb.connect()`.
-
-*  **Pooled connections**: :ref:`Connection pooling <connpooling>` is important for
-   performance when applications frequently connect and disconnect from the database.
-   Pools support Oracle's :ref:`high availability <highavailability>` features and are
-   recommended for applications that must be reliable.  Small pools can also be
-   useful for applications that want a few connections available for infrequent
-   use.  Pools are created with :meth:`oracledb.create_pool()` at application
-   initialization time, and then :meth:`ConnectionPool.acquire()` can be called to
-   obtain a connection from a pool.
+* **Standalone connections**: :ref:`Standalone connections
+  <standaloneconnection>` are useful when the application needs a single
+  connection to a database.  Connections are created by calling
+  :meth:`oracledb.connect()`. For :ref:`asyncio <asyncio>`, use
+  :meth:`oracledb.connect_async()` instead, see :ref:`connasync`.
+
+* **Pooled connections**: :ref:`Connection pooling <connpooling>` is important
+  for performance when applications frequently connect and disconnect from the
+  database.  Pools support Oracle's :ref:`high availability <highavailability>`
+  features and are recommended for applications that must be reliable.  Small
+  pools can also be useful for applications that want a few connections
+  available for infrequent use.  Pools are created with
+  :meth:`oracledb.create_pool()` at application initialization time, and then
+  :meth:`ConnectionPool.acquire()` can be called to obtain a connection from a
+  pool. For :ref:`asyncio <asyncio>`, use :meth:`oracledb.create_pool_async()`
+  and :meth:`AsyncConnectionPool.acquire()` instead, see :ref:`asyncconnpool`.
 
 Many connection behaviors can be controlled by python-oracledb connection
 options.  Other settings can be configured in :ref:`optnetfiles` or in
 :ref:`optclientfiles`.  These include limiting the amount of time that opening
 a connection can take, or enabling :ref:`network encryption <netencrypt>`.
 
-.. note::
-
-       Creating a connection in python-oracledb Thin mode always requires a
-       connection string, or the database host name and service name, to be
-       specified.  The Thin mode cannot use "bequeath" connections and does not
-       reference Oracle environment variables ``ORACLE_SID``, ``TWO_TASK``,
-       or ``LOCAL``.
-
 .. _standaloneconnection:
 
 Standalone Connections
@@ -287,6 +283,14 @@ For more information about naming methods, see the `Database Net Services
 Administrator's Guide
 <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-E5358DEA-D619-4B7B-A799-3D2F802500F1>`__.
 
+.. note::
+
+    Creating a connection in python-oracledb Thin mode always requires a
+    connection string, or the database host name and service name, to be
+    specified.  The Thin mode cannot use "bequeath" connections and does not
+    reference Oracle environment variables ``ORACLE_SID``, ``TWO_TASK``,
+    or ``LOCAL``.
+
 .. _easyconnect:
 
 Easy Connect Syntax for Connection Strings
@@ -1883,6 +1887,10 @@ creation calls. If you call :meth:`ConnectParams.parse_connect_string()`, the
 registered protocol hook method will be called but the parameter hook will not
 be.
 
+..
+   Note to doc writers: do not change the following heading because it is used
+   for a link emitted by ldap_hook() in src/oracledb/builtin_hooks.py
+
 .. _ldapconnections:
 
 LDAP Directory Naming
@@ -2061,8 +2069,17 @@ Connection Pooling
 ==================
 
 Connection pooling can significantly improve application performance and
-scalability, allows resource sharing, and lets applications use advanced Oracle
-High Availability features.
+scalability by allowing resource sharing. Pools also let applications use
+optional advanced Oracle High Availability features.
+
+Opening a connection to a database can be expensive: the connection string must
+be parsed, a network connection must be established, the Oracle Database
+network listener needs to be invoked, user authentication must be performed, a
+database server process must be created, and session memory must be allocated
+(and then the process is destroyed when the connection is closed). Connection
+pools remove the overhead of repeatedly opening and closing :ref:`standalone
+connections <standaloneconnection>` by establishing a pool of open connections
+that can be reused throughout the life of an application process.
 
 The pooling solutions available to python-oracledb applications are:
 
@@ -2092,12 +2109,12 @@ The pooling solutions available to python-oracledb applications are:
 
 - `Proxy Resident Connection Pooling (PRCP)
   <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-E0032017-03B1-
-  4F14-AF9B-BCC87C982DA8>`__: This is connection pooling handled by a dedicated
-  mid-tier connection proxy, `CMAN-TDM <https://download.oracle.com/
-  ocomdocs/global/CMAN_TDM_Oracle_DB_Connection_Proxy_for_scalable_
-  apps.pdf>`__.
+  4F14-AF9B-BCC87C982DA8>`__: This is connection pooling handled by Oracle's
+  mid-tier connection proxy solution, `CMAN-TDM <https://download.oracle.com/
+  ocomdocs/global/
+  CMAN_TDM_Oracle_DB_Connection_Proxy_for_scalable_apps.pdf>`__.
 
-  This is useful for applications taking advantage of CMAN-TDM.
+  PRCP is useful for applications taking advantage of CMAN-TDM.
 
 - :ref:`implicitconnpool`: This can add pooling benefits to applications that
   connect when they start, and only close the connection when the application
@@ -2242,6 +2259,11 @@ server process to be released, use :meth:`ConnectionPool.drop()`:
 
         pool.drop(connection)
 
+Avoid doing this unnecessarily because it shrinks the pool. A future
+:meth:`~ConnectionPool.acquire()` call may suffer the overhead of establishing
+a new connection to the database, instead of being able to reuse a connection
+already available in the pool.
+
 Closing a Connection Pool
 +++++++++++++++++++++++++