FEAT: Param as Dict (#385)

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

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

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

-------------------------------------------------------------------
### Summary   
This pull request introduces support for both `qmark` (`?`) and
`pyformat` (`%(name)s`) parameter styles in SQL queries, improving
compatibility and usability for users of the `mssql_python` package. The
default `paramstyle` is now set to `pyformat`, and both `execute` and
`executemany` methods have been updated to automatically detect and
convert parameter styles as needed. A new utility module,
`parameter_helper.py`, has been added to handle parameter style parsing
and conversion.

**Parameter style support and conversion:**

* Changed the global `paramstyle` in `mssql_python/__init__.py` from
`"qmark"` to `"pyformat"`, making `pyformat` the default parameter
style.
* Added a new module `mssql_python/parameter_helper.py` containing
helper functions to parse pyformat parameters, convert pyformat SQL to
qmark style, and auto-detect/convert parameter styles in queries.

**Enhancements to parameter handling in cursor methods:**

* Updated the `execute` method in `mssql_python/cursor.py` to
auto-detect and convert parameter styles, supporting both single values
and various parameter formats, and to use the new helper functions for
conversion.
* Refactored parameter flattening logic in `execute` to rely on the new
auto-detection and conversion, removing the old manual flattening.
* Enhanced the `executemany` method in `mssql_python/cursor.py` to
auto-detect parameter style, convert pyformat to qmark for all rows if
needed, and wrap single parameters for backward compatibility.

**Tests and validation:**

* Updated the `test_paramstyle` test in `tests/test_001_globals.py` to
expect the new default `paramstyle` value of `"pyformat"`.

Author: jahnvi480

mssql_python/__init__.py

@@ -116,7 +116,7 @@ def _cleanup_connections():
 # GLOBALS
 # Read-Only
 apilevel: str = "2.0"
-paramstyle: str = "qmark"
+paramstyle: str = "pyformat"
 threadsafety: int = 1
 
 # Set the initial decimal separator in C++

mssql_python/cursor.py

@@ -29,6 +29,11 @@
 )
 from mssql_python.row import Row
 from mssql_python import get_settings
+from mssql_python.parameter_helper import (
+    detect_and_convert_parameters,
+    parse_pyformat_params,
+    convert_pyformat_to_qmark,
+)
 
 if TYPE_CHECKING:
     from mssql_python.connection import Connection
@@ -1233,6 +1238,53 @@ def execute(  # pylint: disable=too-many-locals,too-many-branches,too-many-state
         # Clear any previous messages
         self.messages = []
 
+        # Auto-detect and convert parameter style if needed
+        # Supports both qmark (?) and pyformat (%(name)s)
+        # Note: parameters is always a tuple due to *parameters in method signature
+        #
+        # Parameter Passing Rules (handling ambiguity):
+        #
+        # 1. Single value:
+        #    cursor.execute("SELECT ?", 42)
+        #    → parameters = (42,)
+        #    → Wrapped as single parameter
+        #
+        # 2. Multiple values (two equivalent ways):
+        #    cursor.execute("SELECT ?, ?", 1, 2)        # Varargs
+        #    cursor.execute("SELECT ?, ?", (1, 2))      # Tuple
+        #    → Both result in parameters = (1, 2) or ((1, 2),)
+        #    → If single tuple/list/dict arg, it's unwrapped
+        #
+        # 3. Dict for named parameters:
+        #    cursor.execute("SELECT %(id)s", {"id": 42})
+        #    → parameters = ({"id": 42},)
+        #    → Unwrapped to {"id": 42}, then converted to qmark style
+        #
+        # Important: If you pass a tuple/list/dict as the ONLY argument,
+        # it will be unwrapped for parameter binding. This means you cannot
+        # pass a tuple as a single parameter value (but SQL Server doesn't
+        # support tuple types as parameter values anyway).
+        if parameters:
+            # Check if single parameter is a nested container that should be unwrapped
+            # e.g., execute("SELECT ?", (value,)) vs execute("SELECT ?, ?", ((1, 2),))
+            if isinstance(parameters, tuple) and len(parameters) == 1:
+                # Could be either (value,) for single param or ((tuple),) for nested
+                # Check if it's a nested container
+                if isinstance(parameters[0], (tuple, list, dict)):
+                    actual_params = parameters[0]
+                else:
+                    actual_params = parameters
+            else:
+                actual_params = parameters
+
+            # Convert parameters based on detected style
+            operation, converted_params = detect_and_convert_parameters(operation, actual_params)
+
+            # Convert back to list format expected by the binding code
+            parameters = list(converted_params)
+        else:
+            parameters = []
+
         # Getting encoding setting
         encoding_settings = self._get_encoding_settings()
 
@@ -1241,12 +1293,6 @@ def execute(  # pylint: disable=too-many-locals,too-many-branches,too-many-state
         param_info = ddbc_bindings.ParamInfo
         parameters_type = []
 
-        # Flatten parameters if a single tuple or list is passed
-        if len(parameters) == 1 and isinstance(parameters[0], (tuple, list)):
-            parameters = parameters[0]
-
-        parameters = list(parameters)
-
         # Validate that inputsizes matches parameter count if both are present
         if parameters and self._inputsizes:
             if len(self._inputsizes) != len(parameters):
@@ -1933,6 +1979,40 @@ def executemany(  # pylint: disable=too-many-locals,too-many-branches,too-many-s
             self.rowcount = 0
             return
 
+        # Auto-detect and convert parameter style for executemany
+        # Check first row to determine if we need to convert from pyformat to qmark
+        first_row = (
+            seq_of_parameters[0]
+            if hasattr(seq_of_parameters, "__getitem__")
+            else next(iter(seq_of_parameters))
+        )
+
+        if isinstance(first_row, dict):
+            # pyformat style - convert all rows
+            # Parse parameter names from SQL (determines order for all rows)
+            param_names = parse_pyformat_params(operation)
+
+            if param_names:
+                # Convert SQL to qmark style
+                operation, _ = convert_pyformat_to_qmark(operation, first_row)
+
+                # Convert all parameter dicts to tuples in the same order
+                converted_params = []
+                for param_dict in seq_of_parameters:
+                    if not isinstance(param_dict, dict):
+                        raise TypeError(
+                            f"Mixed parameter types in executemany: first row is dict, "
+                            f"but row has {type(param_dict).__name__}"
+                        )
+                    # Build tuple in the order determined by param_names
+                    row_tuple = tuple(param_dict[name] for name in param_names)
+                    converted_params.append(row_tuple)
+
+                seq_of_parameters = converted_params
+                logger.debug(
+                    "executemany: Converted %d rows from pyformat to qmark", len(seq_of_parameters)
+                )
+
         # Apply timeout if set (non-zero)
         if self._timeout > 0:
             try: