mssql-python 0.7.0__cp311-cp311-macosx_15_0_universal2.whl

mssql_python/__init__.py

@@ -0,0 +1,74 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module initializes the mssql_python package.
+"""
+
+# Exceptions
+# https://www.python.org/dev/peps/pep-0249/#exceptions
+from .exceptions import (
+    Warning,
+    Error,
+    InterfaceError,
+    DatabaseError,
+    DataError,
+    OperationalError,
+    IntegrityError,
+    InternalError,
+    ProgrammingError,
+    NotSupportedError,
+)
+
+# Type Objects
+from .type import (
+    Date,
+    Time,
+    Timestamp,
+    DateFromTicks,
+    TimeFromTicks,
+    TimestampFromTicks,
+    Binary,
+    STRING,
+    BINARY,
+    NUMBER,
+    DATETIME,
+    ROWID,
+)
+
+# Connection Objects
+from .db_connection import connect, Connection
+
+# Cursor Objects
+from .cursor import Cursor
+
+# Logging Configuration
+from .logging_config import setup_logging, get_logger
+
+# Constants
+from .constants import ConstantsDDBC
+
+# GLOBALS
+# Read-Only
+apilevel = "2.0"
+paramstyle = "qmark"
+threadsafety = 1
+
+from .pooling import PoolingManager
+def pooling(max_size=100, idle_timeout=600, enabled=True):
+#     """
+#     Enable connection pooling with the specified parameters.
+#     By default:
+#         - If not explicitly called, pooling will be auto-enabled with default values.
+
+#     Args:
+#         max_size (int): Maximum number of connections in the pool.
+#         idle_timeout (int): Time in seconds before idle connections are closed.
+    
+#     Returns:
+#         None
+#     """
+    if not enabled:
+        PoolingManager.disable()
+    else:
+        PoolingManager.enable(max_size, idle_timeout)
+      

mssql_python/bcp_options.py

@@ -0,0 +1,121 @@
+from dataclasses import dataclass, field
+from typing import List, Optional, Literal
+
+
+@dataclass
+class ColumnFormat:
+    """
+    Represents the format of a column in a bulk copy operation.
+    Attributes:
+        prefix_len (int): Option: (format_file) or (prefix_len, data_len).
+            The length of the prefix for fixed-length data types. Must be non-negative.
+        data_len (int): Option: (format_file) or (prefix_len, data_len).
+            The length of the data. Must be non-negative.
+        field_terminator (Optional[bytes]): Option: (-t). The field terminator string.
+            e.g., b',' for comma-separated values.
+        row_terminator (Optional[bytes]): Option: (-r). The row terminator string.
+            e.g., b'\\n' for newline-terminated rows.
+        server_col (int): Option: (format_file) or (server_col). The 1-based column number
+            in the SQL Server table. Defaults to 1, representing the first column.
+            Must be a positive integer.
+        file_col (int): Option: (format_file) or (file_col). The 1-based column number
+            in the data file. Defaults to 1, representing the first column.
+            Must be a positive integer.
+    """
+
+    prefix_len: int
+    data_len: int
+    field_terminator: Optional[bytes] = None
+    row_terminator: Optional[bytes] = None
+    server_col: int = 1
+    file_col: int = 1
+
+    def __post_init__(self):
+        if self.prefix_len < 0:
+            raise ValueError("prefix_len must be a non-negative integer.")
+        if self.data_len < 0:
+            raise ValueError("data_len must be a non-negative integer.")
+        if self.server_col <= 0:
+            raise ValueError("server_col must be a positive integer (1-based).")
+        if self.file_col <= 0:
+            raise ValueError("file_col must be a positive integer (1-based).")
+        if self.field_terminator is not None and not isinstance(
+            self.field_terminator, bytes
+        ):
+            raise TypeError("field_terminator must be bytes or None.")
+        if self.row_terminator is not None and not isinstance(
+            self.row_terminator, bytes
+        ):
+            raise TypeError("row_terminator must be bytes or None.")
+
+
+@dataclass
+class BCPOptions:
+    """
+    Represents the options for a bulk copy operation.
+    Attributes:
+        direction (Literal[str]): 'in' or 'out'. Option: (-i or -o).
+        data_file (str): The data file. Option: (positional argument).
+        error_file (Optional[str]): The error file. Option: (-e).
+        format_file (Optional[str]): The format file to use for 'in'/'out'. Option: (-f).
+        batch_size (Optional[int]): The batch size. Option: (-b).
+        max_errors (Optional[int]): The maximum number of errors allowed. Option: (-m).
+        first_row (Optional[int]): The first row to process. Option: (-F).
+        last_row (Optional[int]): The last row to process. Option: (-L).
+        code_page (Optional[str]): The code page. Option: (-C).
+        keep_identity (bool): Keep identity values. Option: (-E).
+        keep_nulls (bool): Keep null values. Option: (-k).
+        hints (Optional[str]): Additional hints. Option: (-h).
+        bulk_mode (str): Bulk mode ('native', 'char', 'unicode'). Option: (-n, -c, -w).
+            Defaults to "native".
+        columns (List[ColumnFormat]): Column formats.
+    """
+
+    direction: Literal["in", "out"]
+    data_file: str  # data_file is mandatory for 'in' and 'out'
+    error_file: Optional[str] = None
+    format_file: Optional[str] = None
+    # write_format_file is removed as 'format' direction is not actively supported
+    batch_size: Optional[int] = None
+    max_errors: Optional[int] = None
+    first_row: Optional[int] = None
+    last_row: Optional[int] = None
+    code_page: Optional[str] = None
+    keep_identity: bool = False
+    keep_nulls: bool = False
+    hints: Optional[str] = None
+    bulk_mode: Literal["native", "char", "unicode"] = "native"
+    columns: List[ColumnFormat] = field(default_factory=list)
+
+    def __post_init__(self):
+        if self.direction not in ["in", "out"]:
+            raise ValueError("direction must be 'in' or 'out'.")
+        if not self.data_file:
+            raise ValueError("data_file must be provided and non-empty for 'in' or 'out' directions.")
+        if self.error_file is None or not self.error_file:  # Making error_file mandatory for in/out
+            raise ValueError("error_file must be provided and non-empty for 'in' or 'out' directions.")
+
+        if self.format_file is not None and not self.format_file:
+            raise ValueError("format_file, if provided, must not be an empty string.")
+        if self.batch_size is not None and self.batch_size <= 0:
+            raise ValueError("batch_size must be a positive integer.")
+        if self.max_errors is not None and self.max_errors < 0:
+            raise ValueError("max_errors must be a non-negative integer.")
+        if self.first_row is not None and self.first_row <= 0:
+            raise ValueError("first_row must be a positive integer.")
+        if self.last_row is not None and self.last_row <= 0:
+            raise ValueError("last_row must be a positive integer.")
+        if self.last_row is not None and self.first_row is None:
+            raise ValueError("first_row must be specified if last_row is specified.")
+        if (
+            self.first_row is not None
+            and self.last_row is not None
+            and self.last_row < self.first_row
+        ):
+            raise ValueError("last_row must be greater than or equal to first_row.")
+        if self.code_page is not None and not self.code_page:
+            raise ValueError("code_page, if provided, must not be an empty string.")
+        if self.hints is not None and not self.hints:
+            raise ValueError("hints, if provided, must not be an empty string.")
+        if self.bulk_mode not in ["native", "char", "unicode"]:
+            raise ValueError("bulk_mode must be 'native', 'char', or 'unicode'.")

mssql_python/connection.py

@@ -0,0 +1,270 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module defines the Connection class, which is used to manage a connection to a database.
+The class provides methods to establish a connection, create cursors, commit transactions, 
+roll back transactions, and close the connection.
+Resource Management:
+- All cursors created from this connection are tracked internally.
+- When close() is called on the connection, all open cursors are automatically closed.
+- Do not use any cursor after the connection is closed; doing so will raise an exception.
+- Cursors are also cleaned up automatically when no longer referenced, to prevent memory leaks.
+"""
+import weakref
+from mssql_python.cursor import Cursor
+from mssql_python.logging_config import get_logger, ENABLE_LOGGING
+from mssql_python.constants import ConstantsDDBC as ddbc_sql_const
+from mssql_python.helpers import add_driver_to_connection_str, check_error
+from mssql_python import ddbc_bindings
+from mssql_python.pooling import PoolingManager
+from mssql_python.exceptions import DatabaseError, InterfaceError
+
+logger = get_logger()
+
+
+class Connection:
+    """
+    A class to manage a connection to a database, compliant with DB-API 2.0 specifications.
+
+    This class provides methods to establish a connection to a database, create cursors,
+    commit transactions, roll back transactions, and close the connection. It is designed
+    to be used in a context where database operations are required, such as executing queries
+    and fetching results.
+
+    Methods:
+        __init__(database: str) -> None:
+        connect_to_db() -> None:
+        cursor() -> Cursor:
+        commit() -> None:
+        rollback() -> None:
+        close() -> None:
+    """
+
+    def __init__(self, connection_str: str = "", autocommit: bool = False, attrs_before: dict = None, **kwargs) -> None:
+        """
+        Initialize the connection object with the specified connection string and parameters.
+
+        Args:
+            - connection_str (str): The connection string to connect to.
+            - autocommit (bool): If True, causes a commit to be performed after each SQL statement.
+            **kwargs: Additional key/value pairs for the connection string.
+            Not including below properties since we are driver doesn't support this:
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If the connection string is invalid or connection fails.
+
+        This method sets up the initial state for the connection object,
+        preparing it for further operations such as connecting to the 
+        database, executing queries, etc.
+        """
+        self.connection_str = self._construct_connection_string(
+            connection_str, **kwargs
+        )
+        self._attrs_before = attrs_before or {}
+        self._closed = False
+        
+        # Using WeakSet which automatically removes cursors when they are no longer in use
+        # It is a set that holds weak references to its elements.
+        # When an object is only weakly referenced, it can be garbage collected even if it's still in the set.
+        # It prevents memory leaks by ensuring that cursors are cleaned up when no longer in use without requiring explicit deletion.
+        # TODO: Think and implement scenarios for multi-threaded access to cursors
+        self._cursors = weakref.WeakSet()
+
+        # Auto-enable pooling if user never called
+        if not PoolingManager.is_initialized():
+            PoolingManager.enable()
+        self._pooling = PoolingManager.is_enabled()
+        self._conn = ddbc_bindings.Connection(self.connection_str, self._pooling, self._attrs_before)
+        self.setautocommit(autocommit)
+
+    def _construct_connection_string(self, connection_str: str = "", **kwargs) -> str:
+        """
+        Construct the connection string by concatenating the connection string 
+        with key/value pairs from kwargs.
+
+        Args:
+            connection_str (str): The base connection string.
+            **kwargs: Additional key/value pairs for the connection string.
+
+        Returns:
+            str: The constructed connection string.
+        """
+        # Add the driver attribute to the connection string
+        conn_str = add_driver_to_connection_str(connection_str)
+
+        # Add additional key-value pairs to the connection string
+        for key, value in kwargs.items():
+            if key.lower() == "host" or key.lower() == "server":
+                key = "Server"
+            elif key.lower() == "user" or key.lower() == "uid":
+                key = "Uid"
+            elif key.lower() == "password" or key.lower() == "pwd":
+                key = "Pwd"
+            elif key.lower() == "database":
+                key = "Database"
+            elif key.lower() == "encrypt":
+                key = "Encrypt"
+            elif key.lower() == "trust_server_certificate":
+                key = "TrustServerCertificate"
+            else:
+                continue
+            conn_str += f"{key}={value};"
+
+        if ENABLE_LOGGING:
+            logger.info("Final connection string: %s", conn_str)
+
+        return conn_str
+    
+    @property
+    def autocommit(self) -> bool:
+        """
+        Return the current autocommit mode of the connection.
+        Returns:
+            bool: True if autocommit is enabled, False otherwise.
+        """
+        return self._conn.get_autocommit()
+
+    @autocommit.setter
+    def autocommit(self, value: bool) -> None:
+        """
+        Set the autocommit mode of the connection.
+        Args:
+            value (bool): True to enable autocommit, False to disable it.
+        Returns:
+            None
+        """
+        self.setautocommit(value)
+        if ENABLE_LOGGING:
+            logger.info("Autocommit mode set to %s.", value)
+
+    def setautocommit(self, value: bool = True) -> None:
+        """
+        Set the autocommit mode of the connection.
+        Args:
+            value (bool): True to enable autocommit, False to disable it.
+        Returns:
+            None
+        Raises:
+            DatabaseError: If there is an error while setting the autocommit mode.
+        """
+        self._conn.set_autocommit(value)
+
+    def cursor(self) -> Cursor:
+        """
+        Return a new Cursor object using the connection.
+
+        This method creates and returns a new cursor object that can be used to
+        execute SQL queries and fetch results. The cursor is associated with the
+        current connection and allows interaction with the database.
+
+        Returns:
+            Cursor: A new cursor object for executing SQL queries.
+
+        Raises:
+            DatabaseError: If there is an error while creating the cursor.
+            InterfaceError: If there is an error related to the database interface.
+        """
+        """Return a new Cursor object using the connection."""
+        if self._closed:
+            # raise InterfaceError
+            raise InterfaceError(
+                driver_error="Cannot create cursor on closed connection",
+                ddbc_error="Cannot create cursor on closed connection",
+            )
+
+        cursor = Cursor(self)
+        self._cursors.add(cursor)  # Track the cursor
+        return cursor
+
+    def commit(self) -> None:
+        """
+        Commit the current transaction.
+
+        This method commits the current transaction to the database, making all
+        changes made during the transaction permanent. It should be called after
+        executing a series of SQL statements that modify the database to ensure
+        that the changes are saved.
+
+        Raises:
+            DatabaseError: If there is an error while committing the transaction.
+        """
+        # Commit the current transaction
+        self._conn.commit()
+        if ENABLE_LOGGING:
+            logger.info("Transaction committed successfully.")
+
+    def rollback(self) -> None:
+        """
+        Roll back the current transaction.
+
+        This method rolls back the current transaction, undoing all changes made
+        during the transaction. It should be called if an error occurs during the
+        transaction or if the changes should not be saved.
+
+        Raises:
+            DatabaseError: If there is an error while rolling back the transaction.
+        """
+        # Roll back the current transaction
+        self._conn.rollback()
+        if ENABLE_LOGGING:
+            logger.info("Transaction rolled back successfully.")
+
+    def close(self) -> None:
+        """
+        Close the connection now (rather than whenever .__del__() is called).
+
+        This method closes the connection to the database, releasing any resources
+        associated with it. After calling this method, the connection object should
+        not be used for any further operations. The same applies to all cursor objects
+        trying to use the connection. Note that closing a connection without committing
+        the changes first will cause an implicit rollback to be performed.
+
+        Raises:
+            DatabaseError: If there is an error while closing the connection.
+        """
+        # Close the connection
+        if self._closed:
+            return
+        
+        # Close all cursors first, but don't let one failure stop the others
+        if hasattr(self, '_cursors'):
+            # Convert to list to avoid modification during iteration
+            cursors_to_close = list(self._cursors)
+            close_errors = []
+            
+            for cursor in cursors_to_close:
+                try:
+                    if not cursor.closed:
+                        cursor.close()
+                except Exception as e:
+                    # Collect errors but continue closing other cursors
+                    close_errors.append(f"Error closing cursor: {e}")
+                    if ENABLE_LOGGING:
+                        logger.warning(f"Error closing cursor: {e}")
+            
+            # If there were errors closing cursors, log them but continue
+            if close_errors and ENABLE_LOGGING:
+                logger.warning(f"Encountered {len(close_errors)} errors while closing cursors")
+
+            # Clear the cursor set explicitly to release any internal references
+            self._cursors.clear()
+
+        # Close the connection even if cursor cleanup had issues
+        try:
+            if self._conn:
+                self._conn.close()
+                self._conn = None
+        except Exception as e:
+            if ENABLE_LOGGING:
+                logger.error(f"Error closing database connection: {e}")
+            # Re-raise the connection close error as it's more critical
+            raise
+        finally:
+            # Always mark as closed, even if there were errors
+            self._closed = True
+        
+        if ENABLE_LOGGING:
+            logger.info("Connection closed successfully.")

mssql_python/constants.py

@@ -0,0 +1,118 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module contains the constants used in the DDBC module.
+"""
+
+from enum import Enum
+
+
+class ConstantsDDBC(Enum):
+    """
+    Constants used in the DDBC module.
+    """
+    SQL_HANDLE_ENV = 1
+    SQL_HANDLE_DBC = 2
+    SQL_HANDLE_STMT = 3
+    SQL_SUCCESS = 0
+    SQL_SUCCESS_WITH_INFO = 1
+    SQL_NO_DATA = 100
+    SQL_STILL_EXECUTING = 2
+    SQL_NTS = -3
+    SQL_DRIVER_NOPROMPT = 0
+    SQL_ATTR_ASYNC_DBC_EVENT = 119
+    SQL_IS_INTEGER = -6
+    SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE = 117
+    SQL_OV_DDBC3_80 = 380
+    SQL_ATTR_DDBC_VERSION = 200
+    SQL_ATTR_ASYNC_ENABLE = 4
+    SQL_ATTR_ASYNC_STMT_EVENT = 29
+    SQL_ERROR = -1
+    SQL_INVALID_HANDLE = -2
+    SQL_NULL_HANDLE = 0
+    SQL_OV_DDBC3 = 3
+    SQL_COMMIT = 0
+    SQL_ROLLBACK = 1
+    SQL_ATTR_AUTOCOMMIT = 102
+    SQL_SMALLINT = 5
+    SQL_CHAR = 1
+    SQL_WCHAR = -8
+    SQL_WVARCHAR = -9
+    SQL_BIT = -7
+    SQL_TINYINT = -6
+    SQL_BIGINT = -5
+    SQL_BINARY = -2
+    SQL_VARBINARY = -3
+    SQL_LONGVARBINARY = -4
+    SQL_LONGVARCHAR = -1
+    SQL_UNKNOWN_TYPE = 0
+    SQL_NUMERIC = 2
+    SQL_DECIMAL = 3
+    SQL_INTEGER = 4
+    SQL_FLOAT = 6
+    SQL_REAL = 7
+    SQL_DOUBLE = 8
+    SQL_DATETIME = 9
+    SQL_INTERVAL = 10
+    SQL_TIMESTAMP = 11
+    SQL_DATE = 9
+    SQL_TIME = 10
+    SQL_VARCHAR = 12
+    SQL_TYPE_DATE = 91
+    SQL_TYPE_TIME = 92
+    SQL_TYPE_TIMESTAMP = 93
+    SQL_TYPE_TIMESTAMP_WITH_TIMEZONE = 95
+    SQL_GUID = -11
+    SQL_XML = 241
+    SQL_SMALLDATETIME = 58
+    SQL_TIMESTAMPOFFSET = 43
+    SQL_DATETIME2 = 42
+    SQL_SMALLMONEY = 122
+    SQL_MONEY = 60
+    SQL_WLONGVARCHAR = -10
+    SQL_C_BIT = -7
+    SQL_C_TINYINT = -6
+    SQL_C_SBIGINT = -25
+    SQL_C_BINARY = -2
+    SQL_AUTOCOMMIT_ON = 1
+    SQL_AUTOCOMMIT_OFF = 0
+    SQL_C_VARBINARY = -3
+    SQL_C_LONGVARBINARY = -4
+    SQL_C_LONGVARCHAR = -1
+    SQL_C_CHAR = -8
+    SQL_C_NUMERIC = 2
+    SQL_C_DECIMAL = 3
+    SQL_C_LONG = 4
+    SQL_C_SHORT = 5
+    SQL_C_FLOAT = 7
+    SQL_C_DOUBLE = 8
+    SQL_C_TYPE_DATE = 91
+    SQL_C_TYPE_TIME = 92
+    SQL_C_TYPE_TIMESTAMP = 93
+    SQL_C_TYPE_TIMESTAMP_WITH_TIMEZONE = 95
+    SQL_C_GUID = -11
+    SQL_DESC_TYPE = 2
+    SQL_DESC_LENGTH = 3
+    SQL_DESC_NAME = 4
+    SQL_ATTR_ROW_ARRAY_SIZE = 27
+    SQL_ATTR_ROWS_FETCHED_PTR = 26
+    SQL_ATTR_ROW_STATUS_PTR = 25
+    SQL_FETCH_NEXT = 1
+    SQL_ROW_SUCCESS = 0
+    SQL_ROW_SUCCESS_WITH_INFO = 1
+    SQL_ROW_NOROW = 100
+    SQL_ATTR_CURSOR_TYPE = 6
+    SQL_CURSOR_FORWARD_ONLY = 0
+    SQL_CURSOR_STATIC = 3
+    SQL_CURSOR_KEYSET_DRIVEN = 2
+    SQL_CURSOR_DYNAMIC = 3
+    SQL_NULL_DATA = -1
+    SQL_C_DEFAULT = 99
+    SQL_ATTR_ROW_BIND_TYPE = 5
+    SQL_BIND_BY_COLUMN = 0
+    SQL_PARAM_INPUT = 1
+    SQL_PARAM_OUTPUT = 2
+    SQL_PARAM_INPUT_OUTPUT = 3
+    SQL_C_WCHAR = -8
+    SQL_NULLABLE = 1
+    SQL_MAX_NUMERIC_LEN = 16