fix: output converter lookup by SQL type code, not Python type

_build_converter_map looked up converters using desc[1] (the mapped
Python type, e.g. bytes) but add_output_converter registers by SQL
type code (e.g. -151). Added _column_sql_types to Cursor so the
converter map tries the raw SQL code first, then falls back to
Python type, then WVARCHAR.

Also fixes the output converter test to register by SQL_SS_UDT (-151)
instead of bytes, and adds docstrings to _get_c_type_for_sql_type and
_map_data_type documenting the SQL Server-specific types.

Author: dlevy-msft-sql

mssql_python/cursor.py

@@ -844,7 +844,11 @@ def _reset_inputsizes(self) -> None:
         self._inputsizes = None
 
     def _get_c_type_for_sql_type(self, sql_type: int) -> int:
-        """Map SQL type to appropriate C type for parameter binding"""
+        """Map SQL type to appropriate C type for parameter binding.
+
+        Includes SQL_SS_UDT(-151) for CLR UDTs (geography, geometry, hierarchyid),
+        mapped to SQL_C_BINARY.
+        """
         sql_to_c_type = {
             ddbc_sql_const.SQL_CHAR.value: ddbc_sql_const.SQL_C_CHAR.value,
             ddbc_sql_const.SQL_VARCHAR.value: ddbc_sql_const.SQL_C_CHAR.value,
@@ -943,9 +947,11 @@ 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_sql_types = None
             return
 
         description = []
+        sql_types = []
         for _, col in enumerate(column_metadata):
             # Get column name - lowercase it if the lowercase flag is set
             column_name = col["ColumnName"]
@@ -954,6 +960,8 @@ def _initialize_description(self, column_metadata: Optional[Any] = None) -> None
             if get_settings().lowercase:
                 column_name = column_name.lower()
 
+            sql_types.append(col["DataType"])
+
             # Add to description tuple (7 elements as per PEP-249)
             description.append(
                 (
@@ -967,6 +975,7 @@ def _initialize_description(self, column_metadata: Optional[Any] = None) -> None
                 )
             )
         self.description = description
+        self._column_sql_types = sql_types
 
     def _build_converter_map(self):
         """
@@ -982,14 +991,24 @@ def _build_converter_map(self):
             return None
 
         converter_map = []
+        raw_types = getattr(self, "_column_sql_types", None)
 
-        for desc in self.description:
+        for i, desc in enumerate(self.description):
             if desc is None:
                 converter_map.append(None)
                 continue
-            sql_type = desc[1]
-            converter = self.connection.get_output_converter(sql_type)
-            # If no converter found for the SQL type, try the WVARCHAR converter as a fallback
+
+            converter = None
+
+            # First try lookup by raw SQL type code (e.g. -151 for SQL_SS_UDT)
+            if raw_types and i < len(raw_types):
+                converter = self.connection.get_output_converter(raw_types[i])
+
+            # Fall back to lookup by Python type from description
+            if converter is None:
+                converter = self.connection.get_output_converter(desc[1])
+
+            # Last resort: try the WVARCHAR converter as a catch-all fallback
             if converter is None:
                 from mssql_python.constants import ConstantsDDBC
 
@@ -1027,8 +1046,17 @@ def _map_data_type(self, sql_type):
         """
         Map SQL data type to Python data type.
 
+        Maps the ODBC SQL type code returned by SQLDescribeCol to the
+        corresponding Python type for cursor.description[i][1].
+
+        SQL Server-specific types (from msodbcsql.h):
+            SQL_SS_UDT(-151)    for CLR UDTs (geography, geometry, hierarchyid)
+            SQL_SS_XML(-152)    for xml columns
+            SQL_SS_TIME2(-154)  for time columns
+            SQL_DATETIMEOFFSET(-155)  for datetimeoffset columns
+
         Args:
-            sql_type: SQL data type.
+            sql_type: SQL data type code from SQLDescribeCol.
 
         Returns:
             Corresponding Python data type.

tests/test_017_spatial_types.py

@@ -304,14 +304,15 @@ def geography_converter(value):
             return None
         return b"CONVERTED:" + value
 
-    db_connection.add_output_converter(bytes, geography_converter)
+    SQL_SS_UDT = -151
+    db_connection.add_output_converter(SQL_SS_UDT, geography_converter)
 
     try:
         row = cursor.execute("SELECT geo_col FROM #geo_converter;").fetchone()
         assert isinstance(row[0], bytes)
         assert row[0].startswith(b"CONVERTED:")
     finally:
-        db_connection.remove_output_converter(bytes)
+        db_connection.remove_output_converter(SQL_SS_UDT)
 
 
 def test_geography_description_metadata(cursor, db_connection):