mssql-python 0.1.6__cp313-cp313-win_arm64.whl

mssql_python/helpers.py

@@ -0,0 +1,111 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module provides helper functions for the mssql_python package.
+"""
+
+from mssql_python import ddbc_bindings
+from mssql_python.exceptions import raise_exception
+from mssql_python.logging_config import get_logger, ENABLE_LOGGING
+
+logger = get_logger()
+
+
+def add_driver_to_connection_str(connection_str):
+    """
+    Add the DDBC driver to the connection string if not present.
+
+    Args:
+        connection_str (str): The original connection string.
+
+    Returns:
+        str: The connection string with the DDBC driver added.
+
+    Raises:
+        Exception: If the connection string is invalid.
+    """
+    driver_name = "Driver={ODBC Driver 18 for SQL Server}"
+    try:
+        # Strip any leading or trailing whitespace from the connection string
+        connection_str = connection_str.strip()
+        connection_str = add_driver_name_to_app_parameter(connection_str)
+
+        # Split the connection string into individual attributes
+        connection_attributes = connection_str.split(";")
+        final_connection_attributes = []
+
+        # Iterate through the attributes and exclude any existing driver attribute
+        for attribute in connection_attributes:
+            if attribute.lower().split("=")[0] == "driver":
+                continue
+            final_connection_attributes.append(attribute)
+
+        # Join the remaining attributes back into a connection string
+        connection_str = ";".join(final_connection_attributes)
+
+        # Insert the driver attribute at the beginning of the connection string
+        final_connection_attributes.insert(0, driver_name)
+        connection_str = ";".join(final_connection_attributes)
+
+    except Exception as e:
+        raise Exception(
+            "Invalid connection string, Please follow the format: "
+            "Server=server_name;Database=database_name;UID=user_name;PWD=password"
+        ) from e
+
+    return connection_str
+
+
+def check_error(handle_type, handle, ret):
+    """
+    Check for errors and raise an exception if an error is found.
+
+    Args:
+        handle_type: The type of the handle (e.g., SQL_HANDLE_ENV, SQL_HANDLE_DBC).
+        handle: The SqlHandle object associated with the operation.
+        ret: The return code from the DDBC function call.
+
+    Raises:
+        RuntimeError: If an error is found.
+    """
+    if ret < 0:
+        error_info = ddbc_bindings.DDBCSQLCheckError(handle_type, handle, ret)
+        if ENABLE_LOGGING:
+            logger.error("Error: %s", error_info.ddbcErrorMsg)
+        raise_exception(error_info.sqlState, error_info.ddbcErrorMsg)
+
+
+def add_driver_name_to_app_parameter(connection_string):
+    """
+    Modifies the input connection string by appending the APP name.
+
+    Args:
+        connection_string (str): The input connection string.
+
+    Returns:
+        str: The modified connection string.
+    """
+    # Split the input string into key-value pairs
+    parameters = connection_string.split(";")
+
+    # Initialize variables
+    app_found = False
+    modified_parameters = []
+
+    # Iterate through the key-value pairs
+    for param in parameters:
+        if param.lower().startswith("app="):
+            # Overwrite the value with 'MSSQL-Python'
+            app_found = True
+            key, _ = param.split("=", 1)
+            modified_parameters.append(f"{key}=MSSQL-Python")
+        else:
+            # Keep other parameters as is
+            modified_parameters.append(param)
+
+    # If APP key is not found, append it
+    if not app_found:
+        modified_parameters.append("APP=MSSQL-Python")
+
+    # Join the parameters back into a connection string
+    return ";".join(modified_parameters) + ";"

mssql_python/libs/LICENSING

@@ -0,0 +1,19 @@
+A. The dynamic-link libraries (DLLs) in the mssql_python\libs\win folder fall under different Microsoft licenses. 
+====================================================================================================
+Below is a breakdown of these components by their respective licenses.
+
+1. Microsoft ODBC Driver 18 End User License Agreement (EULA)
+These components are part of the Microsoft ODBC Driver 18 for SQL Server and are governed by the Microsoft ODBC Driver 18 EULA.
+
+- msodbcsqlr18.rll – Resource library containing localized error messages for the ODBC driver.
+- msodbcdiag18.dll – Diagnostic library for handling error reporting and troubleshooting.
+- msodbcsql18.dll – Core ODBC driver enabling connectivity between SQL Server and applications.
+
+For official licensing terms, refer to: mssql_python\libs\win\MICROSOFT_ODBC_DRIVER_FOR_SQL_SERVER_LICENSE.txt 
+
+2. Microsoft Visual C++ Redistributable EULA
+These components are part of the Microsoft Visual C++ Redistributable and are governed by the Microsoft Visual C++ Redistributable EULA.
+
+- msvcp140.dll – Microsoft C++ Standard Library runtime, required for running C++ applications.  
+
+For redistribution and usage terms, refer to: mssql_python\libs\win\MICROSOFT_VISUAL_STUDIO_LICENSE.txt

mssql_python/logging_config.py

@@ -0,0 +1,65 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module provides logging configuration for the mssql_python package.
+"""
+
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+import sys
+
+ENABLE_LOGGING = False
+
+
+def setup_logging(mode="file", log_level=logging.DEBUG):
+    """
+    Set up logging configuration.
+
+    This method configures the logging settings for the application.
+    It sets the log level, format, and log file location.
+
+    Args:
+        mode (str): The logging mode ('file' or 'stdout').
+        log_level (int): The logging level (default: logging.DEBUG).
+    """
+    global ENABLE_LOGGING
+    ENABLE_LOGGING = True
+
+    # Create a logger for mssql_python module
+    logger = logging.getLogger(__name__)
+    logger.setLevel(log_level)
+
+    # Construct the path to the log file
+    # TODO: Use a different dir to dump log file
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    log_file = os.path.join(current_dir, f'mssql_python_trace_{os.getpid()}.log')
+
+    # Create a log handler to log to driver specific file
+    # By default we only want to log to a file, max size 500MB, and keep 5 backups
+    # TODO: Rotate files based on time too? Ex: everyday
+    file_handler = RotatingFileHandler(log_file, maxBytes=512*1024*1024, backupCount=5)
+    file_handler.setLevel(log_level)
+    formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(filename)s - %(message)s')
+    file_handler.setFormatter(formatter)
+    logger.addHandler(file_handler)
+
+    if mode == 'stdout':
+        # If the mode is stdout, then we want to log to the console as well
+        stdout_handler = logging.StreamHandler(sys.stdout)
+        stdout_handler.setLevel(log_level)
+        stdout_handler.setFormatter(formatter)
+        logger.addHandler(stdout_handler)
+    elif mode != 'file':
+        raise ValueError(f'Invalid logging mode: {mode}')
+
+def get_logger():
+    """
+    Get the logger instance.
+
+    Returns:
+        logging.Logger: The logger instance.
+    """
+    if not ENABLE_LOGGING:
+        return None
+    return logging.getLogger(__name__)

mssql_python/mssql_python.pyi

@@ -0,0 +1,192 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+"""
+
+from typing import Final, Union
+import datetime
+
+# GLOBALS
+# Read-Only
+apilevel: Final[str] = "2.0"
+paramstyle: Final[str] = "pyformat"
+threadsafety: Final[int] = 1
+
+# Type Objects
+# https://www.python.org/dev/peps/pep-0249/#type-objects
+class STRING:
+    """
+    This type object is used to describe columns in a database that are string-based (e.g. CHAR).
+    """
+
+    def __init__(self) -> None: ...
+
+class BINARY:
+    """
+    This type object is used to describe (long) 
+    binary columns in a database (e.g. LONG, RAW, BLOBs).
+    """
+
+    def __init__(self) -> None: ...
+
+class NUMBER:
+    """
+    This type object is used to describe numeric columns in a database.
+    """
+
+    def __init__(self) -> None: ...
+
+class DATETIME:
+    """
+    This type object is used to describe date/time columns in a database.
+    """
+
+    def __init__(self) -> None: ...
+
+class ROWID:
+    """
+    This type object is used to describe the “Row ID” column in a database.
+    """
+
+    def __init__(self) -> None: ...
+
+# 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(string: str) -> bytes: ...
+
+# Exceptions
+# https://www.python.org/dev/peps/pep-0249/#exceptions
+class Warning(Exception): ...
+class Error(Exception): ...
+class InterfaceError(Error): ...
+class DatabaseError(Error): ...
+class DataError(DatabaseError): ...
+class OperationalError(DatabaseError): ...
+class IntegrityError(DatabaseError): ...
+class InternalError(DatabaseError): ...
+class ProgrammingError(DatabaseError): ...
+class NotSupportedError(DatabaseError): ...
+
+# Connection Objects
+class Connection:
+    """
+    Connection object for interacting with the database.
+
+    https://www.python.org/dev/peps/pep-0249/#connection-objects
+
+    This class should not be instantiated directly, instead call global connect() method to
+    create a Connection object.
+    """
+
+    def cursor(self) -> "Cursor":
+        """
+        Return a new Cursor object using the connection.
+        """
+        ...
+
+    def commit(self) -> None:
+        """
+        Commit the current transaction.
+        """
+        ...
+
+    def rollback(self) -> None:
+        """
+        Roll back the current transaction.
+        """
+        ...
+
+    def close(self) -> None:
+        """
+        Close the connection now.
+        """
+        ...
+
+# Cursor Objects
+class Cursor:
+    """
+    Cursor object for executing SQL queries and fetching results.
+
+    https://www.python.org/dev/peps/pep-0249/#cursor-objects
+
+    This class should not be instantiated directly, instead call cursor() from a Connection
+    object to create a Cursor object.
+    """
+
+    def callproc(
+        self, procname: str, parameters: Union[None, list] = None
+    ) -> Union[None, list]:
+        """
+        Call a stored database procedure with the given name.
+        """
+        ...
+
+    def close(self) -> None:
+        """
+        Close the cursor now.
+        """
+        ...
+
+    def execute(
+        self, operation: str, parameters: Union[None, list, dict] = None
+    ) -> None:
+        """
+        Prepare and execute a database operation (query or command).
+        """
+        ...
+
+    def executemany(self, operation: str, seq_of_parameters: list) -> None:
+        """
+        Prepare a database operation and execute it against all parameter sequences.
+        """
+        ...
+
+    def fetchone(self) -> Union[None, tuple]:
+        """
+        Fetch the next row of a query result set.
+        """
+        ...
+
+    def fetchmany(self, size: int = None) -> list:
+        """
+        Fetch the next set of rows of a query result.
+        """
+        ...
+
+    def fetchall(self) -> list:
+        """
+        Fetch all (remaining) rows of a query result.
+        """
+        ...
+
+    def nextset(self) -> Union[None, bool]:
+        """
+        Skip to the next available result set.
+        """
+        ...
+
+    def setinputsizes(self, sizes: list) -> None:
+        """
+        Predefine memory areas for the operation’s parameters.
+        """
+        ...
+
+    def setoutputsize(self, size: int, column: int = None) -> None:
+        """
+        Set a column buffer size for fetches of large columns.
+        """
+        ...
+
+# Module Functions
+def connect(connection_str: str) -> Connection:
+    """
+    Constructor for creating a connection to the database.
+    """
+    ...