arrowsql 0.1.0__cp313-cp313-win_amd64.whl

arrowsql/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 arrowsql.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

arrowsql/ddbc_bindings.pyi

@@ -0,0 +1,283 @@
+"""Type stub for the compiled extension ``mssql_python.ddbc_bindings`` (RUST-PORT).
+
+Covers the port-specific surface in full (Arrow, bulk copy, native asyncio) and
+the upstream-compatible entry points the Python layer calls. Statement and
+connection handles are opaque to callers; the Python layer owns them.
+"""
+
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+__version__: str
+__architecture__: str
+ARCHITECTURE: str
+__rust_port__: bool
+SQL_NO_TOTAL: int
+
+# ---------------------------------------------------------------------------
+# Arrow (Arrow PyCapsule interface; no pyarrow needed)
+# ---------------------------------------------------------------------------
+
+class ArrowTable:
+    """A fully fetched result. Zero-copy for any Arrow consumer."""
+
+    @property
+    def num_rows(self) -> int: ...
+    @property
+    def num_columns(self) -> int: ...
+    @property
+    def num_batches(self) -> int: ...
+    @property
+    def column_names(self) -> List[str]: ...
+    def __len__(self) -> int: ...
+    def __arrow_c_schema__(self) -> Any: ...
+    def __arrow_c_stream__(self, requested_schema: Optional[Any] = None) -> Any: ...
+    @staticmethod
+    def concat(tables: Sequence["ArrowTable"]) -> "ArrowTable": ...
+
+class ArrowStream:
+    """A result being streamed as Arrow record batches (one-shot)."""
+
+    @property
+    def num_columns(self) -> int: ...
+    @property
+    def column_names(self) -> List[str]: ...
+    @property
+    def closed(self) -> bool: ...
+    def __arrow_c_schema__(self) -> Any: ...
+    def __arrow_c_stream__(self, requested_schema: Optional[Any] = None) -> Any: ...
+    def read_all(self) -> ArrowTable: ...
+    def close(self) -> None: ...
+
+class ArrowMergeStream:
+    """Batches of several ArrowStreams merged into one unordered, bounded stream."""
+
+    def __init__(self, schema_from: ArrowStream, workers: int, depth: int = 8) -> None: ...
+    def pump(self, stream: ArrowStream) -> None: ...
+    def worker_done(self) -> None: ...
+    def fail(self, message: str) -> None: ...
+    @property
+    def stopped(self) -> bool: ...
+    @property
+    def closed(self) -> bool: ...
+    @property
+    def in_use(self) -> bool: ...
+    @property
+    def num_columns(self) -> int: ...
+    @property
+    def column_names(self) -> List[str]: ...
+    def close(self) -> None: ...
+    def read_all(self) -> ArrowTable: ...
+    def __arrow_c_schema__(self) -> Any: ...
+    def __arrow_c_stream__(self, requested_schema: Optional[Any] = None) -> Any: ...
+
+class AgentRender:
+    """Collects the bounded text output of one statement (see arrowsql.agent)."""
+
+    def __init__(
+        self,
+        format: str = "tsv",
+        max_bytes: int = 10000,
+        max_rows: int = 1000,
+        max_cell_chars: int = 500,
+        tail_rows: int = 0,
+        timeout_s: Optional[float] = None,
+    ) -> None: ...
+    def has_room(self) -> bool: ...
+    def result_set(
+        self, statement: Any, messages: Optional[List[Any]] = None
+    ) -> Tuple[int, bool]: ...
+    def rows_affected(self, count: int) -> None: ...
+    def message(self, text: str) -> None: ...
+    def omit(self, count: int) -> None: ...
+    def finish(self) -> str: ...
+
+def DDBCArrowFetchTable(
+    statement: Any,
+    max_rows: int = -1,
+    batch_size: int = 65536,
+    messages: Optional[List[Any]] = None,
+) -> Tuple[int, ArrowTable]: ...
+def DDBCArrowStream(
+    statement: Any,
+    batch_size: int = 65536,
+    prefetch: int = 2,
+    owner: Optional[Any] = None,
+) -> ArrowStream: ...
+def DDBCSQLFetchArrowBatch(
+    statement: Any,
+    capsules: List[Any],
+    arrowBatchSize: int,
+    charCtype: int,
+    messages: Optional[List[Any]] = None,
+) -> int: ...
+
+# ---------------------------------------------------------------------------
+# Native bulk copy
+# ---------------------------------------------------------------------------
+
+class BulkUnsupported(Exception):
+    """The native bulk copy cannot load this source into this destination."""
+
+def DDBCBulkCopyRows(
+    handle: Any,
+    table_name: str,
+    rows: Iterable[Tuple[Any, ...]],
+    batch_size: int = 0,
+    timeout: int = 30,
+    column_mappings: Optional[Any] = None,
+    keep_identity: bool = False,
+    check_constraints: bool = False,
+    table_lock: bool = False,
+    keep_nulls: bool = False,
+    fire_triggers: bool = False,
+    use_internal_transaction: bool = False,
+) -> Dict[str, Any]: ...
+def DDBCBulkCopyArrow(
+    handle: Any,
+    table_name: str,
+    source: Any,
+    batch_size: int = 0,
+    timeout: int = 30,
+    column_mappings: Optional[Any] = None,
+    keep_identity: bool = False,
+    check_constraints: bool = False,
+    table_lock: bool = False,
+    keep_nulls: bool = False,
+    fire_triggers: bool = False,
+    use_internal_transaction: bool = False,
+) -> Dict[str, Any]: ...
+def SQLExecuteManyRows(statementHandle: Any, query: str, rows: Any) -> Optional[int]: ...
+
+# ---------------------------------------------------------------------------
+# Native asyncio (Unix only; absent on Windows). Use mssql_python.aio instead.
+# ---------------------------------------------------------------------------
+
+class AioHub:
+    def __init__(self, event_loop: Any, shape_factory: Any) -> None: ...
+    def fileno(self) -> int: ...
+    def drain(self) -> None: ...
+    def pending(self) -> int: ...
+
+class AioRowBatch:
+    def next(self) -> Any: ...
+    def take(self, n: int) -> List[Any]: ...
+    def remaining(self) -> int: ...
+    def shape(self) -> Any: ...
+
+class AioConnection:
+    autocommit: bool
+    timeout: int
+    def execute(self, *args: Any) -> Any: ...
+    def executemany(self, *args: Any) -> Any: ...
+    def fetch(self, *args: Any) -> Any: ...
+    def fetch_arrow(self, *args: Any) -> Any: ...
+    def nextset(self, *args: Any) -> Any: ...
+    def query(self, *args: Any) -> Any: ...
+    def cursor(self) -> Any: ...
+    def close_cursor(self, *args: Any) -> Any: ...
+    def commit(self) -> Any: ...
+    def rollback(self) -> Any: ...
+    def set_autocommit(self, value: bool) -> Any: ...
+    def cancel(self) -> None: ...
+    def close(self) -> Any: ...
+    def open_cursors(self) -> int: ...
+
+class AioPool:
+    max_size: int
+    timeout: int
+    def acquire(self) -> Any: ...
+    def query(self, *args: Any) -> Any: ...
+    def cancel(self) -> None: ...
+    def close(self) -> Any: ...
+    def idle(self) -> int: ...
+    def in_use(self) -> int: ...
+
+def aio_connect(
+    hub: AioHub,
+    conn_str: str,
+    autocommit: bool = False,
+    timeout: int = 0,
+    tuple_rows: bool = False,
+) -> Any: ...
+def aio_create_pool(
+    hub: AioHub,
+    conn_str: str,
+    min_size: int = 1,
+    max_size: int = 10,
+    autocommit: bool = True,
+    timeout: int = 0,
+    tuple_rows: bool = False,
+    reset: bool = True,
+) -> Any: ...
+
+# ---------------------------------------------------------------------------
+# Upstream-compatible surface (see docs/CONTRACT.md for argument details)
+# ---------------------------------------------------------------------------
+
+class ErrorInfo:
+    sqlState: str
+    ddbcErrorMsg: str
+    nativeError: int
+
+class SqlHandle:
+    def free(self) -> None: ...
+    def _close_cursor(self) -> None: ...
+    def _cancel(self) -> None: ...
+
+class ParamInfo: ...
+class NumericData: ...
+
+class Connection:
+    def __init__(
+        self,
+        conn_str: str,
+        use_pool: bool,
+        attrs_before: Optional[Dict[int, Any]] = None,
+        pool_key: str = "",
+        token_factory: Optional[Any] = None,
+    ) -> None: ...
+    def close(self, transaction_already_rolled_back: bool = False) -> None: ...
+    def commit(self) -> None: ...
+    def rollback(self) -> None: ...
+    def set_autocommit(self, value: bool) -> None: ...
+    def get_autocommit(self) -> bool: ...
+    def set_attr(self, attribute: int, value: Any) -> None: ...
+    def alloc_statement_handle(self) -> SqlHandle: ...
+    def get_info(self, info_type: int) -> Any: ...
+
+def DDBCSQLExecDirect(statement: Any, query: str) -> int: ...
+def DDBCSQLExecute(
+    statementHandle: Any,
+    query: str,
+    params: Any,
+    inputSizes: Any,
+    isStmtPrepared: Any,
+    usePrepare: bool,
+    encodingSettings: Any,
+) -> int: ...
+def SQLExecuteMany(
+    statementHandle: Any,
+    query: str,
+    columnwise_params: Any,
+    paramInfos: Any,
+    paramSetSize: int,
+    encodingSettings: Any,
+) -> int: ...
+def DDBCSQLRowCount(statement: Any) -> int: ...
+def DDBCSQLNumResultCols(statementHandle: Any, messages: Optional[List[Any]] = None) -> int: ...
+def DDBCSQLMoreResults(statement: Any) -> int: ...
+def DDBCSQLResetStmt(statement: Any) -> int: ...
+def DDBCSQLCheckError(handleType: int, handle: Any, retcode: int) -> ErrorInfo: ...
+def DDBCSQLGetAllDiagRecords(handle: Any) -> List[Tuple[str, str]]: ...
+def enable_pooling(max_size: int = 100, idle_timeout: int = 600) -> None: ...
+def close_pooling() -> None: ...
+def disable_pooling() -> None: ...
+def update_log_level(level: int) -> None: ...
+def __getattr__(name: str) -> Any: ...
+
+def utf8_wrap_query(
+    query: str, columns: List[Tuple[Optional[str], int, int, Optional[bool]]]
+) -> Optional[Tuple[str, str]]: ...
+def utf8_collations_supported(
+    product_major_version: Optional[int], engine_edition: Optional[int]
+) -> bool: ...

arrowsql/decimal_config.py

@@ -0,0 +1,98 @@
+"""
+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 arrowsql.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 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 arrowsql.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 settings.decimal_separator
+
+    return setter, getter