Improve handling of metadata.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -64,6 +64,7 @@ Common Changes
 #)  Fixed bug where some :ref:`DbObject <dbobjecttype>` attributes for database
     objects defined using ANSI names (including FLOAT and REAL) may have shown
     as integers.
+#)  Internal change: improve handling of metadata.
 
 
 oracledb 2.5.0 (November 2024)

src/oracledb/base_impl.pxd

@@ -38,10 +38,20 @@ from cpython cimport array
 ctypedef unsigned char char_type
 
 cdef enum:
-    NUM_TYPE_FLOAT = 0
-    NUM_TYPE_INT = 1
-    NUM_TYPE_DECIMAL = 2
-    NUM_TYPE_STR = 3
+    PY_TYPE_NUM_ARRAY = 13
+    PY_TYPE_NUM_BOOL = 4
+    PY_TYPE_NUM_BYTES = 10
+    PY_TYPE_NUM_DATETIME = 7
+    PY_TYPE_NUM_DECIMAL = 14
+    PY_TYPE_NUM_FLOAT = 2
+    PY_TYPE_NUM_INT = 3
+    PY_TYPE_NUM_OBJECT = 9
+    PY_TYPE_NUM_ORACLE_CURSOR = 6
+    PY_TYPE_NUM_ORACLE_INTERVAL_YM = 12
+    PY_TYPE_NUM_ORACLE_LOB = 1
+    PY_TYPE_NUM_ORACLE_OBJECT = 11
+    PY_TYPE_NUM_STR = 5
+    PY_TYPE_NUM_TIMEDELTA = 8
 
 cdef enum:
     DB_TYPE_NUM_MIN = 2000
@@ -211,6 +221,7 @@ cdef class DbType:
         str _ora_name
         uint8_t _ora_type_num
         uint8_t _csfrm
+        uint8_t _default_py_type_num
 
     @staticmethod
     cdef DbType _from_num(uint32_t num)
@@ -270,7 +281,7 @@ cdef class Buffer:
     cdef object parse_interval_ds(self, const uint8_t* ptr)
     cdef object parse_interval_ym(self, const uint8_t* ptr)
     cdef object parse_oracle_number(self, const uint8_t* ptr,
-                                    ssize_t num_bytes, int preferred_num_type)
+                                    ssize_t num_bytes, uint8_t py_type_num)
     cdef object read_binary_double(self)
     cdef object read_binary_float(self)
     cdef object read_binary_integer(self)
@@ -280,7 +291,7 @@ cdef class Buffer:
     cdef object read_interval_ds(self)
     cdef object read_interval_ym(self)
     cdef int read_int32be(self, int32_t *value) except -1
-    cdef object read_oracle_number(self, int preferred_num_type)
+    cdef object read_oracle_number(self, uint8_t py_type_num)
     cdef const char_type* read_raw_bytes(self, ssize_t num_bytes) except NULL
     cdef int read_raw_bytes_and_length(self, const char_type **ptr,
                                        ssize_t *num_bytes) except -1
@@ -416,6 +427,34 @@ cdef class VectorEncoder(GrowableBuffer):
     cdef int encode(self, array.array value) except -1
 
 
+cdef class OracleMetadata:
+    cdef:
+        readonly str name
+        readonly DbType dbtype
+        readonly BaseDbObjectTypeImpl objtype
+        readonly int8_t precision
+        readonly int8_t scale
+        readonly uint32_t max_size
+        readonly uint32_t buffer_size
+        readonly bint nulls_allowed
+        readonly bint is_json
+        readonly bint is_oson
+        readonly str domain_schema
+        readonly str domain_name
+        readonly dict annotations
+        readonly uint32_t vector_dimensions
+        readonly uint8_t vector_format
+        readonly uint8_t vector_flags
+        uint8_t _py_type_num
+
+    cdef int _finalize_init(self) except -1
+    cdef OracleMetadata copy(self)
+    @staticmethod
+    cdef OracleMetadata from_type(object typ)
+    @staticmethod
+    cdef OracleMetadata from_value(object value)
+
+
 cdef class ConnectParamsNode:
     cdef:
         public bint source_route
@@ -571,8 +610,8 @@ cdef class BaseConnImpl:
         ssize_t _oson_max_fname_size
         bint _allow_bind_str_to_lob
 
-    cdef object _check_value(self, DbType dbtype, BaseDbObjectTypeImpl objtype,
-                             object value, bint* is_ok)
+    cdef object _check_value(self, OracleMetadata type_info, object value,
+                             bint* is_ok)
     cdef BaseCursorImpl _create_cursor_impl(self)
 
 
@@ -599,7 +638,7 @@ cdef class BaseCursorImpl:
         public object rowfactory
         public bint scrollable
         public bint set_input_sizes
-        public list fetch_info_impls
+        public list fetch_metadata
         public list fetch_vars
         public list fetch_var_impls
         public list bind_vars
@@ -626,8 +665,8 @@ cdef class BaseCursorImpl:
     cdef int _close(self, bint in_del) except -1
     cdef BaseVarImpl _create_fetch_var(self, object conn, object cursor,
                                        object type_handler, bint
-                                       uses_fetch_info, ssize_t pos,
-                                       FetchInfoImpl fetch_info)
+                                       uses_metadata, ssize_t pos,
+                                       OracleMetadata metadata)
     cdef object _create_row(self)
     cdef BaseVarImpl _create_var_impl(self, object conn)
     cdef int _fetch_rows(self, object cursor) except -1
@@ -645,49 +684,21 @@ cdef class BaseCursorImpl:
     cdef int bind_one(self, object cursor, object parameters) except -1
 
 
-cdef class FetchInfoImpl:
-    cdef:
-        readonly int16_t precision
-        readonly int16_t scale
-        readonly uint32_t buffer_size
-        readonly uint32_t size
-        readonly bint nulls_allowed
-        readonly str name
-        readonly DbType dbtype
-        readonly BaseDbObjectTypeImpl objtype
-        readonly bint is_json
-        readonly bint is_oson
-        readonly str domain_schema
-        readonly str domain_name
-        readonly dict annotations
-        readonly uint32_t vector_dimensions
-        readonly uint8_t vector_format
-        readonly uint8_t vector_flags
-
-
 cdef class BaseVarImpl:
     cdef:
-        readonly str name
-        readonly int16_t precision
-        readonly int16_t scale
+        readonly OracleMetadata metadata
         readonly uint32_t num_elements
         readonly object inconverter
         readonly object outconverter
-        readonly uint32_t size
-        readonly uint32_t buffer_size
         readonly bint bypass_decode
         readonly str encoding_errors
         readonly bint is_array
-        readonly bint nulls_allowed
         readonly bint convert_nulls
         public uint32_t num_elements_in_array
-        readonly DbType dbtype
-        readonly BaseDbObjectTypeImpl objtype
         bytes _encoding_error_bytes
         const char *_encoding_errors
         BaseConnImpl _conn_impl
-        int _preferred_num_type
-        FetchInfoImpl _fetch_info
+        OracleMetadata _fetch_metadata
         list _values
         bint _is_value_set
 
@@ -702,11 +713,11 @@ cdef class BaseVarImpl:
     cdef object _get_scalar_value(self, uint32_t pos)
     cdef int _on_reset_bind(self, uint32_t num_rows) except -1
     cdef int _resize(self, uint32_t new_size) except -1
-    cdef int _set_scalar_value(self, uint32_t pos, object value) except -1
+    cdef int _set_metadata_from_type(self, object typ) except -1
+    cdef int _set_metadata_from_value(self, object value,
+                                      bint is_plsql) except -1
     cdef int _set_num_elements_in_array(self, uint32_t num_elements) except -1
-    cdef int _set_type_info_from_type(self, object typ) except -1
-    cdef int _set_type_info_from_value(self, object value,
-                                       bint is_plsql) except -1
+    cdef int _set_scalar_value(self, uint32_t pos, object value) except -1
 
 
 cdef class BaseLobImpl:
@@ -722,26 +733,14 @@ cdef class BaseDbObjectTypeImpl:
         readonly list attrs
         readonly bint is_collection
         readonly dict attrs_by_name
-        readonly DbType element_dbtype
-        readonly BaseDbObjectTypeImpl element_objtype
-        readonly int8_t element_precision
-        readonly int8_t element_scale
-        readonly uint32_t element_max_size
+        readonly OracleMetadata element_metadata
         readonly BaseConnImpl _conn_impl
-        int _element_preferred_num_type
 
     cpdef str _get_fqn(self)
 
 
-cdef class BaseDbObjectAttrImpl:
-    cdef:
-        readonly str name
-        readonly DbType dbtype
-        readonly BaseDbObjectTypeImpl objtype
-        readonly int8_t precision
-        readonly int8_t scale
-        readonly uint32_t max_size
-        int _preferred_num_type
+cdef class BaseDbObjectAttrImpl(OracleMetadata):
+    pass
 
 
 cdef class BaseDbObjectImpl:
@@ -875,12 +874,11 @@ cdef class PipelineOpResultImpl:
         readonly list rows
         readonly object error
         readonly object warning
-        readonly list fetch_info_impls
+        readonly list fetch_metadata
 
     cdef int _capture_err(self, Exception exc) except -1
 
 
-cdef int get_preferred_num_type(int16_t precision, int8_t scale)
 cdef uint16_t decode_uint16be(const char_type *buf)
 cdef uint32_t decode_uint32be(const char_type *buf)
 cdef uint16_t decode_uint16le(const char_type *buf)

src/oracledb/base_impl.pyx

@@ -59,8 +59,6 @@ import sys
 
 cydatetime.import_datetime()
 
-include "impl/base/types.pyx"
-
 # Python types used by the driver
 cdef type PY_TYPE_ASYNC_CURSOR
 cdef type PY_TYPE_ASYNC_LOB
@@ -90,17 +88,14 @@ cdef const char* DRIVER_INSTALLATION_URL = \
 cdef const char* ENCODING_UTF8 = "UTF-8"
 cdef const char* ENCODING_UTF16 = "UTF-16BE"
 
-cdef int get_preferred_num_type(int16_t precision, int8_t scale):
-    if scale == 0 or (scale == -127 and precision == 0):
-        return NUM_TYPE_INT
-    return NUM_TYPE_FLOAT
-
 # protocols registered with the library
 REGISTERED_PROTOCOLS = {}
 
+include "impl/base/types.pyx"
 include "impl/base/constants.pxi"
 include "impl/base/decoders.pyx"
 include "impl/base/encoders.pyx"
+include "impl/base/metadata.pyx"
 include "impl/base/utils.pyx"
 include "impl/base/defaults.pyx"
 include "impl/base/pipeline.pyx"

src/oracledb/cursor.py

@@ -262,9 +262,7 @@ def description(self) -> tuple:
         """
         self._verify_open()
         if self._impl.is_query(self):
-            return [
-                FetchInfo._from_impl(i) for i in self._impl.fetch_info_impls
-            ]
+            return [FetchInfo._from_impl(i) for i in self._impl.fetch_metadata]
 
     @property
     def fetchvars(self) -> list:

src/oracledb/dbobject.py

@@ -347,11 +347,11 @@ def element_type(self) -> Union["DbObjectType", DbType]:
         object type; otherwise, it will be one of the database type constants.
         """
         if self._element_type is None:
-            if self._impl.element_objtype is not None:
-                typ_impl = self._impl.element_objtype
+            if self._impl.element_metadata.objtype is not None:
+                typ_impl = self._impl.element_metadata.objtype
                 self._element_type = DbObjectType._from_impl(typ_impl)
             else:
-                self._element_type = self._impl.element_dbtype
+                self._element_type = self._impl.element_metadata.dbtype
         return self._element_type
 
     def newobject(self, value: Sequence = None) -> DbObject:

src/oracledb/fetch_info.py

@@ -114,8 +114,8 @@ def display_size(self) -> Union[int, None]:
         """
         Returns the display size of the column.
         """
-        if self._impl.size > 0:
-            return self._impl.size
+        if self._impl.max_size > 0:
+            return self._impl.max_size
         dbtype = self._impl.dbtype
         if (
             dbtype is DB_TYPE_DATE
@@ -158,7 +158,7 @@ def internal_size(self) -> Union[int, None]:
         """
         Returns the size in bytes of the column.
         """
-        if self._impl.size > 0:
+        if self._impl.max_size > 0:
             return self._impl.buffer_size
 
     @property

src/oracledb/impl/base/bind_var.pyx

@@ -47,14 +47,14 @@ cdef class BindVar:
         if isinstance(value, list):
             if len(value) != 2:
                 errors._raise_err(errors.ERR_WRONG_ARRAY_DEFINITION)
-            var_impl._set_type_info_from_type(value[0])
+            var_impl._set_metadata_from_type(value[0])
             var_impl.num_elements = value[1]
             var_impl.is_array = True
         elif isinstance(value, int):
-            var_impl.dbtype = DB_TYPE_VARCHAR
-            var_impl.size = value
+            var_impl._set_metadata_from_type(str)
+            var_impl.metadata.max_size = value
         else:
-            var_impl._set_type_info_from_type(value)
+            var_impl._set_metadata_from_type(value)
         var_impl._finalize_init()
         self.var_impl = var_impl
         if isinstance(value, PY_TYPE_DB_OBJECT_TYPE):
@@ -68,20 +68,23 @@ cdef class BindVar:
         """
         cdef:
             bint is_plsql = cursor_impl._is_plsql()
+            OracleMetadata metadata
             BaseVarImpl var_impl
         var_impl = cursor_impl._create_var_impl(conn)
         if not isinstance(value, list):
             var_impl.num_elements = num_elements
-            var_impl._set_type_info_from_value(value, is_plsql)
+            var_impl._set_metadata_from_value(value, is_plsql)
         else:
             var_impl.is_array = True
             var_impl.num_elements = max(num_elements, len(value))
             for element in value:
                 if element is not None:
-                    var_impl._set_type_info_from_value(element, is_plsql)
-            if var_impl.dbtype is None:
-                var_impl.dbtype = DB_TYPE_VARCHAR
-                var_impl.size = 1
+                    var_impl._set_metadata_from_value(element, is_plsql)
+            if var_impl.metadata is None:
+                metadata = OracleMetadata.__new__(OracleMetadata)
+                metadata.dbtype = DB_TYPE_VARCHAR
+                metadata.max_size = 1
+                var_impl.metadata = metadata
         var_impl._finalize_init()
         self.var_impl = var_impl