FIX: Cursor.describe invalid data

CHANGELOG.md

@@ -7,22 +7,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ## [Unreleased]
 
 ### Added
+
 - New feature: Support for macOS and Linux.
 - Documentation: Added API documentation in the Wiki.
+- Added support for SQL Server spatial data types (geography, geometry, hierarchyid) via SQL_SS_UDT type handling.
+- Added `SQLTypeCode` class for dual-compatible type codes in `cursor.description`.
 
 ### Changed
+
 - Improved error handling in the connection module.
+- Enhanced `cursor.description[i][1]` to return `SQLTypeCode` objects that compare equal to both SQL type integers and Python types, maintaining full backwards compatibility while aligning with DB-API 2.0.
 
 ### Fixed
+
 - Bug fix: Resolved issue with connection timeout.
+- Fixed `cursor.description` type handling for better DB-API 2.0 compliance (Issue #352).
+
+### SQLTypeCode Usage
+
+The `type_code` field in `cursor.description` now returns `SQLTypeCode` objects that support both comparison styles:
+
+```python
+cursor.execute("SELECT id, name FROM users")
+desc = cursor.description
+
+# Style 1: Compare with Python types (backwards compatible with pandas, etc.)
+if desc[0][1] == int:
+    print("Integer column")
+
+# Style 2: Compare with SQL type codes (DB-API 2.0 compliant)
+from mssql_python.constants import ConstantsDDBC as sql_types
+if desc[0][1] == sql_types.SQL_INTEGER.value:  # or just == 4
+    print("Integer column")
+
+# Get the raw SQL type code
+type_code = int(desc[0][1])  # Returns 4 for SQL_INTEGER
+```
 
 ## [1.0.0-alpha] - 2025-02-24
 
 ### Added
+
 - Initial release of the mssql-python driver for SQL Server.
 
 ### Changed
+
 - N/A
 
 ### Fixed
-- N/A
+
+- N/A

mssql_python/__init__.py

@@ -59,7 +59,7 @@
 from .connection_string_builder import _ConnectionStringBuilder
 
 # Cursor Objects
-from .cursor import Cursor
+from .cursor import Cursor, SQLTypeCode
 
 # Logging Configuration (Simplified single-level DEBUG system)
 from .logging import logger, setup_logging, driver_logger

mssql_python/connection.py

@@ -939,6 +939,7 @@ def add_output_converter(self, sqltype: int, func: Callable[[Any], Any]) -> None
             sqltype (int): The integer SQL type value to convert, which can be one of the
                           defined standard constants (e.g. SQL_VARCHAR) or a database-specific
                           value (e.g. -151 for the SQL Server 2008 geometry data type).
+                          Also accepts SQLTypeCode objects (from cursor.description).
             func (callable): The converter function which will be called with a single parameter,
                             the value, and should return the converted value. If the value is NULL
                             then the parameter passed to the function will be None, otherwise it
@@ -947,6 +948,9 @@ def add_output_converter(self, sqltype: int, func: Callable[[Any], Any]) -> None
         Returns:
             None
         """
+        # Handle SQLTypeCode objects (from cursor.description) by converting to int
+        if hasattr(sqltype, "type_code"):
+            sqltype = sqltype.type_code
         with self._converters_lock:
             self._output_converters[sqltype] = func
             # Pass to the underlying connection if native implementation supports it
@@ -961,7 +965,9 @@ def get_output_converter(self, sqltype: Union[int, type]) -> Optional[Callable[[
         Thread-safe implementation that protects the converters dictionary with a lock.
 
         Args:
-            sqltype (int or type): The SQL type value or Python type to get the converter for
+            sqltype (int or type): The SQL type value or Python type to get the converter for.
+                Also accepts SQLTypeCode objects (from cursor.description), which are
+                automatically converted to their integer type code.
 
         Returns:
             callable or None: The converter function or None if no converter is registered
@@ -970,6 +976,10 @@ def get_output_converter(self, sqltype: Union[int, type]) -> Optional[Callable[[
             ⚠️ The returned converter function will be executed on database values. Only use
             converters from trusted sources.
         """
+        # Handle SQLTypeCode objects (from cursor.description) by converting to int
+        # SQLTypeCode has a type_code attribute and supports int() conversion
+        if hasattr(sqltype, "type_code"):
+            sqltype = sqltype.type_code
         with self._converters_lock:
             return self._output_converters.get(sqltype)
 
@@ -980,11 +990,15 @@ def remove_output_converter(self, sqltype: Union[int, type]) -> None:
         Thread-safe implementation that protects the converters dictionary with a lock.
 
         Args:
-            sqltype (int or type): The SQL type value to remove the converter for
+            sqltype (int or type): The SQL type value to remove the converter for.
+                Also accepts SQLTypeCode objects (from cursor.description).
 
         Returns:
             None
         """
+        # Handle SQLTypeCode objects (from cursor.description) by converting to int
+        if hasattr(sqltype, "type_code"):
+            sqltype = sqltype.type_code
         with self._converters_lock:
             if sqltype in self._output_converters:
                 del self._output_converters[sqltype]

mssql_python/constants.py

@@ -114,7 +114,12 @@ class ConstantsDDBC(Enum):
     SQL_FETCH_ABSOLUTE = 5
     SQL_FETCH_RELATIVE = 6
     SQL_FETCH_BOOKMARK = 8
+    # NOTE: The following SQL Server-specific type constants MUST stay in sync with
+    # the corresponding values in mssql_python/pybind/ddbc_bindings.cpp
     SQL_DATETIMEOFFSET = -155
+    SQL_SS_TIME2 = -154  # SQL Server TIME(n) type
+    SQL_SS_UDT = -151  # SQL Server User-Defined Types (geometry, geography, hierarchyid)
+    SQL_SS_XML = -152  # SQL Server XML type
     SQL_C_SS_TIMESTAMPOFFSET = 0x4001
     SQL_SCOPE_CURROW = 0
     SQL_BEST_ROWID = 1

mssql_python/cursor.py

@@ -48,6 +48,110 @@
 MONEY_MAX: decimal.Decimal = decimal.Decimal("922337203685477.5807")
 
 
+class SQLTypeCode:
+    """
+    A dual-compatible type code that compares equal to both SQL type integers and Python types.
+
+    This class maintains backwards compatibility with code that checks
+    `cursor.description[i][1] == str` while also supporting DB-API 2.0
+    compliant code that checks `cursor.description[i][1] == -9`.
+
+    Examples:
+        >>> type_code = SQLTypeCode(-9, str)
+        >>> type_code == str  # Backwards compatible with pandas, etc.
+        True
+        >>> type_code == -9   # DB-API 2.0 compliant
+        True
+        >>> int(type_code)    # Get the raw SQL type code
+        -9
+    """
+
+    # SQL type code to Python type mapping (class-level cache)
+    _type_map = None
+
+    def __init__(self, type_code: int, python_type: type = None):
+        self.type_code = type_code
+        # If python_type not provided, look it up from the mapping
+        if python_type is None:
+            python_type = self._get_python_type(type_code)
+        self.python_type = python_type
+
+    @classmethod
+    def _get_type_map(cls):
+        """Lazily build the SQL to Python type mapping."""
+        if cls._type_map is None:
+            cls._type_map = {
+                ddbc_sql_const.SQL_CHAR.value: str,
+                ddbc_sql_const.SQL_VARCHAR.value: str,
+                ddbc_sql_const.SQL_LONGVARCHAR.value: str,
+                ddbc_sql_const.SQL_WCHAR.value: str,
+                ddbc_sql_const.SQL_WVARCHAR.value: str,
+                ddbc_sql_const.SQL_WLONGVARCHAR.value: str,
+                ddbc_sql_const.SQL_INTEGER.value: int,
+                ddbc_sql_const.SQL_REAL.value: float,
+                ddbc_sql_const.SQL_FLOAT.value: float,
+                ddbc_sql_const.SQL_DOUBLE.value: float,
+                ddbc_sql_const.SQL_DECIMAL.value: decimal.Decimal,
+                ddbc_sql_const.SQL_NUMERIC.value: decimal.Decimal,
+                ddbc_sql_const.SQL_DATE.value: datetime.date,
+                ddbc_sql_const.SQL_TIMESTAMP.value: datetime.datetime,
+                ddbc_sql_const.SQL_TIME.value: datetime.time,
+                ddbc_sql_const.SQL_SS_TIME2.value: datetime.time,  # SQL Server TIME(n)
+                # ODBC 3.x date/time type codes
+                ddbc_sql_const.SQL_TYPE_DATE.value: datetime.date,
+                ddbc_sql_const.SQL_TYPE_TIME.value: datetime.time,
+                ddbc_sql_const.SQL_TYPE_TIMESTAMP.value: datetime.datetime,
+                ddbc_sql_const.SQL_TYPE_TIMESTAMP_WITH_TIMEZONE.value: datetime.datetime,
+                ddbc_sql_const.SQL_BIT.value: bool,
+                ddbc_sql_const.SQL_TINYINT.value: int,
+                ddbc_sql_const.SQL_SMALLINT.value: int,
+                ddbc_sql_const.SQL_BIGINT.value: int,
+                ddbc_sql_const.SQL_BINARY.value: bytes,
+                ddbc_sql_const.SQL_VARBINARY.value: bytes,
+                ddbc_sql_const.SQL_LONGVARBINARY.value: bytes,
+                ddbc_sql_const.SQL_GUID.value: uuid.UUID,
+                ddbc_sql_const.SQL_SS_UDT.value: bytes,
+                ddbc_sql_const.SQL_SS_XML.value: str,  # SQL Server XML type (-152)
+                ddbc_sql_const.SQL_DATETIME2.value: datetime.datetime,
+                ddbc_sql_const.SQL_SMALLDATETIME.value: datetime.datetime,
+                ddbc_sql_const.SQL_DATETIMEOFFSET.value: datetime.datetime,
+            }
+        return cls._type_map
+
+    @classmethod
+    def _get_python_type(cls, sql_code: int) -> type:
+        """Get the Python type for a SQL type code."""
+        return cls._get_type_map().get(sql_code, str)
+
+    def __eq__(self, other):
+        """Compare equal to both Python types and SQL integer codes."""
+        if isinstance(other, type):
+            return self.python_type == other
+        if isinstance(other, int):
+            return self.type_code == other
+        if isinstance(other, SQLTypeCode):
+            return self.type_code == other.type_code
+        return False
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    # Instances are intentionally unhashable because __eq__ allows
+    # comparisons to both Python types and integer SQL codes, and
+    # there is no single hash value that can be consistent with both.
+    __hash__ = None
+
+    def __int__(self):
+        return self.type_code
+
+    def __repr__(self):
+        type_name = self.python_type.__name__ if self.python_type else "Unknown"
+        return f"SQLTypeCode({self.type_code}, {type_name})"
+
+    def __str__(self):
+        return str(self.type_code)
+
+
 class Cursor:  # pylint: disable=too-many-instance-attributes,too-many-public-methods
     """
     Represents a database cursor, which is used to manage the context of a fetch operation.
@@ -142,6 +246,9 @@ def __init__(self, connection: "Connection", timeout: int = 0) -> None:
         )
         self.messages = []  # Store diagnostic messages
 
+        # Store raw column metadata for converter lookups
+        self._column_metadata = None
+
     def _is_unicode_string(self, param: str) -> bool:
         """
         Check if a string contains non-ASCII characters.
@@ -756,6 +863,7 @@ def close(self) -> None:
             self.hstmt = None
             logger.debug("SQLFreeHandle succeeded")
         self._clear_rownumber()
+        self._column_metadata = None  # Clear metadata to prevent memory leaks
         self.closed = True
 
     def _check_closed(self) -> None:
@@ -942,8 +1050,12 @@ def _initialize_description(self, column_metadata: Optional[Any] = None) -> None
         """Initialize the description attribute from column metadata."""
         if not column_metadata:
             self.description = None
+            self._column_metadata = None  # Clear metadata too
             return
 
+        # Store raw metadata for converter map building
+        self._column_metadata = column_metadata
+
         description = []
         for _, col in enumerate(column_metadata):
             # Get column name - lowercase it if the lowercase flag is set
@@ -954,10 +1066,13 @@ def _initialize_description(self, column_metadata: Optional[Any] = None) -> None
                 column_name = column_name.lower()
 
             # Add to description tuple (7 elements as per PEP-249)
+            # Use SQLTypeCode for backwards-compatible type_code that works with both
+            # `desc[1] == str` (pandas) and `desc[1] == -9` (DB-API 2.0)
+            sql_type = col["DataType"]
             description.append(
                 (
                     column_name,  # name
-                    self._map_data_type(col["DataType"]),  # type_code
+                    SQLTypeCode(sql_type),  # type_code - dual compatible
                     None,  # display_size
                     col["ColumnSize"],  # internal_size
                     col["ColumnSize"],  # precision - should match ColumnSize
@@ -975,18 +1090,17 @@ def _build_converter_map(self):
         """
         if (
             not self.description
+            or not self._column_metadata
             or not hasattr(self.connection, "_output_converters")
             or not self.connection._output_converters
         ):
             return None
 
         converter_map = []
 
-        for desc in self.description:
-            if desc is None:
-                converter_map.append(None)
-                continue
-            sql_type = desc[1]
+        for col_meta in self._column_metadata:
+            # Use the raw SQL type code from metadata, not the mapped Python type
+            sql_type = col_meta["DataType"]
             converter = self.connection.get_output_converter(sql_type)
             # If no converter found for the SQL type, try the WVARCHAR converter as a fallback
             if converter is None:
@@ -1022,41 +1136,6 @@ def _get_column_and_converter_maps(self):
 
         return column_map, converter_map
 
-    def _map_data_type(self, sql_type):
-        """
-        Map SQL data type to Python data type.
-
-        Args:
-            sql_type: SQL data type.
-
-        Returns:
-            Corresponding Python data type.
-        """
-        sql_to_python_type = {
-            ddbc_sql_const.SQL_INTEGER.value: int,
-            ddbc_sql_const.SQL_VARCHAR.value: str,
-            ddbc_sql_const.SQL_WVARCHAR.value: str,
-            ddbc_sql_const.SQL_CHAR.value: str,
-            ddbc_sql_const.SQL_WCHAR.value: str,
-            ddbc_sql_const.SQL_FLOAT.value: float,
-            ddbc_sql_const.SQL_DOUBLE.value: float,
-            ddbc_sql_const.SQL_DECIMAL.value: decimal.Decimal,
-            ddbc_sql_const.SQL_NUMERIC.value: decimal.Decimal,
-            ddbc_sql_const.SQL_DATE.value: datetime.date,
-            ddbc_sql_const.SQL_TIMESTAMP.value: datetime.datetime,
-            ddbc_sql_const.SQL_TIME.value: datetime.time,
-            ddbc_sql_const.SQL_BIT.value: bool,
-            ddbc_sql_const.SQL_TINYINT.value: int,
-            ddbc_sql_const.SQL_SMALLINT.value: int,
-            ddbc_sql_const.SQL_BIGINT.value: int,
-            ddbc_sql_const.SQL_BINARY.value: bytes,
-            ddbc_sql_const.SQL_VARBINARY.value: bytes,
-            ddbc_sql_const.SQL_LONGVARBINARY.value: bytes,
-            ddbc_sql_const.SQL_GUID.value: uuid.UUID,
-            # Add more mappings as needed
-        }
-        return sql_to_python_type.get(sql_type, str)
-
     @property
     def rownumber(self) -> int:
         """
@@ -2756,7 +2835,13 @@ def __del__(self):
         Destructor to ensure the cursor is closed when it is no longer needed.
         This is a safety net to ensure resources are cleaned up
         even if close() was not called explicitly.
-        If the cursor is already closed, it will not raise an exception during cleanup.
+
+        Error handling:
+        This destructor performs best-effort cleanup only. Any exceptions raised
+        while closing the cursor are caught and, when possible, logged instead of
+        being propagated, because raising from __del__ can cause hard-to-debug
+        failures during garbage collection. During interpreter shutdown, logging
+        may be suppressed if the logging subsystem is no longer available.
         """
         if "closed" not in self.__dict__ or not self.closed:
             try: