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

@@ -953,9 +953,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"]
@@ -964,6 +966,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(
                 (
@@ -977,6 +981,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):
         """
@@ -992,14 +997,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
 

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):