mssql-python 1.16.0__cp315-cp315-win_amd64.whl

mssql_python/db_connection.py

@@ -0,0 +1,98 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module provides a way to create a new connection object to interact with the database.
+"""
+
+from typing import Any, Dict, Optional, Union
+
+from mssql_python.connection import Connection, TokenProvider
+
+
+def connect(
+    connection_str: str = "",
+    autocommit: bool = False,
+    attrs_before: Optional[Dict[int, Union[int, str, bytes]]] = None,
+    timeout: int = 0,
+    native_uuid: Optional[bool] = None,
+    token_provider: Optional[TokenProvider] = None,
+    **kwargs: Any,
+) -> Connection:
+    """
+    Constructor for creating a connection to the database.
+
+    Args:
+        connection_str (str): The connection string to connect to.
+        autocommit (bool): If True, causes a commit to be performed after each SQL statement.
+        attrs_before (dict, optional): A dictionary of connection attributes to set before
+                                      connecting.
+        timeout (int): Login (connection-attempt) timeout in seconds. 0 (default)
+            uses the driver default. This bounds the login/network handshake (via
+            SQL_ATTR_LOGIN_TIMEOUT), not query execution — it is distinct from the
+            ``Connection.timeout`` property, which is the per-statement query
+            timeout. If both ``timeout`` and ``attrs_before[SQL_ATTR_LOGIN_TIMEOUT]``
+            are supplied, the explicit ``attrs_before`` value takes precedence.
+        native_uuid (bool, optional): Controls whether UNIQUEIDENTIFIER columns return
+            uuid.UUID objects (True) or str (False) for this connection.
+            - True: UNIQUEIDENTIFIER columns return uuid.UUID objects.
+            - False: UNIQUEIDENTIFIER columns return str (pyodbc-compatible).
+            - None (default): Uses the module-level ``mssql_python.native_uuid`` setting (True).
+
+            This per-connection override is useful for migration from pyodbc:
+            connections that need string UUIDs can pass native_uuid=False, while the default (True)
+            returns native uuid.UUID objects.
+        token_provider (object, optional): A token provider for Microsoft Entra ID
+            authentication. This must be any object with a ``.get_token(scope)`` method that
+            returns an object with a ``.token`` attribute containing a raw JWT string — for
+            example, any ``azure-identity`` credential class such as
+            ``DefaultAzureCredential``, ``AzureCliCredential``, ``ManagedIdentityCredential``,
+            ``CertificateCredential``, etc.
+
+            When provided, the driver calls ``token_provider.get_token()`` to acquire an
+            access token for SQL Server, bypassing the built-in credential map.
+            Cannot be combined with ``Authentication=`` in the connection string.
+
+            For environment-portable code, prefer ``Authentication=ActiveDirectoryDefault``
+            in the connection string — ``DefaultAzureCredential`` automatically picks the
+            right credential per environment (CLI on dev, Managed Identity in prod).
+            Use ``token_provider=`` only when you need explicit control over token
+            acquisition (e.g., excluding specific providers, using a credential not in
+            the built-in map, or passing custom options to the credential constructor).
+
+            Example::
+
+                from azure.identity import AzureCliCredential
+                conn = mssql_python.connect("Server=s;Database=d",
+                                            token_provider=AzureCliCredential())
+
+            Note: the token scope is fixed to the Azure **commercial** cloud
+            (``https://database.windows.net/.default``). Sovereign clouds (Azure US
+            Government, Azure China, Azure Germany) are **out of scope** — acquire the token
+            yourself and pass it via ``attrs_before[SQL_COPT_SS_ACCESS_TOKEN]`` instead.
+    Keyword Args:
+        **kwargs: Additional key/value pairs for the connection string.
+    Below attributes are not implemented in the internal driver:
+    - encoding (str): The encoding for the connection string.
+    - ansi (bool): If True, indicates the driver does not support Unicode.
+
+    Returns:
+        Connection: A new connection object to interact with the database.
+
+    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.
+
+    This function provides a way to create a new connection object, which can then
+    be used to perform database operations such as executing queries, committing
+    transactions, and closing the connection.
+    """
+    conn = Connection(
+        connection_str,
+        autocommit=autocommit,
+        attrs_before=attrs_before,
+        timeout=timeout,
+        native_uuid=native_uuid,
+        token_provider=token_provider,
+        **kwargs,
+    )
+    return conn

mssql_python/ddbc_bindings.py

@@ -0,0 +1,215 @@
+"""
+Dynamic loading of platform-specific DDBC bindings for mssql-python.
+
+This module handles the runtime loading of the appropriate compiled extension
+module based on the current platform, architecture, and Python version.
+"""
+
+import os
+import importlib.util
+import sys
+import platform
+import sysconfig
+import warnings
+
+
+def normalize_architecture(platform_name_param, architecture_param):
+    """
+    Normalize architecture names for the given platform.
+
+    Args:
+        platform_name_param (str): Platform name ('windows', 'darwin', 'linux')
+        architecture_param (str): Architecture string to normalize
+
+    Returns:
+        str: Normalized architecture name
+
+    Raises:
+        ImportError: If architecture is not supported for the given platform
+        OSError: If platform is not supported
+    """
+    arch_lower = architecture_param.lower()
+
+    if platform_name_param == "windows":
+        arch_map = {
+            "win64": "x64",
+            "amd64": "x64",
+            "x64": "x64",
+            "win32": "x86",
+            "x86": "x86",
+            "arm64": "arm64",
+        }
+        if arch_lower in arch_map:
+            return arch_map[arch_lower]
+        supported = list(set(arch_map.keys()))
+        raise ImportError(
+            f"Unsupported architecture '{architecture_param}' for platform "
+            f"'{platform_name_param}'; expected one of {supported}"
+        )
+
+    if platform_name_param == "darwin":
+        # For macOS, return runtime architecture
+        return platform.machine().lower()
+
+    if platform_name_param == "linux":
+        arch_map = {
+            "x64": "x86_64",
+            "amd64": "x86_64",
+            "x86_64": "x86_64",
+            "arm64": "arm64",
+            "aarch64": "arm64",
+        }
+        if arch_lower in arch_map:
+            return arch_map[arch_lower]
+        supported = list(set(arch_map.keys()))
+        raise ImportError(
+            f"Unsupported architecture '{architecture_param}' for platform "
+            f"'{platform_name_param}'; expected one of {supported}"
+        )
+
+    supported_platforms_list = ["windows", "darwin", "linux"]
+    raise OSError(
+        f"Unsupported platform '{platform_name_param}'; expected one of "
+        f"{supported_platforms_list}"
+    )
+
+
+def get_interpreter_architecture(platform_name_param):
+    """
+    Get the raw architecture string of the running interpreter.
+
+    On Windows, ``platform.machine()`` reports the host CPU rather than the
+    architecture the interpreter was built for. The two differ when an x64
+    interpreter runs emulated on a Windows ARM64 machine (the python.org
+    "64-bit" installer is x64), so the loader would look for an arm64 binary
+    that the installed win_amd64 wheel never shipped. ``sysconfig.get_platform()``
+    is derived from the interpreter build and matches the wheel tag, so it is
+    the source of truth on Windows.
+
+    Args:
+        platform_name_param (str): Platform name ('windows', 'darwin', 'linux')
+
+    Returns:
+        str: Lower case architecture string accepted by normalize_architecture()
+    """
+    if platform_name_param == "windows":
+        # 'win-amd64' -> 'amd64', 'win-arm64' -> 'arm64', 'win32' -> 'win32'
+        return sysconfig.get_platform().lower().removeprefix("win-")
+    return platform.machine().lower()
+
+
+def get_module_architecture(platform_name_param):
+    """
+    Get the architecture token used in the compiled ddbc_bindings filename.
+
+    Args:
+        platform_name_param (str): Platform name ('windows', 'darwin', 'linux')
+
+    Returns:
+        str: 'universal2' on macOS, otherwise the normalized architecture with
+        the Windows x64 build renamed to 'amd64' and the Windows x86 build
+        renamed to 'win32', matching the file names the build produces
+    """
+    # Special handling for macOS universal2 binaries
+    if platform_name_param == "darwin":
+        return "universal2"
+
+    architecture_name = normalize_architecture(
+        platform_name_param, get_interpreter_architecture(platform_name_param)
+    )
+
+    # Handle Windows-specific naming for binary files. The build names the
+    # x64 artifact 'amd64' and the x86 artifact 'win32' (see pybind/build.bat
+    # and pybind/CMakeLists.txt), so the loader has to look for those tokens.
+    if platform_name_param == "windows" and architecture_name == "x64":
+        architecture_name = "amd64"
+    elif platform_name_param == "windows" and architecture_name == "x86":
+        architecture_name = "win32"
+    return architecture_name
+
+
+def find_module_path(module_dir_param, python_version_param, architecture_param, extension_param):
+    """
+    Find the compiled ddbc_bindings module file for the running interpreter.
+
+    Args:
+        module_dir_param (str): Directory that contains the compiled module
+        python_version_param (str): Python version tag such as 'cp312'
+        architecture_param (str): Architecture token from get_module_architecture()
+        extension_param (str): File extension, '.pyd' on Windows and '.so' elsewhere
+
+    Returns:
+        str: Path of the exactly matching module file. If it does not exist, the
+        first ddbc_bindings file built for this interpreter's version tag is
+        returned instead and a RuntimeWarning is emitted.
+
+    Raises:
+        ImportError: If no ddbc_bindings file for this interpreter's version
+        tag exists with the right extension
+    """
+    expected_module = f"ddbc_bindings.{python_version_param}-{architecture_param}{extension_param}"
+    module_path_found = os.path.join(module_dir_param, expected_module)
+
+    if os.path.exists(module_path_found):
+        return module_path_found
+
+    # Fallback: only binaries built for this interpreter's version tag are
+    # loadable, since the cpXY tags are version specific rather than abi3. A
+    # different architecture may still work (for example a universal2 build),
+    # but a different Python version fails later inside importlib with a
+    # confusing DLL or symbol error, so it is excluded here. Sorted so the
+    # pick is deterministic when several candidates remain.
+    module_files = sorted(
+        f
+        for f in os.listdir(module_dir_param)
+        if f.startswith(f"ddbc_bindings.{python_version_param}-") and f.endswith(extension_param)
+    )
+    if not module_files:
+        raise ImportError(
+            f"No ddbc_bindings module found for {python_version_param}-{architecture_param} "
+            f"with extension {extension_param}"
+        )
+    warnings.warn(
+        f"Using fallback module file {module_files[0]} instead of {expected_module}",
+        RuntimeWarning,
+        stacklevel=2,
+    )
+    return os.path.join(module_dir_param, module_files[0])
+
+
+# Get current Python version and architecture
+python_version = f"cp{sys.version_info.major}{sys.version_info.minor}"
+
+platform_name = platform.system().lower()
+architecture = get_module_architecture(platform_name)
+
+# Validate supported platforms
+if platform_name not in ["windows", "darwin", "linux"]:
+    supported_platforms = ["windows", "darwin", "linux"]
+    raise ImportError(
+        f"Unsupported platform '{platform_name}' for mssql-python; expected one "
+        f"of {supported_platforms}"
+    )
+
+# Determine extension based on platform
+if platform_name == "windows":
+    extension = ".pyd"
+else:  # macOS or Linux
+    extension = ".so"
+
+# Find the specifically matching module file
+module_dir = os.path.dirname(__file__)
+module_path = find_module_path(module_dir, python_version, architecture, extension)
+
+
+# Use the original module name 'ddbc_bindings' that the C extension was compiled with
+module_name = "ddbc_bindings"
+spec = importlib.util.spec_from_file_location(module_name, module_path)
+module = importlib.util.module_from_spec(spec)
+sys.modules[module_name] = module
+spec.loader.exec_module(module)
+
+# Copy all attributes from the loaded module to this module
+for attr in dir(module):
+    if not attr.startswith("__"):
+        globals()[attr] = getattr(module, attr)

mssql_python/decimal_config.py

@@ -0,0 +1,114 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+
+This module provides functions for managing decimal separator configuration.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from mssql_python.helpers import Settings
+
+
+def _setDecimalSeparator(separator: str, settings: "Settings", set_in_cpp_func=None) -> None:
+    """
+    Internal implementation for setting the decimal separator.
+
+    Not intended for direct external use — the public API is exposed via
+    ``mssql_python.setDecimalSeparator`` (created by ``create_decimal_separator_functions``).
+
+    Args:
+        separator (str): The character to use as decimal separator
+        settings (Settings): The settings object to update
+        set_in_cpp_func: Optional callable to set the separator in C++ bindings
+
+    Raises:
+        ValueError: If the separator is not a single character string
+    """
+    # Type validation
+    if not isinstance(separator, str):
+        raise ValueError("Decimal separator must be a string")
+
+    # Length validation
+    if len(separator) == 0:
+        raise ValueError("Decimal separator cannot be empty")
+
+    if len(separator) > 1:
+        raise ValueError("Decimal separator must be a single character")
+
+    # Character validation (covers \t, \n, \r, \v, \f and all other whitespace)
+    if separator.isspace():
+        raise ValueError("Whitespace characters are not allowed as decimal separators")
+
+    # Set in Python side settings
+    settings.decimal_separator = separator
+
+    # Update the C++ side if available
+    if set_in_cpp_func is not None:
+        set_in_cpp_func(separator)
+
+
+def _getDecimalSeparator(settings: "Settings") -> str:
+    """
+    Internal implementation for getting the decimal separator.
+
+    Not intended for direct external use — the public API is exposed via
+    ``mssql_python.getDecimalSeparator`` (created by ``create_decimal_separator_functions``).
+
+    Args:
+        settings (Settings): The settings object to read from
+
+    Returns:
+        str: The current decimal separator character
+    """
+    return settings.decimal_separator
+
+
+def create_decimal_separator_functions(settings: "Settings"):
+    """
+    Factory function to create decimal separator getter/setter bound to specific settings.
+
+    This function handles importing the C++ binding and initializing the decimal separator.
+
+    Args:
+        settings: The Settings instance to bind to
+
+    Returns:
+        Tuple of (setDecimalSeparator, getDecimalSeparator) functions
+    """
+    # Try to import and initialize the C++ binding
+    try:
+        from mssql_python.ddbc_bindings import DDBCSetDecimalSeparator
+
+        # Set the initial decimal separator in C++
+        DDBCSetDecimalSeparator(settings.decimal_separator)
+        cpp_binding = DDBCSetDecimalSeparator
+    except ImportError:
+        # Handle case where ddbc_bindings is not available
+        cpp_binding = None
+
+    def setter(separator: str) -> None:
+        """
+        Sets the decimal separator character used when parsing NUMERIC/DECIMAL values
+        from the database, e.g. the "." in "1,234.56".
+
+        Args:
+            separator (str): The character to use as decimal separator
+
+        Raises:
+            ValueError: If the separator is not a single character string
+        """
+        _setDecimalSeparator(separator, settings, cpp_binding)
+
+    def getter() -> str:
+        """
+        Returns the decimal separator character used when parsing NUMERIC/DECIMAL values
+        from the database.
+
+        Returns:
+            str: The current decimal separator character
+        """
+        return _getDecimalSeparator(settings)
+
+    return setter, getter