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

@@ -47,6 +47,7 @@
 
 if TYPE_CHECKING:
     from mssql_python.row import Row
+    from mssql_python.cursor import SQLTypeCode
 
 # Add SQL_WMETADATA constant for metadata decoding configuration
 SQL_WMETADATA: int = -99  # Special flag for column name decoding
@@ -923,7 +924,9 @@ def cursor(self) -> Cursor:
         logger.debug("cursor: Cursor created successfully - total_cursors=%d", len(self._cursors))
         return cursor
 
-    def add_output_converter(self, sqltype: int, func: Callable[[Any], Any]) -> None:
+    def add_output_converter(
+        self, sqltype: "Union[int, SQLTypeCode, type]", func: Callable[[Any], Any]
+    ) -> None:
         """
         Register an output converter function that will be called whenever a value
         with the given SQL type is read from the database.
@@ -936,32 +939,47 @@ def add_output_converter(self, sqltype: int, func: Callable[[Any], Any]) -> None
         vulnerabilities. This API should never be exposed to untrusted or external input.
 
         Args:
-            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).
+            sqltype (int, SQLTypeCode, or type): 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) or Python types (e.g., str, int) for
+                          backward compatibility.
             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
-                            will be a bytes object.
+                            then the parameter passed to the function will be None. For string/binary
+                            columns, the value will be bytes (UTF-16LE encoded for strings). For other
+                            types (int, decimal.Decimal, datetime, etc.), the value will be the native
+                            Python object.
 
         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
-            if hasattr(self._conn, "add_output_converter"):
+            # Only forward int type codes to native layer; Python type keys are handled
+            # only in our Python-side dictionary
+            if isinstance(sqltype, int) and hasattr(self._conn, "add_output_converter"):
                 self._conn.add_output_converter(sqltype, func)
         logger.info(f"Added output converter for SQL type {sqltype}")
 
-    def get_output_converter(self, sqltype: Union[int, type]) -> Optional[Callable[[Any], Any]]:
+    def get_output_converter(
+        self, sqltype: "Union[int, SQLTypeCode, type]"
+    ) -> Optional[Callable[[Any], Any]]:
         """
         Get the output converter function for the specified SQL type.
 
         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, SQLTypeCode, or type): The SQL type value to get the converter for.
+                Also accepts SQLTypeCode objects (from cursor.description), which are
+                automatically converted to their integer type code, or Python types
+                (e.g., str, int) for backward compatibility.
 
         Returns:
             callable or None: The converter function or None if no converter is registered
@@ -970,26 +988,43 @@ 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
+        original_sqltype = sqltype
+        if hasattr(sqltype, "type_code"):
+            sqltype = sqltype.type_code
         with self._converters_lock:
-            return self._output_converters.get(sqltype)
-
-    def remove_output_converter(self, sqltype: Union[int, type]) -> None:
+            result = self._output_converters.get(sqltype)
+            # If int lookup misses for an SQLTypeCode, also try its python_type
+            # to preserve backward compatibility with converters registered by Python type
+            if result is None and hasattr(original_sqltype, "python_type"):
+                result = self._output_converters.get(original_sqltype.python_type)
+            return result
+
+    def remove_output_converter(self, sqltype: "Union[int, SQLTypeCode, type]") -> None:
         """
         Remove the output converter function for the specified SQL type.
 
         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, SQLTypeCode, or type): The SQL type value to remove the converter for.
+                Also accepts SQLTypeCode objects (from cursor.description) or Python types
+                (e.g., str, int) for backward compatibility.
 
         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]
                 # Pass to the underlying connection if native implementation supports it
-                if hasattr(self._conn, "remove_output_converter"):
+                # Only forward int type codes to native layer; Python type keys are handled
+                # only in our Python-side dictionary
+                if isinstance(sqltype, int) and hasattr(self._conn, "remove_output_converter"):
                     self._conn.remove_output_converter(sqltype)
         logger.info(f"Removed output converter for SQL type {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