Added support for explicitly specifying whether to fetch LOBs or decimal

values when performing queries.

Author: anthony-tuininga

doc/src/api_manual/async_connection.rst

@@ -87,6 +87,10 @@ AsyncConnection Methods
 
 .. automethod:: AsyncConnection.fetchall
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_lobs`` and ``fetch_decimals`` parameters were added.
+
 .. automethod:: AsyncConnection.fetch_df_all
 
     See :ref:`dataframeformat` for the supported data types and examples.
@@ -96,6 +100,10 @@ AsyncConnection Methods
         The data frame support in python-oracledb 3.3 is a pre-release and may
         change in a future version.
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_decimals`` parameter was added.
+
     .. versionadded:: 3.0.0
 
 .. automethod:: AsyncConnection.fetch_df_batches
@@ -107,12 +115,24 @@ AsyncConnection Methods
         The data frame support in python-oracledb 3.3 is a pre-release and may
         change in a future version.
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_decimals`` parameter was added.
+
     .. versionadded:: 3.0.0
 
 .. automethod:: AsyncConnection.fetchmany
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_lobs`` and ``fetch_decimals`` parameters were added.
+
 .. automethod:: AsyncConnection.fetchone
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_lobs`` and ``fetch_decimals`` parameters were added.
+
 .. automethod:: AsyncConnection.gettype
 
 .. automethod:: AsyncConnection.is_healthy

doc/src/api_manual/async_cursor.rst

@@ -68,6 +68,10 @@ AsyncCursor Methods
 
 .. automethod:: AsyncCursor.execute
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_lobs`` and ``fetch_decimals`` parameters were added.
+
     .. versionchanged:: 3.3.0
 
         The ``suspend_on_success`` parameter was added.

doc/src/api_manual/connection.rst

@@ -90,6 +90,10 @@ Connection Methods
 
     .. dbapimethodextension::
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_decimals`` parameter was added.
+
     .. versionadded:: 3.0.0
 
 .. automethod:: Connection.fetch_df_batches
@@ -103,6 +107,10 @@ Connection Methods
 
     .. dbapimethodextension::
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_decimals`` parameter was added.
+
     .. versionadded:: 3.0.0
 
 .. automethod:: Connection.getSodaDatabase

doc/src/api_manual/cursor.rst

@@ -69,6 +69,10 @@ Cursor Methods
 
 .. automethod:: Cursor.execute
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_lobs`` and ``fetch_decimals`` parameters were added.
+
     .. versionchanged:: 3.3.0
 
         The ``suspend_on_success`` parameter was added.

doc/src/api_manual/module.rst

@@ -1405,12 +1405,12 @@ Also see the table :ref:`supporteddbtypes`.
 .. data:: DB_TYPE_LONG_NVARCHAR
 
     This constant can be used in output type handlers when fetching NCLOB
-    columns as a string. (Note a type handler is not needed if
-    :ref:`oracledb.defaults.fetch_lobs <defaults>` is set to False).  For IN
-    binds, this constant can be used to create a bind variable in
-    :meth:`Cursor.var()` or via :meth:`Cursor.setinputsizes()`.  The
-    ``DB_TYPE_LONG_NVARCHAR`` value won't be shown in query metadata since it
-    is not a database type.
+    columns as a string.  (Note a type handler is not needed if
+    :ref:`oracledb.defaults.fetch_lobs <defaults>`, or the equivalent execution
+    parameter, is set to *False*).  For IN binds, this constant can be used to
+    create a bind variable in :meth:`Cursor.var()` or via
+    :meth:`Cursor.setinputsizes()`.  The ``DB_TYPE_LONG_NVARCHAR`` value won't
+    be shown in query metadata since it is not a database type.
 
     It will compare equal to the DB API type :data:`STRING`.
 

doc/src/api_manual/pipeline.rst

@@ -48,14 +48,26 @@ Pipeline Methods
 
 .. automethod:: Pipeline.add_fetchall
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_lobs`` and ``fetch_decimals`` parameters were added.
+
 .. automethod:: Pipeline.add_fetchmany
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_lobs`` and ``fetch_decimals`` parameters were added.
+
     .. seealso::
 
         :ref:`roundtrips`, and :ref:`rowlimit`
 
 .. automethod:: Pipeline.add_fetchone
 
+    .. versionchanged:: 3.4.0
+
+        The ``fetch_lobs`` and ``fetch_decimals`` parameters were added.
+
     .. seealso::
 
         :ref:`rowlimit`
@@ -86,6 +98,14 @@ PipelineOp Attributes
 
         :ref:`tuningfetch`
 
+.. autoproperty:: PipelineOp.fetch_decimals
+
+    .. versionadded:: 3.4.0
+
+.. autoproperty:: PipelineOp.fetch_lobs
+
+    .. versionadded:: 3.4.0
+
 .. autoproperty:: PipelineOp.keyword_parameters
 
 .. autoproperty:: PipelineOp.name

doc/src/release_notes.rst

@@ -25,6 +25,13 @@ Thick Mode Changes
 Common Changes
 ++++++++++++++
 
+#)  Added ``fetch_lobs`` and ``fetch_decimals`` parameters where applicable to
+    the methods used for fetching rows or dataframes from the database. Note
+    that for the creation of pipeline operations, if these parameters are not
+    specified then the values of
+    :attr:`oracledb.defaults.fetch_lobs <Defaults.fetch_lobs>` and
+    :attr:`oracledb.defaults.fetch_decimals <Defaults.fetch_decimals>` are now
+    stored with the operation and used during pipeline execution.
 #)  API documentation is now generated from the source code.
 
 

doc/src/user_guide/json_data_type.rst

@@ -412,8 +412,6 @@ for example:
 
 .. code-block:: python
 
-    oracledb.defaults.fetch_lobs = False
-
     cursor.execute("""
         select
             json_arrayagg(
@@ -423,7 +421,8 @@ for example:
             departments d
         where
             department_id < :did""",
-       [50]);
+       [50],
+       fetch_lobs=False)
     j, = cursor.fetchone()
     print(j)
 

doc/src/user_guide/lob_data.rst

@@ -74,16 +74,14 @@ Fetching LOBs as Strings and Bytes
 
 CLOBs and BLOBs smaller than 1 GB can queried from the database directly as
 strings and bytes.  This can be much faster than streaming a :ref:`LOB Object
-<lobobj>`.  Support is enabled by setting the :ref:`Defaults Object
-<defaults>`.
+<lobobj>`.  Support is enabled by setting :attr:`oracledb.defaults.fetch_lobs
+<Defaults.fetch_lobs>`, or by setting the ``fetch_lobs`` parameter at statement
+execution:
 
 .. code-block:: python
 
     import oracledb
 
-    # returns strings or bytes instead of a locator
-    oracledb.defaults.fetch_lobs = False
-
     . . .
 
     id_val = 1
@@ -92,7 +90,7 @@ strings and bytes.  This can be much faster than streaming a :ref:`LOB Object
     cursor.execute("insert into lob_tbl (id, c, b) values (:1, :2, :3)",
                    [id_val, text_data, binary_data])
 
-    cursor.execute("select c, b from lob_tbl where id = :1", [id_val])
+    cursor.execute("select c, b from lob_tbl where id = :1", [id_val], fetch_lobs=False)
     clob_data, blob_data = cursor.fetchone()
     print("CLOB length:", len(clob_data))
     print("CLOB data:", clob_data)
@@ -106,8 +104,7 @@ This displays::
     BLOB length: 16
     BLOB data: b'Some binary data'
 
-An older alternative to using ``oracledb.defaults.fetch_lobs`` is to use a type
-handler:
+An older alternative to using ``fetch_lobs`` is to use a type handler:
 
 .. code-block:: python
 
@@ -124,8 +121,9 @@ handler:
 Streaming LOBs (Read)
 =====================
 
-Without setting ``oracledb.defaults.fetch_lobs`` to False, or without using an
-output type handler, the CLOB and BLOB values are fetched as :ref:`LOB
+Without setting :attr:`oracledb.defaults.fetch_lobs <Defaults.fetch_lobs>` or
+equivalent execution parameter to *False*, or without using an output type
+handler, then the CLOB and BLOB values are fetched as :ref:`LOB
 objects<lobobj>`. The size of the LOB object can be obtained by calling
 :meth:`LOB.size()` and the data can be read by calling :meth:`LOB.read()`:
 

samples/json_blob.py

@@ -105,11 +105,10 @@
 
     # Using JSON_ARRAYAGG to extract a whole relational table as JSON
 
-    oracledb.defaults.fetch_lobs = False
     sql = """select json_arrayagg(
                         json_object('key' is c.id,
                                     'name' is c.json_data)
                         returning clob)
              from CustomersAsBlob c"""
-    for r in cursor.execute(sql):
+    for r in cursor.execute(sql, fetch_lobs=False):
         print(r)