mssql-python 0.5.0__cp313-cp313-macosx_15_0_universal2.whl

mssql_python/__init__.py

@@ -0,0 +1,69 @@
+"""
+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):
+#     """
+#     Enable connection pooling with the specified parameters.
+    
+#     Args:
+#         max_size (int): Maximum number of connections in the pool.
+#         idle_timeout (int): Time in seconds before idle connections are closed.
+    
+#     Returns:
+#         None
+#     """
+    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,203 @@
+"""
+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.
+"""
+import ctypes
+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
+
+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._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 Cursor(self)
+
+    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
+        self._conn.close()
+        if ENABLE_LOGGING:
+            logger.info("Connection closed successfully.")