mssql-python 1.0.0a0__cp313-cp313-win_amd64.whl

mssql_python/__init__.py

@@ -0,0 +1,31 @@
+from .constants import (
+    ConstantsODBC
+)
+
+# GLOBALS
+# Read-Only
+apilevel = '2.0'
+paramstyle = 'qmark'
+threadsafety = 1
+
+# 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 .connection import Connection
+from .db_connection import connect
+
+# Cursor Objects
+from .cursor import Cursor
+
+from .logging_config import setup_logging, get_logger

mssql_python/connection.py

@@ -0,0 +1,302 @@
+import ctypes
+from mssql_python.cursor import Cursor
+from mssql_python.logging_config import get_logger, ENABLE_LOGGING
+from mssql_python.constants import ConstantsODBC as odbc_sql_const
+from mssql_python.helpers import add_driver_to_connection_str, check_error
+import os
+from mssql_python import ddbc_bindings
+
+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, **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.henv = ctypes.c_void_p()
+        self.hdbc = ctypes.c_void_p()
+        self.connection_str = self._construct_connection_string(connection_str, **kwargs)
+        self._initializer()
+        self._autocommit = autocommit
+        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":
+                key = "Server"
+            elif key.lower() == "user":
+                key = "Uid"
+            elif key.lower() == "password":
+                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};"
+        return conn_str
+
+    def _initializer(self) -> None:
+        """
+        Initialize the environment and connection handles.
+
+        This method is responsible for setting up the environment and connection
+        handles, allocating memory for them, and setting the necessary attributes.
+        It should be called before establishing a connection to the database.
+        """
+        self._allocate_environment_handle()
+        self._set_environment_attributes()
+        self._allocate_connection_handle()
+        self._set_connection_attributes()
+        self._connect_to_db()
+        
+    def _allocate_environment_handle(self):
+        """
+        Allocate the environment handle.
+        """
+        ret = ddbc_bindings.DDBCSQLAllocHandle(
+            odbc_sql_const.SQL_HANDLE_ENV.value, #SQL environment handle type
+            0, # SQL input handle
+            ctypes.cast(ctypes.pointer(self.henv), ctypes.c_void_p).value # SQL output handle pointer
+        )
+        check_error(odbc_sql_const.SQL_HANDLE_ENV.value, self.henv.value, ret)
+
+    def _set_environment_attributes(self):
+        """
+        Set the environment attributes.
+        """
+        ret = ddbc_bindings.DDBCSQLSetEnvAttr(
+            self.henv.value,  # Environment handle
+            odbc_sql_const.SQL_ATTR_ODBC_VERSION.value,  # Attribute
+            odbc_sql_const.SQL_OV_ODBC3_80.value, # String Length
+            0 # Null-terminated string
+        )
+        check_error(odbc_sql_const.SQL_HANDLE_ENV.value, self.henv.value, ret)
+
+    def _allocate_connection_handle(self):
+        """
+        Allocate the connection handle.
+        """
+        ret = ddbc_bindings.DDBCSQLAllocHandle(
+            odbc_sql_const.SQL_HANDLE_DBC.value, # SQL connection handle type
+            self.henv.value, # SQL environment handle
+            ctypes.cast(ctypes.pointer(self.hdbc), ctypes.c_void_p).value # SQL output handle pointer
+        )
+        check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, ret)
+
+    def _set_connection_attributes(self):
+        """
+        Set the connection attributes before connecting.
+        """
+        if self.autocommit:
+            ret = ddbc_bindings.DDBCSQLSetConnectAttr(
+                self.hdbc.value,
+                odbc_sql_const.SQL_ATTR_AUTOCOMMIT.value,
+                odbc_sql_const.SQL_AUTOCOMMIT_ON.value,
+                0
+            )
+            check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, ret)
+
+    def _connect_to_db(self) -> None:
+        """
+        Establish a connection to the database.
+
+        This method is responsible for creating a connection to the specified database.
+        It does not take any arguments and does not return any value. The connection
+        details such as database name, user credentials, host, and port should be
+        configured within the class or passed during the class instantiation.
+
+        Raises:
+            DatabaseError: If there is an error while trying to connect to the database.
+            InterfaceError: If there is an error related to the database interface.
+        """
+        if ENABLE_LOGGING:
+            logger.info("Connecting to the database")
+        ret = ddbc_bindings.DDBCSQLDriverConnect(
+            self.hdbc.value, # Connection handle
+            0, # Window handle
+            self.connection_str # Connection string
+        )
+        check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, ret)
+        if ENABLE_LOGGING:
+            logger.info("Connection established successfully.")
+
+    @property
+    def autocommit(self) -> bool:
+        """
+        Return the current autocommit mode of the connection.
+        Returns:
+            bool: True if autocommit is enabled, False otherwise.
+        """
+        autocommit_mode = ddbc_bindings.DDBCSQLGetConnectionAttr(
+            self.hdbc.value,  # Connection handle
+            odbc_sql_const.SQL_ATTR_AUTOCOMMIT.value,  # Attribute
+        )
+        check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, autocommit_mode)
+        return autocommit_mode == odbc_sql_const.SQL_AUTOCOMMIT_ON.value
+
+    @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
+        Raises:
+            DatabaseError: If there is an error while setting the autocommit mode.
+        """
+        ret = ddbc_bindings.DDBCSQLSetConnectAttr(
+            self.hdbc.value,  # Connection handle
+            odbc_sql_const.SQL_ATTR_AUTOCOMMIT.value,  # Attribute
+            odbc_sql_const.SQL_AUTOCOMMIT_ON.value if value else odbc_sql_const.SQL_AUTOCOMMIT_OFF.value,  # Value
+            0  # String length
+        )
+        check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, ret)
+        self._autocommit = 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.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
+        ret = ddbc_bindings.DDBCSQLEndTran(
+            odbc_sql_const.SQL_HANDLE_DBC.value, # Handle type
+            self.hdbc.value, # Connection handle
+            odbc_sql_const.SQL_COMMIT.value # Commit the transaction
+        )
+        check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, ret)
+        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
+        ret = ddbc_bindings.DDBCSQLEndTran(
+            odbc_sql_const.SQL_HANDLE_DBC.value,  # Handle type
+            self.hdbc.value, # Connection handle
+            odbc_sql_const.SQL_ROLLBACK.value # Roll back the transaction
+        )
+        check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, ret)
+        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.
+        """
+        # Disconnect from the database
+        ret = ddbc_bindings.DDBCSQLDisconnect(self.hdbc.value)
+        check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, ret)
+        
+        # Free the connection handle
+        ret = ddbc_bindings.DDBCSQLFreeHandle(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value)
+        check_error(odbc_sql_const.SQL_HANDLE_DBC.value, self.hdbc.value, ret)
+        
+        if ENABLE_LOGGING:
+            logger.info("Connection closed successfully.")

mssql_python/constants.py

@@ -0,0 +1,108 @@
+from enum import Enum
+
+class ConstantsODBC(Enum):
+    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_ODBC3_80 = 380
+    SQL_ATTR_ODBC_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_ODBC3 = 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