Documentation improvements.

Author: anthony-tuininga

doc/src/api_manual/connect_param.rst

@@ -51,7 +51,7 @@ ConnectParams Methods
         externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \
         edition=None, tag=None, matchanytag=None, config_dir=None, \
         appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, handle=None)
+        connection_id_prefix=None, ssl_context=None, handle=None)
 
     Sets the default values for one or more of the parameters of an empty
     ConnectParams object.  A default will be overriden when a connection string

doc/src/api_manual/cursor.rst

@@ -581,6 +581,9 @@ Cursor Attributes
     The attribute is only used for tuning row fetches from the database.  It
     does not affect data inserts.
 
+    Queries that return LOBs and similar types will never prefetch rows, so the
+    ``prefetchrows`` value is ignored in those cases.
+
     See :ref:`Tuning Fetch Performance <tuningfetch>` for more information.
 
     .. note::

doc/src/api_manual/defaults.rst

@@ -57,10 +57,11 @@ Defaults Attributes
 
 .. attribute:: defaults.fetch_lobs
 
-    When the value of this attribute is True, then queries to LOB columns return
-    LOB locators. When the value of this attribute is False, then strings or bytes
-    are fetched. If LOBs are larger than 1 GB, then this attribute should be set to
-    True and the LOBs should be streamed.  See :ref:`lobdata`.
+    When the value of this attribute is True, then queries to LOB columns
+    return LOB locators. When the value of this attribute is False, then CLOBs
+    and NCLOBs are fetched as strings, and BLOBs are fetched as bytes. If LOBs
+    are larger than 1 GB, then this attribute should be set to True and the
+    LOBs should be streamed.  See :ref:`lobdata`.
 
     An output type handler such as the one previously required in cx_Oracle (see
     `return_lobs_as_strings.py <https://github.com/oracle/python-cx_Oracle/blob/main/samples/

doc/src/api_manual/module.rst

@@ -48,7 +48,7 @@ Oracledb Methods
         edition=None, tag=None, matchanytag=False, \
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, handle=0)
+        connection_id_prefix=None, ssl_context=None, handle=0)
 
     Constructor for creating a connection to the database. Returns a
     :ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -295,13 +295,25 @@ Oracledb Methods
     ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__.  This value
     is only used in the python-oracledb Thin mode.
 
+    The ``ssl_context`` parameter is expected to be an `SSLContext object
+    <https://docs.python.org/3/library/ssl.html#ssl-contexts>`__ which is used
+    for connecting to the database using TLS.  This SSL context will be
+    modified to include the private key or any certificates found in a
+    separately supplied wallet.  This parameter should only be specified if
+    the default SSLContext object cannot be used.  This value is only used in
+    the python-oracledb Thin mode.
+
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
     PowerBuilder) which has already made the connection. The connection thus
     created should *never* be used after the source handle has been closed or
     destroyed. This value is only used in the python-oracledb Thick mode.  It
     should be used with extreme caution. The default value is 0.
 
+    .. versionchanged:: 2.0.0
+
+        The ``ssl_context`` parameter was added.
+
 .. function:: ConnectParams(user=None, proxy_user=None, password=None, \
         newpassword=None, wallet_password=None, access_token=None, host=None, \
         port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \
@@ -314,7 +326,7 @@ Oracledb Methods
         edition=None, tag=None, matchanytag=False, \
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, handle=0)
+        connection_id_prefix=None, ssl_context=None, handle=0)
 
     Contains all the parameters that can be used to establish a connection to
     the database.
@@ -526,11 +538,22 @@ Oracledb Methods
     ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__.  This value
     is only used in the python-oracledb Thin mode.
 
+    The ``ssl_context`` parameter is expected to be an `SSLContext object
+    <https://docs.python.org/3/library/ssl.html#ssl-contexts>`__ which is used
+    for connecting to the database using TLS.  This SSL context will be
+    modified to include the private key or any certificates found in a
+    separately supplied wallet.  This parameter should only be specified if
+    the default SSLContext object cannot be used.  This value is only used in
+    the python-oracledb Thin mode.
+
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
     python-oracledb Thick mode.  It should be used with extreme caution. The
     default value is 0.
 
+    .. versionchanged:: 2.0.0
+
+        The ``ssl_context`` parameter was added.
 
 .. function:: create_pool(dsn=None, pool_class=oracledb.ConnectionPool, \
         params=None, min=1, max=2, increment=1, \
@@ -550,7 +573,7 @@ Oracledb Methods
         edition=None, tag=None, matchanytag=False, \
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, handle=0)
+        connection_id_prefix=None, ssl_context=None, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -844,13 +867,25 @@ Oracledb Methods
     ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__.  This value
     is only used in the python-oracledb Thin mode.
 
+    The ``ssl_context`` parameter is expected to be an `SSLContext object
+    <https://docs.python.org/3/library/ssl.html#ssl-contexts>`__ which is used
+    for connecting to the database using TLS.  This SSL context will be
+    modified to include the private key or any certificates found in a
+    separately supplied wallet.  This parameter should only be specified if
+    the default SSLContext object cannot be used.  This value is only used in
+    the python-oracledb Thin mode.
+
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
     PowerBuilder) which has already made the connection. The connection thus
     created should *never* be used after the source handle has been closed or
     destroyed. This value is only used in the python-oracledb Thick mode. It
     should be used with extreme caution. The deault value is 0.
 
+    .. versionchanged:: 2.0.0
+
+        The ``ssl_context`` parameter was added.
+
     In the python-oracledb Thick mode, connection pooling is handled by
     Oracle's `Session pooling <https://www.oracle.com/pls/topic/lookup?
     ctx=dblatest&id=GUID-F9662FFB-EAEF-495C-96FC-49C6D1D9625C>`__ technology.
@@ -979,7 +1014,7 @@ Oracledb Methods
         edition=None, tag=None, matchanytag=False, \
         config_dir=oracledb.defaults.config_dir, appcontext=[], \
         shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, handle=0)
+        connection_id_prefix=None, ssl_context=None, handle=0)
 
     Creates and returns a :ref:`PoolParams Object <poolparam>`. The object
     can be passed to :meth:`oracledb.create_pool()`.
@@ -1243,11 +1278,23 @@ Oracledb Methods
     ctx=dblatest&id=GUID-B0FC69F9-2EBC-44E8-ACB2-62FBA14ABD5C>`__.  This value
     is only used in the python-oracledb Thin mode.
 
+    The ``ssl_context`` parameter is expected to be an `SSLContext object
+    <https://docs.python.org/3/library/ssl.html#ssl-contexts>`__ which is used
+    for connecting to the database using TLS.  This SSL context will be
+    modified to include the private key or any certificates found in a
+    separately supplied wallet.  This parameter should only be specified if
+    the default SSLContext object cannot be used.  This value is only used in
+    the python-oracledb Thin mode.
+
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
     python-oracledb Thick mode. It should be used with extreme caution. The
     default value is 0.
 
+    .. versionchanged:: 2.0.0
+
+        The ``ssl_context`` parameter was added.
+
 .. function:: Time(hour, minute, second)
 
     Constructs an object holding a time value.

doc/src/api_manual/pool_params.rst

@@ -46,7 +46,7 @@ PoolParams Methods
         externalauth=None, mode=None, disable_oob=None, stmtcachesize=None, \
         edition=None, tag=None, matchanytag=None, config_dir=None, \
         appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-        connection_id_prefix=None, handle=None)
+        connection_id_prefix=None, ssl_context=None, handle=None)
 
   Sets one or more of the parameters.
 

doc/src/user_guide/appendix_a.rst

@@ -214,10 +214,10 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - No - All NLS environment variables are ignored.  Use Python globalization support instead
       - Yes - NLS environment variables are respected except character set in NLS_LANG
       - Yes - NLS environment variables are respected except character set in NLS_LANG
-    * - Row prefetching on first query execute.(see :attr:`prefetchrows`)
-      - Yes
-      - Yes
-      - Yes
+    * - Row prefetching on first query execute (see :attr:`prefetchrows`)
+      - Yes - unless the row contains LOBs or similar types
+      - Yes - unless the row contains LOBs or similar types
+      - Yes - unless the row contains LOBs or similar types
     * - Array fetching for queries (see :attr:`arraysize`)
       - Yes
       - Yes
@@ -318,10 +318,10 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - Yes
       - Yes
       - Yes
-    * - LOB prefetching
-      - No
-      - No - does have LOB length prefetch
-      - No - does have LOB length prefetch
+    * - LOB length prefetching
+      - Yes
+      - Yes
+      - Yes
     * - LOB locator operations such as trim
       - Yes
       - Yes