FEAT: add native_uuid support (#463)

### Work Item / Issue Reference  
<!-- 
IMPORTANT: Please follow the PR template guidelines below.
For mssql-python maintainers: Insert your ADO Work Item ID below 
For external contributors: Insert Github Issue number below
Only one reference is required - either GitHub issue OR ADO Work Item.
-->

<!-- mssql-python maintainers: ADO Work Item -->
>
[AB#42905](https://sqlclientdrivers.visualstudio.com/c6d89619-62de-46a0-8b46-70b92a84d85e/_workitems/edit/42905)

<!-- External contributors: GitHub Issue -->
> GitHub Issue: #447 

-------------------------------------------------------------------
### Summary   
This pull request introduces support for native UUID handling in the
`mssql_python` package, allowing users to control whether SQL Server
`UNIQUEIDENTIFIER` columns are returned as `uuid.UUID` objects or as
strings. The feature is configurable at both the module and
per-connection levels, enabling incremental adoption and backward
compatibility with pyodbc-style string UUIDs. The implementation ensures
efficient conversion with minimal runtime overhead and updates the
public API, documentation, and type hints accordingly.

**Native UUID Handling**

* Added a new `native_uuid` setting to the global settings (`Settings`
class in `helpers.py`) and exposed it as a property on the module,
allowing users to control UUID handling globally.
(`mssql_python/helpers.py`, `mssql_python/__init__.py`)
* Extended the `Connection` and `connect` API to accept a `native_uuid`
parameter, enabling per-connection overrides of the global setting.
Updated docstrings and type hints to document this parameter.
(`mssql_python/connection.py`, `mssql_python/db_connection.py`,
`mssql_python/mssql_python.pyi`)

**Cursor and Row Conversion Logic**

* Updated the `Cursor` class to determine the effective `native_uuid`
setting and efficiently precompute which columns require conversion to
string, minimizing per-row overhead. (`mssql_python/cursor.py`)
* Modified the `Row` class to accept a list of UUID column indices and
convert those columns to uppercase strings only when
`native_uuid=False`, preserving pyodbc compatibility and allowing
seamless migration. (`mssql_python/row.py`,
`mssql_python/mssql_python.pyi`)

**Testing and Minor Updates**

* Updated test imports to include the new `native_uuid` symbol.
(`tests/test_001_globals.py`)
* Minor formatting and docstring updates for clarity and consistency.
(`tests/test_001_globals.py`)

These changes provide a robust and flexible way for users to opt in to
native UUID support, with clear migration paths and minimal performance
impact.

Author: jahnvi480

mssql_python/__init__.py

@@ -339,6 +339,24 @@ def lowercase(self, value: bool) -> None:
         with _settings_lock:
             _settings.lowercase = value
 
+    @property
+    def native_uuid(self) -> bool:
+        """Get the native_uuid setting.
+
+        Controls whether UNIQUEIDENTIFIER columns return uuid.UUID objects (True)
+        or str (False). Default is True.
+        Set to False to return str for pyodbc-compatible migration.
+        """
+        return _settings.native_uuid
+
+    @native_uuid.setter
+    def native_uuid(self, value: bool) -> None:
+        """Set the native_uuid setting."""
+        if not isinstance(value, bool):
+            raise ValueError("native_uuid must be a boolean value")
+        with _settings_lock:
+            _settings.native_uuid = value
+
 
 # Replace the current module with our custom module class
 old_module: types.ModuleType = sys.modules[__name__]
@@ -357,3 +375,4 @@ def lowercase(self, value: bool) -> None:
 
 # Initialize property values
 lowercase: bool = _settings.lowercase
+native_uuid: bool = _settings.native_uuid

mssql_python/connection.py

@@ -203,6 +203,7 @@ def __init__(
         autocommit: bool = False,
         attrs_before: Optional[Dict[int, Union[int, str, bytes]]] = None,
         timeout: int = 0,
+        native_uuid: Optional[bool] = None,
         **kwargs: Any,
     ) -> None:
         """
@@ -219,6 +220,9 @@ def __init__(
                                           connecting, such as SQL_ATTR_LOGIN_TIMEOUT,
                                           SQL_ATTR_ODBC_CURSORS, and SQL_ATTR_PACKET_SIZE.
             timeout (int): Login timeout in seconds. 0 means no timeout.
+            native_uuid (bool, optional): Controls whether UNIQUEIDENTIFIER columns return
+                uuid.UUID objects (True) or str (False) for cursors created from this connection.
+                None (default) defers to the module-level ``mssql_python.native_uuid`` setting (True).
             **kwargs: Additional key/value pairs for the connection string.
 
         Returns:
@@ -236,7 +240,16 @@ def __init__(
             >>> import mssql_python as ms
             >>> conn = ms.connect("Server=myserver;Database=mydb",
             ...                   attrs_before={ms.SQL_ATTR_LOGIN_TIMEOUT: 30})
+
+            >>> # Return native uuid.UUID objects instead of strings
+            >>> conn = ms.connect("Server=myserver;Database=mydb", native_uuid=True)
         """
+        # Store per-connection native_uuid override.
+        # None means "use module-level mssql_python.native_uuid".
+        if native_uuid is not None and not isinstance(native_uuid, bool):
+            raise ValueError("native_uuid must be a boolean value or None")
+        self._native_uuid = native_uuid
+
         self.connection_str = self._construct_connection_string(connection_str, **kwargs)
         self._attrs_before = attrs_before or {}
 

mssql_python/cursor.py

@@ -135,6 +135,10 @@ def __init__(self, connection: "Connection", timeout: int = 0) -> None:
 
         self._cached_column_map = None
         self._cached_converter_map = None
+        self._uuid_str_indices = None  # Pre-computed UUID column indices for str conversion
+        # Cache the effective native_uuid setting for this cursor's connection.
+        # Resolution order: connection._native_uuid (if not None) → module-level setting.
+        self._conn_native_uuid = getattr(self.connection, "_native_uuid", None)
         self._next_row_index = 0  # internal: index of the next row the driver will return (0-based)
         self._has_result_set = False  # Track if we have an active result set
         self._skip_increment_for_next_fetch = (
@@ -1009,6 +1013,32 @@ def _build_converter_map(self):
 
         return converter_map
 
+    def _compute_uuid_str_indices(self):
+        """
+        Compute the tuple of column indices whose uuid.UUID values should be
+        stringified (as uppercase), based on the effective native_uuid setting.
+
+        Resolution order: connection-level (if set) → module-level (fallback).
+
+        Returns:
+            tuple of int or None: Column indices to stringify, or None when
+            native_uuid is True — meaning zero per-row overhead.
+        """
+        if not self.description:
+            return None
+
+        effective_native_uuid = (
+            self._conn_native_uuid
+            if self._conn_native_uuid is not None
+            else get_settings().native_uuid
+        )
+        if not effective_native_uuid:
+            indices = tuple(
+                i for i, desc in enumerate(self.description) if desc and desc[1] is uuid.UUID
+            )
+            return indices if indices else None
+        return None
+
     def _get_column_and_converter_maps(self):
         """
         Get column map and converter map for Row construction (thread-safe).
@@ -1429,20 +1459,13 @@ def execute(  # pylint: disable=too-many-locals,too-many-branches,too-many-state
                 col_desc[0]: i for i, col_desc in enumerate(self.description)
             }
             self._cached_converter_map = self._build_converter_map()
+            self._uuid_str_indices = self._compute_uuid_str_indices()
         else:
             self.rowcount = ddbc_bindings.DDBCSQLRowCount(self.hstmt)
             self._clear_rownumber()
             self._cached_column_map = None
             self._cached_converter_map = None
-
-        # After successful execution, initialize description if there are results
-        column_metadata = []
-        try:
-            ddbc_bindings.DDBCSQLDescribeCol(self.hstmt, column_metadata)
-            self._initialize_description(column_metadata)
-        except Exception as e:
-            # If describe fails, it's likely there are no results (e.g., for INSERT)
-            self.description = None
+            self._uuid_str_indices = None
 
         self._reset_inputsizes()  # Reset input sizes after execution
         # Return self for method chaining
@@ -2273,14 +2296,29 @@ def executemany(  # pylint: disable=too-many-locals,too-many-branches,too-many-s
             check_error(ddbc_sql_const.SQL_HANDLE_STMT.value, self.hstmt, ret)
             self.rowcount = ddbc_bindings.DDBCSQLRowCount(self.hstmt)
             self.last_executed_stmt = operation
-            self._initialize_description()
+
+            # Fetch column metadata (e.g. for INSERT … OUTPUT)
+            column_metadata = []
+            try:
+                ddbc_bindings.DDBCSQLDescribeCol(self.hstmt, column_metadata)
+                self._initialize_description(column_metadata)
+            except Exception:  # pylint: disable=broad-exception-caught
+                self.description = None
 
             if self.description:
                 self.rowcount = -1
                 self._reset_rownumber()
+                self._cached_column_map = {
+                    col_desc[0]: i for i, col_desc in enumerate(self.description)
+                }
+                self._cached_converter_map = self._build_converter_map()
+                self._uuid_str_indices = self._compute_uuid_str_indices()
             else:
                 self.rowcount = ddbc_bindings.DDBCSQLRowCount(self.hstmt)
                 self._clear_rownumber()
+                self._cached_column_map = None
+                self._cached_converter_map = None
+                self._uuid_str_indices = None
         finally:
             # Reset input sizes after execution
             self._reset_inputsizes()
@@ -2328,7 +2366,13 @@ def fetchone(self) -> Union[None, Row]:
 
             # Get column and converter maps
             column_map, converter_map = self._get_column_and_converter_maps()
-            return Row(row_data, column_map, cursor=self, converter_map=converter_map)
+            return Row(
+                row_data,
+                column_map,
+                cursor=self,
+                converter_map=converter_map,
+                uuid_str_indices=self._uuid_str_indices,
+            )
         except Exception as e:
             # On error, don't increment rownumber - rethrow the error
             raise e
@@ -2386,8 +2430,15 @@ def fetchmany(self, size: Optional[int] = None) -> List[Row]:
             column_map, converter_map = self._get_column_and_converter_maps()
 
             # Convert raw data to Row objects
+            uuid_idx = self._uuid_str_indices
             return [
-                Row(row_data, column_map, cursor=self, converter_map=converter_map)
+                Row(
+                    row_data,
+                    column_map,
+                    cursor=self,
+                    converter_map=converter_map,
+                    uuid_str_indices=uuid_idx,
+                )
                 for row_data in rows_data
             ]
         except Exception as e:
@@ -2439,8 +2490,15 @@ def fetchall(self) -> List[Row]:
             column_map, converter_map = self._get_column_and_converter_maps()
 
             # Convert raw data to Row objects
+            uuid_idx = self._uuid_str_indices
             return [
-                Row(row_data, column_map, cursor=self, converter_map=converter_map)
+                Row(
+                    row_data,
+                    column_map,
+                    cursor=self,
+                    converter_map=converter_map,
+                    uuid_str_indices=uuid_idx,
+                )
                 for row_data in rows_data
             ]
         except Exception as e:
@@ -2466,6 +2524,7 @@ def nextset(self) -> Union[bool, None]:
         # Clear cached column and converter maps for the new result set
         self._cached_column_map = None
         self._cached_converter_map = None
+        self._uuid_str_indices = None
 
         # Skip to the next result set
         ret = ddbc_bindings.DDBCSQLMoreResults(self.hstmt)
@@ -2491,6 +2550,7 @@ def nextset(self) -> Union[bool, None]:
                     col_desc[0]: i for i, col_desc in enumerate(self.description)
                 }
                 self._cached_converter_map = self._build_converter_map()
+                self._uuid_str_indices = self._compute_uuid_str_indices()
         except Exception as e:  # pylint: disable=broad-exception-caught
             # If describe fails, there might be no results in this result set
             self.description = None

mssql_python/db_connection.py

@@ -14,6 +14,7 @@ def connect(
     autocommit: bool = False,
     attrs_before: Optional[Dict[int, Union[int, str, bytes]]] = None,
     timeout: int = 0,
+    native_uuid: Optional[bool] = None,
     **kwargs: Any,
 ) -> Connection:
     """
@@ -22,10 +23,18 @@ def connect(
     Args:
         connection_str (str): The connection string to connect to.
         autocommit (bool): If True, causes a commit to be performed after each SQL statement.
-    TODO: Add the following parameters to the function signature:
+        attrs_before (dict, optional): A dictionary of connection attributes to set before
+                                      connecting.
         timeout (int): The timeout for the connection attempt, in seconds.
-        readonly (bool): If True, the connection is set to read-only.
-        attrs_before (dict): A dictionary of connection attributes to set before connecting.
+        native_uuid (bool, optional): Controls whether UNIQUEIDENTIFIER columns return
+            uuid.UUID objects (True) or str (False) for this connection.
+            - True: UNIQUEIDENTIFIER columns return uuid.UUID objects.
+            - False: UNIQUEIDENTIFIER columns return str (pyodbc-compatible).
+            - None (default): Uses the module-level ``mssql_python.native_uuid`` setting (True).
+
+            This per-connection override is useful for migration from pyodbc:
+            connections that need string UUIDs can pass native_uuid=False, while the default (True)
+            returns native uuid.UUID objects.
     Keyword Args:
         **kwargs: Additional key/value pairs for the connection string.
     Below attributes are not implemented in the internal driver:
@@ -44,6 +53,11 @@ def connect(
     transactions, and closing the connection.
     """
     conn = Connection(
-        connection_str, autocommit=autocommit, attrs_before=attrs_before, timeout=timeout, **kwargs
+        connection_str,
+        autocommit=autocommit,
+        attrs_before=attrs_before,
+        timeout=timeout,
+        native_uuid=native_uuid,
+        **kwargs,
     )
     return conn

mssql_python/helpers.py

@@ -360,13 +360,17 @@ class Settings:
     Settings class for mssql_python package configuration.
 
     This class holds global settings that affect the behavior of the package,
-    including lowercase column names, decimal separator.
+    including lowercase column names, decimal separator, and UUID handling.
     """
 
     def __init__(self) -> None:
         self.lowercase: bool = False
         # Use the pre-determined separator - no locale access here
         self.decimal_separator: str = _default_decimal_separator
+        # Controls whether UNIQUEIDENTIFIER columns return uuid.UUID (True)
+        # or str (False). Default True returns native uuid.UUID objects.
+        # Set to False to return str for pyodbc-compatible migration.
+        self.native_uuid: bool = True
 
 
 # Global settings instance

mssql_python/mssql_python.pyi

@@ -129,21 +129,11 @@ class Row:
 
     def __init__(
         self,
-        cursor: "Cursor",
-        description: List[
-            Tuple[
-                str,
-                Any,
-                Optional[int],
-                Optional[int],
-                Optional[int],
-                Optional[int],
-                Optional[bool],
-            ]
-        ],
         values: List[Any],
-        column_map: Optional[Dict[str, int]] = None,
-        settings_snapshot: Optional[Dict[str, Any]] = None,
+        column_map: Dict[str, int],
+        cursor: Optional["Cursor"] = None,
+        converter_map: Optional[List[Any]] = None,
+        uuid_str_indices: Optional[Tuple[int, ...]] = None,
     ) -> None: ...
     def __getitem__(self, index: int) -> Any: ...
     def __getattr__(self, name: str) -> Any: ...
@@ -247,6 +237,7 @@ class Connection:
         autocommit: bool = False,
         attrs_before: Optional[Dict[int, Union[int, str, bytes]]] = None,
         timeout: int = 0,
+        native_uuid: Optional[bool] = None,
         **kwargs: Any,
     ) -> None: ...
 
@@ -289,6 +280,7 @@ def connect(
     autocommit: bool = False,
     attrs_before: Optional[Dict[int, Union[int, str, bytes]]] = None,
     timeout: int = 0,
+    native_uuid: Optional[bool] = None,
     **kwargs: Any,
 ) -> Connection: ...
 

mssql_python/row.py

@@ -6,6 +6,7 @@
 """
 
 import decimal
+import uuid as _uuid
 from typing import Any
 from mssql_python.helpers import get_settings
 from mssql_python.logging import logger
@@ -26,14 +27,17 @@ class Row:
         print(row.column_name)  # Access by column name (case sensitivity varies)
     """
 
-    def __init__(self, values, column_map, cursor=None, converter_map=None):
+    def __init__(self, values, column_map, cursor=None, converter_map=None, uuid_str_indices=None):
         """
         Initialize a Row object with values and pre-built column map.
         Args:
             values: List of values for this row
             column_map: Pre-built column name to index mapping (shared across rows)
             cursor: Optional cursor reference (for backward compatibility and lowercase access)
             converter_map: Pre-computed converter map (shared across rows for performance)
+            uuid_str_indices: Tuple of column indices whose uuid.UUID values should be
+                converted to str. Pre-computed once per result set when native_uuid=False.
+                None means no conversion (native_uuid=True, the default).
         """
         # Apply output converters if available using pre-computed converter map
         if converter_map:
@@ -48,9 +52,33 @@ def __init__(self, values, column_map, cursor=None, converter_map=None):
         else:
             self._values = values
 
+        # Convert UUID columns to str when native_uuid=False.
+        # uuid_str_indices is pre-computed once at execute() time, so this is
+        # O(num_uuid_columns) per row — zero cost when native_uuid=True (the default).
+        if uuid_str_indices:
+            self._stringify_uuids(uuid_str_indices)
+
         self._column_map = column_map
         self._cursor = cursor
 
+    def _stringify_uuids(self, indices):
+        """
+        Convert uuid.UUID values at the given column indices to uppercase str in-place.
+
+        This is only called when native_uuid=False. It operates directly on
+        self._values to avoid creating an extra list copy.
+        """
+        vals = self._values
+        # If values are still the original list (no converters), we need a mutable copy
+        if not isinstance(vals, list):
+            vals = list(vals)
+            self._values = vals
+
+        for i in indices:
+            v = vals[i]
+            if v is not None and isinstance(v, _uuid.UUID):
+                vals[i] = str(v).upper()
+
     def _apply_output_converters(self, values, cursor):
         """
         Apply output converters to raw values.