mssql-python 1.0.0__cp314-cp314-win_amd64.whl

mssql_python/mssql_python.pyi

@@ -0,0 +1,375 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+Type stubs for mssql_python package - based on actual public API
+"""
+
+from typing import Any, Dict, List, Optional, Union, Tuple, Sequence, Callable, Iterator
+import datetime
+import logging
+
+# GLOBALS - DB-API 2.0 Required Module Globals
+# https://www.python.org/dev/peps/pep-0249/#module-interface
+apilevel: str  # "2.0"
+paramstyle: str  # "qmark"
+threadsafety: int  # 1
+
+# Module Settings - Properties that can be get/set at module level
+lowercase: bool  # Controls column name case behavior
+native_uuid: bool  # Controls UUID type handling
+
+# Settings Class
+class Settings:
+    lowercase: bool
+    decimal_separator: str
+    native_uuid: bool
+    def __init__(self) -> None: ...
+
+# Module-level Configuration Functions
+def get_settings() -> Settings: ...
+def setDecimalSeparator(separator: str) -> None: ...
+def getDecimalSeparator() -> str: ...
+def pooling(
+    max_size: int = 100, idle_timeout: int = 600, enabled: bool = True
+) -> None: ...
+def get_info_constants() -> Dict[str, int]: ...
+
+# Logging Functions
+def setup_logging(mode: str = "file", log_level: int = logging.DEBUG) -> None: ...
+def get_logger() -> Optional[logging.Logger]: ...
+
+# DB-API 2.0 Type Objects
+# https://www.python.org/dev/peps/pep-0249/#type-objects
+class STRING:
+    """Type object for string-based database columns (e.g. CHAR, VARCHAR)."""
+
+    ...
+
+class BINARY:
+    """Type object for binary database columns (e.g. BINARY, VARBINARY)."""
+
+    ...
+
+class NUMBER:
+    """Type object for numeric database columns (e.g. INT, DECIMAL)."""
+
+    ...
+
+class DATETIME:
+    """Type object for date/time database columns (e.g. DATE, TIMESTAMP)."""
+
+    ...
+
+class ROWID:
+    """Type object for row identifier columns."""
+
+    ...
+
+# DB-API 2.0 Type Constructors
+# https://www.python.org/dev/peps/pep-0249/#type-constructors
+def Date(year: int, month: int, day: int) -> datetime.date: ...
+def Time(hour: int, minute: int, second: int) -> datetime.time: ...
+def Timestamp(
+    year: int,
+    month: int,
+    day: int,
+    hour: int,
+    minute: int,
+    second: int,
+    microsecond: int,
+) -> datetime.datetime: ...
+def DateFromTicks(ticks: int) -> datetime.date: ...
+def TimeFromTicks(ticks: int) -> datetime.time: ...
+def TimestampFromTicks(ticks: int) -> datetime.datetime: ...
+def Binary(value: Union[str, bytes, bytearray]) -> bytes: ...
+
+# DB-API 2.0 Exception Hierarchy
+# https://www.python.org/dev/peps/pep-0249/#exceptions
+class Warning(Exception):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+    driver_error: str
+    ddbc_error: str
+    message: str
+
+class Error(Exception):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+    driver_error: str
+    ddbc_error: str
+    message: str
+
+class InterfaceError(Error):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+
+class DatabaseError(Error):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+
+class DataError(DatabaseError):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+
+class OperationalError(DatabaseError):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+
+class IntegrityError(DatabaseError):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+
+class InternalError(DatabaseError):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+
+class ProgrammingError(DatabaseError):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+
+class NotSupportedError(DatabaseError):
+    def __init__(self, driver_error: str, ddbc_error: str) -> None: ...
+
+# Row Object
+class Row:
+    """
+    Represents a database result row.
+
+    Supports both index-based and name-based column access.
+    """
+
+    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,
+    ) -> None: ...
+    def __getitem__(self, index: int) -> Any: ...
+    def __getattr__(self, name: str) -> Any: ...
+    def __eq__(self, other: Any) -> bool: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[Any]: ...
+    def __str__(self) -> str: ...
+    def __repr__(self) -> str: ...
+
+# DB-API 2.0 Cursor Object
+# https://www.python.org/dev/peps/pep-0249/#cursor-objects
+class Cursor:
+    """
+    Database cursor for executing SQL operations and fetching results.
+
+    This class should not be instantiated directly. Use Connection.cursor() instead.
+    """
+
+    # DB-API 2.0 Required Attributes
+    description: Optional[
+        List[
+            Tuple[
+                str,
+                Any,
+                Optional[int],
+                Optional[int],
+                Optional[int],
+                Optional[int],
+                Optional[bool],
+            ]
+        ]
+    ]
+    rowcount: int
+    arraysize: int
+
+    # Extension Attributes
+    closed: bool
+    messages: List[str]
+
+    @property
+    def rownumber(self) -> int: ...
+    @property
+    def connection(self) -> "Connection": ...
+    def __init__(self, connection: "Connection", timeout: int = 0) -> None: ...
+
+    # DB-API 2.0 Required Methods
+    def callproc(
+        self, procname: str, parameters: Optional[Sequence[Any]] = None
+    ) -> Optional[Sequence[Any]]: ...
+    def close(self) -> None: ...
+    def execute(
+        self,
+        operation: str,
+        *parameters: Any,
+        use_prepare: bool = True,
+        reset_cursor: bool = True,
+    ) -> "Cursor": ...
+    def executemany(
+        self, operation: str, seq_of_parameters: List[Sequence[Any]]
+    ) -> None: ...
+    def fetchone(self) -> Optional[Row]: ...
+    def fetchmany(self, size: Optional[int] = None) -> List[Row]: ...
+    def fetchall(self) -> List[Row]: ...
+    def nextset(self) -> Optional[bool]: ...
+    def setinputsizes(self, sizes: List[Union[int, Tuple[Any, ...]]]) -> None: ...
+    def setoutputsize(self, size: int, column: Optional[int] = None) -> None: ...
+
+# DB-API 2.0 Connection Object
+# https://www.python.org/dev/peps/pep-0249/#connection-objects
+class Connection:
+    """
+    Database connection object.
+
+    This class should not be instantiated directly. Use the connect() function instead.
+    """
+
+    # DB-API 2.0 Exception Attributes
+    Warning: type[Warning]
+    Error: type[Error]
+    InterfaceError: type[InterfaceError]
+    DatabaseError: type[DatabaseError]
+    DataError: type[DataError]
+    OperationalError: type[OperationalError]
+    IntegrityError: type[IntegrityError]
+    InternalError: type[InternalError]
+    ProgrammingError: type[ProgrammingError]
+    NotSupportedError: type[NotSupportedError]
+
+    # Connection Properties
+    @property
+    def timeout(self) -> int: ...
+    @timeout.setter
+    def timeout(self, value: int) -> None: ...
+    @property
+    def autocommit(self) -> bool: ...
+    @autocommit.setter
+    def autocommit(self, value: bool) -> None: ...
+    @property
+    def searchescape(self) -> str: ...
+    def __init__(
+        self,
+        connection_str: str = "",
+        autocommit: bool = False,
+        attrs_before: Optional[Dict[int, Union[int, str, bytes]]] = None,
+        timeout: int = 0,
+        **kwargs: Any,
+    ) -> None: ...
+
+    # DB-API 2.0 Required Methods
+    def cursor(self) -> Cursor: ...
+    def commit(self) -> None: ...
+    def rollback(self) -> None: ...
+    def close(self) -> None: ...
+
+    # Extension Methods
+    def setautocommit(self, value: bool = False) -> None: ...
+    def setencoding(
+        self, encoding: Optional[str] = None, ctype: Optional[int] = None
+    ) -> None: ...
+    def getencoding(self) -> Dict[str, Union[str, int]]: ...
+    def setdecoding(
+        self, sqltype: int, encoding: Optional[str] = None, ctype: Optional[int] = None
+    ) -> None: ...
+    def getdecoding(self, sqltype: int) -> Dict[str, Union[str, int]]: ...
+    def set_attr(
+        self, attribute: int, value: Union[int, str, bytes, bytearray]
+    ) -> None: ...
+    def add_output_converter(
+        self, sqltype: int, func: Callable[[Any], Any]
+    ) -> None: ...
+    def get_output_converter(
+        self, sqltype: Union[int, type]
+    ) -> Optional[Callable[[Any], Any]]: ...
+    def remove_output_converter(self, sqltype: Union[int, type]) -> None: ...
+    def clear_output_converters(self) -> None: ...
+    def execute(self, sql: str, *args: Any) -> Cursor: ...
+    def batch_execute(
+        self,
+        statements: List[str],
+        params: Optional[List[Union[None, Any, Tuple[Any, ...], List[Any]]]] = None,
+        reuse_cursor: Optional[Cursor] = None,
+        auto_close: bool = False,
+    ) -> Tuple[List[Union[List[Row], int]], Cursor]: ...
+    def getinfo(self, info_type: int) -> Union[str, int, bool, None]: ...
+
+    # Context Manager Support
+    def __enter__(self) -> "Connection": ...
+    def __exit__(self, *args: Any) -> None: ...
+
+# Module Connection Function
+def connect(
+    connection_str: str = "",
+    autocommit: bool = False,
+    attrs_before: Optional[Dict[int, Union[int, str, bytes]]] = None,
+    timeout: int = 0,
+    **kwargs: Any,
+) -> Connection: ...
+
+# SQL Type Constants
+SQL_CHAR: int
+SQL_VARCHAR: int
+SQL_LONGVARCHAR: int
+SQL_WCHAR: int
+SQL_WVARCHAR: int
+SQL_WLONGVARCHAR: int
+SQL_DECIMAL: int
+SQL_NUMERIC: int
+SQL_BIT: int
+SQL_TINYINT: int
+SQL_SMALLINT: int
+SQL_INTEGER: int
+SQL_BIGINT: int
+SQL_REAL: int
+SQL_FLOAT: int
+SQL_DOUBLE: int
+SQL_BINARY: int
+SQL_VARBINARY: int
+SQL_LONGVARBINARY: int
+SQL_DATE: int
+SQL_TIME: int
+SQL_TIMESTAMP: int
+SQL_WMETADATA: int
+
+# Connection Attribute Constants
+SQL_ATTR_ACCESS_MODE: int
+SQL_ATTR_CONNECTION_TIMEOUT: int
+SQL_ATTR_CURRENT_CATALOG: int
+SQL_ATTR_LOGIN_TIMEOUT: int
+SQL_ATTR_PACKET_SIZE: int
+SQL_ATTR_TXN_ISOLATION: int
+
+# Transaction Isolation Level Constants
+SQL_TXN_READ_UNCOMMITTED: int
+SQL_TXN_READ_COMMITTED: int
+SQL_TXN_REPEATABLE_READ: int
+SQL_TXN_SERIALIZABLE: int
+
+# Access Mode Constants
+SQL_MODE_READ_WRITE: int
+SQL_MODE_READ_ONLY: int
+
+# GetInfo Constants for Connection.getinfo()
+SQL_DRIVER_NAME: int
+SQL_DRIVER_VER: int
+SQL_DRIVER_ODBC_VER: int
+SQL_DATA_SOURCE_NAME: int
+SQL_DATABASE_NAME: int
+SQL_SERVER_NAME: int
+SQL_USER_NAME: int
+SQL_SQL_CONFORMANCE: int
+SQL_KEYWORDS: int
+SQL_IDENTIFIER_QUOTE_CHAR: int
+SQL_SEARCH_PATTERN_ESCAPE: int
+SQL_CATALOG_TERM: int
+SQL_SCHEMA_TERM: int
+SQL_TABLE_TERM: int
+SQL_PROCEDURE_TERM: int
+SQL_TXN_CAPABLE: int
+SQL_DEFAULT_TXN_ISOLATION: int
+SQL_NUMERIC_FUNCTIONS: int
+SQL_STRING_FUNCTIONS: int
+SQL_DATETIME_FUNCTIONS: int
+SQL_MAX_COLUMN_NAME_LEN: int
+SQL_MAX_TABLE_NAME_LEN: int
+SQL_MAX_SCHEMA_NAME_LEN: int
+SQL_MAX_CATALOG_NAME_LEN: int
+SQL_MAX_IDENTIFIER_LEN: int

mssql_python/pooling.py

@@ -0,0 +1,125 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module provides connection pooling functionality for the mssql_python package.
+"""
+import atexit
+import threading
+from typing import Dict
+
+from mssql_python import ddbc_bindings
+from mssql_python.logging import logger
+
+
+class PoolingManager:
+    """
+    Manages connection pooling for the mssql_python package.
+    
+    This class provides thread-safe connection pooling functionality using the 
+    underlying DDBC bindings. It follows a singleton pattern with class-level
+    state management.
+    """
+    _enabled: bool = False
+    _initialized: bool = False
+    _pools_closed: bool = False  # Track if pools have been closed
+    _lock: threading.Lock = threading.Lock()
+    _config: Dict[str, int] = {"max_size": 100, "idle_timeout": 600}
+
+    @classmethod
+    def enable(cls, max_size: int = 100, idle_timeout: int = 600) -> None:
+        """
+        Enable connection pooling with specified parameters.
+        
+        Args:
+            max_size: Maximum number of connections in the pool (default: 100)
+            idle_timeout: Timeout in seconds for idle connections (default: 600)
+            
+        Raises:
+            ValueError: If parameters are invalid (max_size <= 0 or idle_timeout < 0)
+        """
+        logger.debug('PoolingManager.enable: Attempting to enable pooling - max_size=%d, idle_timeout=%d', max_size, idle_timeout)
+        with cls._lock:
+            if cls._enabled:
+                logger.debug('PoolingManager.enable: Pooling already enabled, skipping')
+                return
+
+            if max_size <= 0 or idle_timeout < 0:
+                logger.error('PoolingManager.enable: Invalid parameters - max_size=%d, idle_timeout=%d', max_size, idle_timeout)
+                raise ValueError("Invalid pooling parameters")
+
+            logger.info('PoolingManager.enable: Enabling connection pooling - max_size=%d, idle_timeout=%d seconds', max_size, idle_timeout)
+            ddbc_bindings.enable_pooling(max_size, idle_timeout)
+            cls._config["max_size"] = max_size
+            cls._config["idle_timeout"] = idle_timeout
+            cls._enabled = True
+            cls._initialized = True
+            logger.info('PoolingManager.enable: Connection pooling enabled successfully')
+
+    @classmethod
+    def disable(cls) -> None:
+        """
+        Disable connection pooling and clean up resources.
+        
+        This method safely disables pooling and closes existing connections.
+        It can be called multiple times safely.
+        """
+        logger.debug('PoolingManager.disable: Attempting to disable pooling')
+        with cls._lock:
+            if (
+                cls._enabled and not cls._pools_closed
+            ):  # Only cleanup if enabled and not already closed
+                logger.info('PoolingManager.disable: Closing connection pools')
+                ddbc_bindings.close_pooling()
+                logger.info('PoolingManager.disable: Connection pools closed successfully')
+            else:
+                logger.debug('PoolingManager.disable: Pooling already disabled or closed')
+            cls._pools_closed = True
+            cls._enabled = False
+            cls._initialized = True
+
+    @classmethod
+    def is_enabled(cls) -> bool:
+        """
+        Check if connection pooling is currently enabled.
+        
+        Returns:
+            bool: True if pooling is enabled, False otherwise
+        """
+        return cls._enabled
+
+    @classmethod
+    def is_initialized(cls) -> bool:
+        """
+        Check if the pooling manager has been initialized.
+        
+        Returns:
+            bool: True if initialized (either enabled or disabled), False otherwise
+        """
+        return cls._initialized
+
+    @classmethod
+    def _reset_for_testing(cls) -> None:
+        """Reset pooling state - for testing purposes only"""
+        with cls._lock:
+            cls._enabled = False
+            cls._initialized = False
+            cls._pools_closed = False
+
+
+@atexit.register
+def shutdown_pooling():
+    """
+    Shutdown pooling during application exit.
+    
+    This function is registered with atexit to ensure proper cleanup of
+    connection pools when the application terminates.
+    """
+    logger.debug('shutdown_pooling: atexit cleanup triggered')
+    with PoolingManager._lock:
+        if PoolingManager._enabled and not PoolingManager._pools_closed:
+            logger.info('shutdown_pooling: Closing connection pools during application exit')
+            ddbc_bindings.close_pooling()
+            PoolingManager._pools_closed = True
+            logger.info('shutdown_pooling: Connection pools closed successfully')
+        else:
+            logger.debug('shutdown_pooling: No active pools to close')

mssql_python/row.py

@@ -0,0 +1,194 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module contains the Row class, which represents a single row of data 
+from a cursor fetch operation.
+"""
+import decimal
+from typing import Any
+from mssql_python.helpers import get_settings
+from mssql_python.logging import logger
+
+class Row:
+    """
+    A row of data from a cursor fetch operation. Provides both tuple-like indexing
+    and attribute access to column values.
+
+    Column attribute access behavior depends on the global 'lowercase' setting:
+    - When enabled: Case-insensitive attribute access
+    - When disabled (default): Case-sensitive attribute access matching original column names
+
+    Example:
+        row = cursor.fetchone()
+        print(row[0])           # Access by index
+        print(row.column_name)  # Access by column name (case sensitivity varies)
+    """
+    
+    def __init__(self, values, column_map, cursor=None, converter_map=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)
+        """
+        # Apply output converters if available using pre-computed converter map
+        if converter_map:
+            self._values = self._apply_output_converters_optimized(values, converter_map)
+        elif cursor and hasattr(cursor.connection, '_output_converters') and cursor.connection._output_converters:
+            # Fallback to original method for backward compatibility
+            self._values = self._apply_output_converters(values, cursor)
+        else:
+            self._values = values
+        
+        self._column_map = column_map
+        self._cursor = cursor
+
+    def _apply_output_converters(self, values, cursor):
+        """
+        Apply output converters to raw values.
+
+        Args:
+            values: Raw values from the database
+            cursor: Cursor object with connection and description
+
+        Returns:
+            List of converted values
+        """
+        if not cursor.description:
+            return values
+
+        converted_values = list(values)
+        
+        for i, (value, desc) in enumerate(zip(values, cursor.description)):
+            if desc is None or value is None:
+                continue
+
+            # Get SQL type from description
+            sql_type = desc[1]  # type_code is at index 1 in description tuple
+
+            # Try to get a converter for this type
+            converter = cursor.connection.get_output_converter(sql_type)
+            
+            # If no converter found for the SQL type but the value is a string or bytes,
+            # try the WVARCHAR converter as a fallback
+            if converter is None and isinstance(value, (str, bytes)):
+                from mssql_python.constants import ConstantsDDBC
+                converter = cursor.connection.get_output_converter(ConstantsDDBC.SQL_WVARCHAR.value)
+
+            # If we found a converter, apply it
+            if converter:
+                try:
+                    # If value is already a Python type (str, int, etc.), 
+                    # we need to convert it to bytes for our converters
+                    if isinstance(value, str):
+                        # Encode as UTF-16LE for string values (SQL_WVARCHAR format)
+                        value_bytes = value.encode("utf-16-le")
+                        converted_values[i] = converter(value_bytes)
+                    else:
+                        converted_values[i] = converter(value)
+                except Exception:
+                    logger.debug('Exception occurred in output converter', exc_info=True)
+                    # If conversion fails, keep the original value
+                    pass
+        
+        return converted_values
+
+    def _apply_output_converters_optimized(self, values, converter_map):
+        """
+        Apply output converters using pre-computed converter map for optimal performance.
+        
+        Args:
+            values: Raw values from the database
+            converter_map: Pre-computed list of converters (one per column, None if no converter)
+            
+        Returns:
+            List of converted values
+        """
+        converted_values = list(values)
+        
+        for i, (value, converter) in enumerate(zip(values, converter_map)):
+            if converter and value is not None:
+                try:
+                    if isinstance(value, str):
+                        value_bytes = value.encode('utf-16-le')
+                        converted_values[i] = converter(value_bytes)
+                    else:
+                        converted_values[i] = converter(value)
+                except Exception:
+                    pass
+        
+        return converted_values
+
+    def __getitem__(self, index: int) -> Any:
+        """Allow accessing by numeric index: row[0]"""
+        return self._values[index]
+
+    def __getattr__(self, name: str) -> Any:
+        """
+        Allow accessing by column name as attribute: row.column_name
+        
+        Note: Case sensitivity depends on the global 'lowercase' setting:
+        - When lowercase=True: Column names are stored in lowercase, enabling
+          case-insensitive attribute access (e.g., row.NAME, row.name, row.Name all work).
+        - When lowercase=False (default): Column names preserve original casing,
+          requiring exact case matching for attribute access.
+        """
+        # Handle lowercase attribute access - if lowercase is enabled,
+        # try to match attribute names case-insensitively
+        if name in self._column_map:
+            return self._values[self._column_map[name]]
+        
+        # If lowercase is enabled on the cursor, try case-insensitive lookup
+        if hasattr(self._cursor, 'lowercase') and self._cursor.lowercase:
+            name_lower = name.lower()
+            for col_name in self._column_map:
+                if col_name.lower() == name_lower:
+                    return self._values[self._column_map[col_name]]
+        
+        raise AttributeError(f"Row has no attribute '{name}'")
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Support comparison with lists for test compatibility.
+        This is the key change needed to fix the tests.
+        """
+        if isinstance(other, list):
+            return self._values == other
+        if isinstance(other, Row):
+            return self._values == other._values
+        return super().__eq__(other)
+
+    def __len__(self) -> int:
+        """Return the number of values in the row"""
+        return len(self._values)
+
+    def __iter__(self) -> Any:
+        """Allow iteration through values"""
+        return iter(self._values)
+
+    def __str__(self) -> str:
+        """Return string representation of the row"""
+        # Local import to avoid circular dependency
+        from mssql_python import getDecimalSeparator
+        parts = []
+        for value in self:
+            if isinstance(value, decimal.Decimal):
+                # Apply custom decimal separator for display
+                sep = getDecimalSeparator()
+                if sep != "." and value is not None:
+                    s = str(value)
+                    if "." in s:
+                        s = s.replace(".", sep)
+                    parts.append(s)
+                else:
+                    parts.append(str(value))
+            else:
+                parts.append(repr(value))
+
+        return "(" + ", ".join(parts) + ")"
+
+    def __repr__(self) -> str:
+        """Return a detailed string representation for debugging"""
+        return repr(tuple(self._values))