FIX: dispatch output converters on integer ODBC SQL type codes (#684)

[jahnvi480]

Work Item / Issue Reference

[AB#46648]

GitHub Issue: #684

---

Summary

Connection.add_output_converter(sqltype, func) documents (and pyodbc accepts) an
integer ODBC SQL type code as the key — e.g. SQL_DECIMAL, SQL_INTEGER. However,
dispatch in Cursor._build_converter_map() keyed on the Python type stored in
cursor.description[i][1] (via _map_data_type), so integer-keyed converters were stored
but silently never fired. Only Python-type keys (e.g. decimal.Decimal, str) worked.
This makes the driver diverge from pyodbc and from its own documentation.

Root cause

The raw ODBC SQL type code (col["DataType"]) is available when the description is built
in _initialize_description, but it was discarded. _build_converter_map then looked up
converters using description[i][1] (a Python type), which can never match an integer key.

Fix

• cursor.py
  • _initialize_description now also stores self._column_sql_types — the raw ODBC SQL
    type codes, parallel to description (reset to None when there are no columns).
  • _build_converter_map dispatches in pyodbc-compatible order: (1) integer SQL type
    code, (2) Python type in description[i][1], (3) the legacy WVARCHAR catch-all.
    This is purely additive — existing Python-type converters keep working.
  • _prepare_metadata_result_set now builds the converter map so catalog metadata result
    sets (columns(), tables(), …) honor converters consistently with normal result sets.
  • Defensive self._column_sql_types = None resets alongside the bare self.description = None
    assignments (execute/executemany describe-fail paths and nextset).
• connection.py — add_output_converter signature is now sqltype: Union[int, type]; the
  docstring is corrected to describe both key styles (integer key takes precedence) and the
  value semantics (already-materialized Python object; str passed as UTF‑16LE bytes).
• mssql_python.pyi — stub updated to match (Union[int, type]).

Exact-type dispatch

Integer keys use exact ODBC type matching, so SQL_DECIMAL and SQL_NUMERIC are
distinct (they are not collapsed to decimal.Decimal), matching pyodbc.

Tests

Added tests/test_003_connection.py::test_output_converter_integer_sql_type_key_gh684
covering: integer key fires; exact-type dispatch (SQL_INTEGER does not touch DECIMAL,
but fires on INT); integer-key precedence over a Python-type key; distinct DECIMAL vs
NUMERIC converters; NULL stays None; the SQL_WVARCHAR string path (converter receives
UTF‑16LE bytes); and metadata result sets building a converter map.

Validation

• black --check --line-length=100 clean on all changed files.
• Output-converter suite: 14 passed (incl. the new regression test) against a live SQL Server.

[Copilot]

Pull request overview

Fixes output-converter dispatch so Connection.add_output_converter(sqltype, func) honors integer ODBC SQL type codes (pyodbc-compatible) instead of only firing for Python-type keys derived from cursor.description[i][1]. This aligns runtime behavior with the documented API and resolves the silent no-op described in #684.

Changes:

• Preserve raw ODBC SQL type codes per column and use them first when building the per-result-set output-converter dispatch map (with Python-type and legacy SQL_WVARCHAR fallback preserved).
• Ensure catalog/metadata result sets (e.g., cursor.tables()) also build a converter map so converters apply consistently.
• Update the public type surface (connection.py doc/signature and mssql_python.pyi) and add a regression test covering integer-key dispatch semantics and precedence.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
mssql_python/cursor.py	Store per-column raw ODBC type codes and dispatch converters in pyodbc-compatible precedence order; build converter maps for metadata result sets.
mssql_python/connection.py	Broaden add_output_converter to accept Union[int, type] and correct/clarify converter semantics in the docstring.
mssql_python/mssql_python.pyi	Update stub signature for add_output_converter to match runtime API.
tests/test_003_connection.py	Add regression test covering integer SQL type keys, precedence, exact-type matching, NULL handling, string converter path, and metadata behavior.

[github-actions]

📊 Code Coverage Report

🔥 Diff Coverage 100%

🎯 Overall Coverage 81%

📈 Total Lines Covered: 7083 out of 8689 📁 Project: mssql-python

---

Diff Coverage

Diff: main...HEAD, staged and unstaged changes

• mssql_python/connection.py (100%)
• mssql_python/cursor.py (100%)

Summary

• Total: 17 lines
• Missing: 0 lines
• Coverage: 100%

---

📋 Files Needing Attention

📉 Files with overall lowest coverage (click to expand)

mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.pybind.ddbc_bindings.h: 59.9%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python.pybind.ddbc_bindings.cpp: 76.3%
mssql_python.__init__.py: 77.3%
mssql_python.row.py: 77.6%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.pybind.connection.connection_pool.cpp: 81.4%
mssql_python.pybind.connection.connection.cpp: 83.7%
mssql_python.connection.py: 84.7%

---

🔗 Quick Links

⚙️ Build Summary	📋 Coverage Details
View Azure DevOps Build	Browse Full Coverage Report