Support for enhanced metadata.

Author: anthony-tuininga

doc/src/api_manual/connection.rst

@@ -756,14 +756,19 @@ Connection Attributes
 
     This read-write attribute specifies a method called for each column that is
     going to be fetched from any cursor associated with this connection. The
-    method signature is handler(cursor, name, defaultType, length, precision,
-    scale) and the return value is expected to be a variable object or None in
-    which case a default variable object will be created. If this attribute is
-    None, the default behavior will take place for all columns fetched from
-    cursors.
+    method signature is ``handler(cursor, metadata)`` and the return value is
+    expected to be a :ref:`variable object<varobj>` or None in which case a
+    default variable object will be created. If this attribute is None, the
+    default behavior will take place for all columns fetched from cursors.
 
     See :ref:`outputtypehandlers`.
 
+    .. versionchanged:: 1.4
+
+        The method signature was changed. The previous signature
+        ``handler(cursor, name, default_type, length, precision, scale)`` will
+        still work but is deprecated and will be removed in a future version.
+
     .. note::
 
         This attribute is an extension to the DB API definition.

doc/src/api_manual/cursor.rst

@@ -496,14 +496,10 @@ Cursor Attributes
 
 .. data:: Cursor.description
 
-    This read-only attribute is a sequence of 7-item sequences. Each of these
-    sequences contains information describing one result column: (name, type,
-    display_size, internal_size, precision, scale, null_ok). This attribute
-    will be None for operations that do not return rows or if the cursor has
-    not had an operation invoked via the :meth:`~Cursor.execute()` method yet.
-
-    The type will be one of the :ref:`database type constants <dbtypes>`
-    defined at the module level.
+    This read-only attribute is a sequence of :ref:`FetchInfo<fetchinfoobj>`
+    objects. This attribute will be None for operations that do not return rows
+    or if the cursor has not had an operation invoked via the
+    :meth:`~Cursor.execute()` method yet.
 
 .. attribute:: Cursor.fetchvars
 
@@ -541,13 +537,19 @@ Cursor Attributes
 
     This read-write attribute specifies a method called for each column that is
     to be fetched from this cursor. The method signature is
-    handler(cursor, name, defaultType, length, precision, scale) and the return
-    value is expected to be a variable object or None in which case a default
-    variable object will be created. If this attribute is None, then the default
+    handler(cursor, metadata) and the return value is expected to be a
+    :ref:`variable object<varobj>` or None in which case a default variable
+    object will be created. If this attribute is None, then the default
     behavior will take place for all columns fetched from this cursor.
 
     See :ref:`outputtypehandlers`.
 
+    .. versionchanged:: 1.4
+
+        The method signature was changed. The previous signature
+        handler(cursor, name, default_type, length, precision, scale) will
+        still work but is deprecated and will be removed in a future version.
+
     .. note::
 
         This attribute is an extension to the DB API definition.

doc/src/api_manual/deprecations.rst

@@ -9,6 +9,19 @@ when they were first deprecated and a comment on what should be used instead,
 if applicable. The most recent deprecations are listed first.
 
 
+.. list-table-with-summary:: Deprecated in python-oracledb 1.4
+    :header-rows: 1
+    :class: wy-table-responsive
+    :summary: The first column, Name, displays the deprecated API name. The second column, Comments, includes information about when the API was deprecated and what API to use, if applicable.
+    :name: _deprecations_1_4
+
+    * - Name
+      - Comments
+    * - Output type handler with arguments
+        ``handler(cursor, name, default_type, length, precision, scale)``
+      - Replace with ``handler(cursor, metadata)``. See
+        :ref:`outputtypehandlers`.
+
 .. list-table-with-summary:: Deprecated in python-oracledb 1.0
     :header-rows: 1
     :class: wy-table-responsive

doc/src/api_manual/fetch_info.rst

@@ -0,0 +1,71 @@
+.. _fetchinfoobj:
+
+**********************
+API: FetchInfo Objects
+**********************
+
+These objects are created internally when a query is executed. They are found
+in the sequence :data:`Cursor.description`. For compatibility with the Python
+Database API, this object behaves as a 7-tuple containing the values for the
+attributes ``name``, ``type_code``, ``display_size``, ``internal_size``,
+``precision``, ``scale``, and ``null_ok`` in that order. For example, if
+``fetch_info`` is of type FetchInfo, then ``fetch_info[2]`` is the same as
+``fetch_info.display_size``.
+
+.. note::
+
+    This object is an extension the DB API.
+
+FetchInfo Attributes
+====================
+
+.. attribute:: FetchInfo.display_size
+
+    This read-only attribute returns the display size of the column as mandated
+    by the Python Database API.
+
+.. attribute:: FetchInfo.internal_size
+
+    This read-only attribute returns the internal size of the column as
+    mandated by the Python Database API.
+
+.. attribute:: FetchInfo.is_json
+
+    This read-only attribute returns whether the column is known to contain
+    JSON data. This will be ``true`` when the type code is
+    ``oracledb.DB_TYPE_JSON`` as well as when an "IS JSON" constraint is
+    enabled on LOB and VARCHAR2 columns.
+
+.. attribute:: FetchInfo.name
+
+    This read-only attribute returns the name of the column as mandated by the
+    Python Database API.
+
+.. attribute:: FetchInfo.null_ok
+
+    This read-only attribute returns whether nulls are allowed in the column as
+    mandated by the Python Database API.
+
+.. attribute:: FetchInfo.precision
+
+    This read-only attribute returns the precision of the column as mandated by
+    the Python Database API.
+
+.. attribute:: FetchInfo.scale
+
+    This read-only attribute returns the scale of the column as mandated by
+    the Python Database API.
+
+.. attribute:: FetchInfo.type
+
+    This read-only attribute returns the type of the column. This will be an
+    :ref:`Oracle Object Type <dbobjecttype>` if the column contains Oracle
+    objects; otherwise, it will be one of the :ref:`database type constants
+    <dbtypes>` defined at the module level.
+
+
+.. attribute:: FetchInfo.type_code
+
+    This read-only attribute returns the type of the column as mandated by the
+    Python Database API. The type will be one of the :ref:`database type
+    constants <dbtypes>` defined at the module level.

doc/src/index.rst

@@ -66,6 +66,7 @@ API Manual
     api_manual/connection_pool.rst
     api_manual/pool_params.rst
     api_manual/cursor.rst
+    api_manual/fetch_info.rst
     api_manual/variable.rst
     api_manual/subscription.rst
     api_manual/lob.rst

doc/src/release_notes.rst

@@ -70,6 +70,15 @@ Thick Mode Changes
 Common Changes
 ++++++++++++++
 
+#)  Replaced fixed 7-tuple for the cursor metadata found in
+    :data:`Cursor.description` with a class which provides additional
+    information such as the database object type and whether the column
+    contains JSON data.
+#)  Changed the signature for output type handlers to
+    ``handler(cursor, metadata)`` where the ``metadata`` parameter is a
+    :ref:`FetchInfo<fetchinfoobj>` object containing the same information found
+    in :data:`Cursor.description`. The original signature for output type
+    handlers is deprecated and will be removed in some future version.
 #)  Added support for fetching VARCHAR2 and LOB columns which contain JSON (and
     have the "IS JSON" check constraint enabled) in the same way as columns of
     type JSON (which requires Oracle Database 21c or higher) are fetched. In

doc/src/user_guide/globalization.rst

@@ -133,16 +133,16 @@ To convert numbers:
     locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8')
 
     # simple naive conversion
-    def type_handler1(cursor, name, default_type, size, precision, scale):
-        if default_type == oracledb.DB_TYPE_NUMBER:
+    def type_handler1(cursor, metadata):
+        if metadata.type_code is oracledb.DB_TYPE_NUMBER:
             return cursor.var(oracledb.DB_TYPE_VARCHAR, arraysize=cursor.arraysize,
-                    outconverter=lambda v: v.replace('.', ','))
+                              outconverter=lambda v: v.replace('.', ','))
 
     # locale conversion
-    def type_handler2(cursor, name, default_type, size, precision, scale):
-        if default_type == oracledb.DB_TYPE_NUMBER:
-            return cursor.var(default_type, arraysize=cursor.arraysize,
-                    outconverter=lambda v: locale.format_string("%g", v))
+    def type_handler2(cursor, metadata):
+        if metadata.type_code is oracledb.DB_TYPE_NUMBER:
+            return cursor.var(metadata.type_code, arraysize=cursor.arraysize,
+                              outconverter=lambda v: locale.format_string("%g", v))
 
 
     connection = oracledb.connect(user="hr", password=userpwd,
@@ -186,16 +186,16 @@ To convert dates:
     locale_date_format = locale.nl_langinfo(locale.D_T_FMT)
 
     # simple naive conversion
-    def type_handler3(cursor, name, default_type, size, precision, scale):
-        if default_type == oracledb.DB_TYPE_DATE:
-            return cursor.var(default_type, arraysize=cursor.arraysize,
-                    outconverter=lambda v: v.strftime("%Y-%m-%d %H:%M:%S"))
+    def type_handler3(cursor, metadata):
+        if metadata.type_code is oracledb.DB_TYPE_DATE:
+            return cursor.var(metadata.type_code, arraysize=cursor.arraysize,
+                              outconverter=lambda v: v.strftime("%Y-%m-%d %H:%M:%S"))
 
     # locale conversion
     def type_handler4(cursor, name, default_type, size, precision, scale):
-        if default_type == oracledb.DB_TYPE_DATE:
-            return cursor.var(default_type, arraysize=cursor.arraysize,
-                    outconverter=lambda v: v.strftime(locale_date_format))
+        if metadata.type_code is oracledb.DB_TYPE_DATE:
+            return cursor.var(metadata.type_code, arraysize=cursor.arraysize,
+                              outconverter=lambda v: v.strftime(locale_date_format))
 
 
     connection = oracledb.connect(user="hr", password=userpwd,

doc/src/user_guide/lob_data.rst

@@ -107,12 +107,12 @@ handler:
 
 .. code-block:: python
 
-    def output_type_handler(cursor, name, default_type, size, precision, scale):
-        if default_type == oracledb.DB_TYPE_CLOB:
+    def output_type_handler(cursor, metadata):
+        if metadata.type_code is oracledb.DB_TYPE_CLOB:
             return cursor.var(oracledb.DB_TYPE_LONG, arraysize=cursor.arraysize)
-        if default_type == oracledb.DB_TYPE_BLOB:
+        if metadata.type_code is oracledb.DB_TYPE_BLOB:
             return cursor.var(oracledb.DB_TYPE_LONG_RAW, arraysize=cursor.arraysize)
-        if default_type == oracledb.DB_TYPE_NCLOB:
+        if metadata.type_code is oracledb.DB_TYPE_NCLOB:
             return cursor.var(oracledb.DB_TYPE_LONG_NVARCHAR, arraysize=cursor.arraysize)
 
     connection.outputtypehandler = output_type_handler

doc/src/user_guide/sql_execution.rst

@@ -312,10 +312,10 @@ cursors created by that connection will have their fetch type handling changed.
 The output type handler is expected to be a function with the following
 signature::
 
-    handler(cursor, name, default_type, size, precision, scale)
+    handler(cursor, metadata)
 
-The parameters are the same information as the query column metadata found in
-:attr:`Cursor.description`.
+The metadata parameter is a :ref:`FetchInfo object<fetchinfoobj>`, which is the
+same value found in :attr:`Cursor.description`.
 
 The function is called once for each column that is going to be
 fetched. The function is expected to return a :ref:`variable object <varobj>`
@@ -326,8 +326,8 @@ For example:
 
 .. code-block:: python
 
-    def output_type_handler(cursor, name, default_type, size, precision, scale):
-        if default_type == oracledb.DB_TYPE_NUMBER:
+    def output_type_handler(cursor, metadata):
+        if metadata.type_code is oracledb.DB_TYPE_NUMBER:
             return cursor.var(oracledb.DB_TYPE_VARCHAR, arraysize=cursor.arraysize)
 
 This output type handler is called once for each column in the SELECT query.
@@ -375,15 +375,15 @@ For example:
 
 .. code-block:: python
 
-    def output_type_handler(cursor, name, default_type, size, precision, scale):
+    def output_type_handler(cursor, metadata):
 
         def out_converter(d):
             if isinstance(d, str):
                 return f"{d} was a string"
             else:
                 return f"{d} was not a string"
 
-        if default_type == oracledb.DB_TYPE_NUMBER:
+        if metadata.type_code is oracledb.DB_TYPE_NUMBER:
             return cursor.var(oracledb.DB_TYPE_VARCHAR,
                  arraysize=cursor.arraysize, outconverter=out_converter)
 
@@ -456,15 +456,15 @@ An example showing an :ref:`output type handler <outputtypehandlers>`, an
 
 .. code-block:: python
 
-    def output_type_handler(cursor, name, default_type, size, precision, scale):
+    def output_type_handler(cursor, metadata):
 
         def out_converter(d):
             if type(d) is str:
                 return f"{d} was a string"
             else:
                 return f"{d} was not a string"
 
-        if default_type == oracledb.DB_TYPE_NUMBER:
+        if metadata.type_code is oracledb.DB_TYPE_NUMBER:
             return cursor.var(oracledb.DB_TYPE_VARCHAR,
                 arraysize=cursor.arraysize, outconverter=out_converter)
 
@@ -532,8 +532,8 @@ to use an :ref:`output type handler <outputtypehandlers>` do the conversion.
 
     import decimal
 
-    def number_to_decimal(cursor, name, default_type, size, precision, scale):
-        if default_type == oracledb.DB_TYPE_NUMBER:
+    def number_to_decimal(cursor, metadata):
+        if metadata.type_code is oracledb.DB_TYPE_NUMBER:
             return cursor.var(decimal.Decimal, arraysize=cursor.arraysize)
 
     cursor.outputtypehandler = number_to_decimal
@@ -824,9 +824,8 @@ The following sample demonstrates how to use this feature:
     .. code-block:: python
 
         # define output type handler
-        def return_strings_as_bytes(cursor, name, default_type, size,
-                                    precision, scale):
-            if default_type == oracledb.DB_TYPE_VARCHAR:
+        def return_strings_as_bytes(cursor, metadata):
+            if metadata.type_code is oracledb.DB_TYPE_VARCHAR:
                 return cursor.var(str, arraysize=cursor.arraysize,
                                   bypass_decode=True)
 
@@ -900,9 +899,10 @@ columns:
 
 .. code-block:: python
 
-    def output_type_handler(cursor, name, default_type, size, precision, scale):
-        if default_type == oracledb.DB_TYPE_VARCHAR:
-            return cursor.var(default_type, size, arraysize=cursor.arraysize,
+    def output_type_handler(cursor, metadata):
+        if metadata.type_code is oracledb.DB_TYPE_VARCHAR:
+            return cursor.var(metadata.type_code, size,
+                              arraysize=cursor.arraysize,
                               encoding_errors="replace")
 
     cursor.outputtypehandler = output_type_handler

samples/generic_row_factory.py

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2016, 2022, Oracle and/or its affiliates.
+# Copyright (c) 2016, 2023, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -52,7 +52,7 @@ def execute(self, statement, args=None):
         if prepare_needed:
             description = self.description
             if description is not None:
-                names = [d[0] for d in description]
+                names = [d.name for d in description]
                 self.rowfactory = collections.namedtuple("GenericQuery", names)
         return result