snowflake-connector-python 5.0.0b1__cp311-cp311-win_arm64.whl

snowflake/connector/__init__.py

@@ -0,0 +1,112 @@
+"""
+PEP 249 Database API 2.0 Implementation
+
+This module provides an empty implementation of the Python Database API Specification 2.0
+as defined in PEP 249.
+"""
+
+from typing import Any
+
+from . import util_text  # noqa: F401 - backward compatibility re-exports
+from ._internal.api_client.c_api import register_default_logger_callback  # noqa: F401
+from ._internal.decorators import pep249
+from .connection import Connection, SnowflakeConnection
+from .constants import QueryStatus, StatementParameterName
+from .cursor import DictCursor, SnowflakeCursor
+from .errors import (
+    DatabaseError,
+    DataError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    Warning,
+)
+from .types import (
+    BINARY,
+    DATETIME,
+    NUMBER,
+    ROWID,
+    STRING,
+    Binary,
+    Date,
+    DateFromTicks,
+    Time,
+    TimeFromTicks,
+    Timestamp,
+    TimestampFromTicks,
+)
+from .version import __version__
+
+
+# PEP 249 Module Interface Constants
+apilevel = "2.0"
+threadsafety = 2  # Threads may share the module and connections, but not cursors
+paramstyle = "pyformat"  # Default: %(name)s and %s placeholders (client-side interpolation)
+
+
+@pep249
+def connect(**kwargs: Any) -> Connection:
+    """
+    Create a connection to the database.
+
+    Args:
+        database: Database name
+        user: Username
+        password: Password
+        host: Host name
+        port: Port number
+        **kwargs: Additional connection parameters
+
+    Returns:
+        Connection: A Connection object
+    """
+    return Connection(**kwargs)
+
+
+# Export all public symbols
+__all__ = [
+    # Version
+    "__version__",
+    # Module constants
+    "apilevel",
+    "threadsafety",
+    "paramstyle",
+    # Connection function
+    "connect",
+    # Classes
+    "Connection",
+    "SnowflakeConnection",
+    "QueryStatus",
+    "StatementParameterName",
+    "DictCursor",
+    "SnowflakeCursor",
+    # Exceptions
+    "Warning",
+    "Error",
+    "InterfaceError",
+    "DatabaseError",
+    "DataError",
+    "OperationalError",
+    "IntegrityError",
+    "InternalError",
+    "ProgrammingError",
+    "NotSupportedError",
+    # Type constructors
+    "Date",
+    "Time",
+    "Timestamp",
+    "DateFromTicks",
+    "TimeFromTicks",
+    "TimestampFromTicks",
+    "Binary",
+    # Type objects
+    "STRING",
+    "BINARY",
+    "NUMBER",
+    "DATETIME",
+    "ROWID",
+]

snowflake/connector/_internal/__init__.py

@@ -0,0 +1,6 @@
+"""Internal module for snowflake.ud_connector."""
+
+from .decorators import internal_api
+
+
+__all__ = ["internal_api"]

snowflake/connector/_internal/_private_key_helper.py

@@ -0,0 +1,50 @@
+"""Helper functions for private key conversion."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import ProgrammingError
+
+
+def normalize_private_key(private_key: Any) -> bytes | str:
+    """
+    Normalize private_key to a format that can be sent to the Rust core.
+
+    The Rust core handles:
+    - bytes: DER format (sent via connection_set_option_bytes)
+    - str: base64-encoded PEM or DER (sent via connection_set_option_string)
+
+    This function only converts RSAPrivateKey objects to bytes.
+    bytes and str are passed through as-is.
+
+    Args:
+        private_key: Private key in one of the supported formats:
+                     - bytes (DER format)
+                     - str (base64-encoded PEM or DER)
+                     - RSAPrivateKey object
+
+    Returns:
+        bytes or str: Private key ready to be sent to Rust core
+
+    Raises:
+        ProgrammingError: If the private_key type is not supported or conversion fails
+    """
+    if isinstance(private_key, (bytes, str)):
+        # Pass through - Rust handles DER bytes and base64-encoded strings (PEM or DER)
+        return private_key
+
+    # Handle RSAPrivateKey object from cryptography library
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
+
+    if isinstance(private_key, RSAPrivateKey):
+        return private_key.private_bytes(
+            encoding=serialization.Encoding.DER,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+    raise ProgrammingError(
+        f"Unsupported private_key type: {type(private_key)}. "
+        "Expected bytes, str (base64-encoded), or RSAPrivateKey object."
+    )

snowflake/connector/_internal/api_client/__init__.py

@@ -0,0 +1,6 @@
+"""Initialize the core API with the default logger callback."""
+
+from .c_api import c_logger_callback, sf_core_init
+
+
+sf_core_init(c_logger_callback)

snowflake/connector/_internal/api_client/c_api.py

@@ -0,0 +1,187 @@
+import ctypes
+import functools
+import logging
+import os
+import sys
+
+from enum import Enum
+from importlib import resources
+from typing import Any
+
+from ..logging import get_sf_core_logger
+
+
+_CORE_LIB_STEM = "sf_core"
+_CORE_LIB_NAME = f"lib{_CORE_LIB_STEM}"
+
+
+class CORE_API(Enum):
+    DATABASE_DRIVER_API_V1 = 1
+
+
+class CAPIHandle(ctypes.Structure):
+    _fields_ = [("id", ctypes.c_int64), ("magic", ctypes.c_int64)]
+
+
+def _get_core_path() -> Any:
+    # Define the file name for each platform.
+    # On Windows, cdylib crates produce "sf_core.dll" (no lib prefix).
+    # On Unix, they produce "libsf_core.so" / "libsf_core.dylib".
+    if sys.platform.startswith("win"):
+        lib_name = f"{_CORE_LIB_STEM}.dll"
+    elif sys.platform.startswith("darwin"):
+        lib_name = f"{_CORE_LIB_NAME}.dylib"
+    else:
+        lib_name = f"{_CORE_LIB_NAME}.so"
+
+    files = resources.files("snowflake.connector")
+    return files.joinpath("_core").joinpath(lib_name)
+
+
+def _load_core() -> ctypes.CDLL:
+    path = _get_core_path()
+    with resources.as_file(path) as lib_path:
+        lib_path_str = str(lib_path)
+        if sys.platform.startswith("win"):
+            # ctypes.CDLL on Python 3.8+ uses restricted DLL search; register
+            # _core/ so the Windows loader finds sf_core.dll's co-located deps.
+            os.add_dll_directory(os.fspath(lib_path.parent))
+        try:
+            return ctypes.CDLL(lib_path_str)
+        except OSError as err:
+            raise OSError(f"Couldn't load core driver (path={lib_path_str})") from err
+
+
+try:
+    core = _load_core()
+except OSError as err:
+    raise RuntimeError("Couldn't load core driver dependency") from err
+
+LOGGER_CALLBACK = ctypes.CFUNCTYPE(
+    ctypes.c_uint32, ctypes.c_uint32, ctypes.c_char_p, ctypes.c_char_p, ctypes.c_uint32, ctypes.c_char_p
+)
+core.sf_core_init.argtypes = [LOGGER_CALLBACK]
+core.sf_core_init.restype = ctypes.c_uint32
+
+core.sf_core_api_call_proto.restype = ctypes.c_uint32
+core.sf_core_api_call_proto.argtypes = [
+    ctypes.c_char_p,  # const char* api
+    ctypes.c_char_p,  # const char* method
+    ctypes.POINTER(ctypes.c_ubyte),  # const char* request
+    ctypes.c_size_t,  # size_t request_len
+    ctypes.POINTER(ctypes.POINTER(ctypes.c_ubyte)),  # char* const* response
+    ctypes.POINTER(ctypes.c_size_t),  # size_t* response_len
+]
+
+core.sf_core_free_buffer.restype = None
+core.sf_core_free_buffer.argtypes = [
+    ctypes.POINTER(ctypes.c_ubyte),  # uint8_t* buffer
+    ctypes.c_size_t,  # size_t len
+]
+
+
+# Performance instrumentation FFI bindings (see sf_core/src/c_api.rs).
+# These symbols are always present in libsf_core; when the perf_timing feature
+# is off they return empty/no-op results. Callers use sf_core_perf_enabled() to
+# check whether real data is available.
+core.sf_core_perf_enabled.argtypes = []
+core.sf_core_perf_enabled.restype = ctypes.c_bool
+
+
+class CoreInstrumentationData(ctypes.Structure):
+    """Mirrors #[repr(C)] CoreInstrumentationData from sf_core::perf_timing."""
+
+    _fields_ = [
+        ("core_batch_wait_ns", ctypes.c_uint64),
+        ("core_chunk_download_ns", ctypes.c_uint64),
+        ("core_arrow_decode_ns", ctypes.c_uint64),
+    ]
+
+
+core.sf_core_get_perf_data.argtypes = []
+core.sf_core_get_perf_data.restype = CoreInstrumentationData
+
+core.sf_core_reset_perf_metrics.argtypes = []
+core.sf_core_reset_perf_metrics.restype = None
+
+
+def sf_core_api_call_proto(
+    api: ctypes.c_char_p,
+    method: ctypes.c_char_p,
+    request: Any,
+    request_len: int,
+    response: Any,
+    response_len: Any,
+) -> int:
+    return core.sf_core_api_call_proto(api, method, request, request_len, response, response_len)  # type: ignore
+
+
+def sf_core_free_buffer(buffer: Any, length: int) -> None:
+    core.sf_core_free_buffer(buffer, length)
+
+
+def sf_core_init(callback: Any) -> None:
+    core.sf_core_init(callback)
+
+
+level_map = {
+    # sf_core level -> python logging level
+    0: logging.ERROR,
+    1: logging.WARNING,
+    2: logging.INFO,
+    3: logging.DEBUG,
+}
+
+
+def logger_callback(level: int, message: bytes, filename: bytes, line: int, function: bytes) -> int:
+    py_level = level_map.get(level)
+    if py_level is None:
+        return 0
+
+    sf_core_logger = get_sf_core_logger()
+    # Respect the logger's configured level - skip if not enabled
+    if not sf_core_logger.isEnabledFor(py_level):
+        return 0
+
+    record = sf_core_logger.makeRecord(
+        sf_core_logger.name,
+        py_level,
+        filename.decode("utf-8"),
+        line,
+        message.decode("utf-8"),
+        (),
+        None,
+        func=function.decode("utf-8"),
+    )
+    sf_core_logger.handle(record)
+    return 0
+
+
+c_logger_callback = LOGGER_CALLBACK(logger_callback)
+
+
+def register_default_logger_callback() -> None:
+    """
+    Register the default logger callback with the core API.
+    Call this function explicitly to set up logging.
+    """
+    sf_core_init(c_logger_callback)
+
+
+@functools.lru_cache(maxsize=1)
+def sf_core_perf_enabled() -> bool:
+    return bool(core.sf_core_perf_enabled())
+
+
+def sf_core_get_perf_data() -> dict[str, float]:
+    """Atomically read-and-reset perf counters, returning seconds."""
+    data: CoreInstrumentationData = core.sf_core_get_perf_data()
+    return {
+        "core_batch_wait_s": data.core_batch_wait_ns / 1e9,
+        "core_chunk_download_s": data.core_chunk_download_ns / 1e9,
+        "core_arrow_decode_s": data.core_arrow_decode_ns / 1e9,
+    }
+
+
+def sf_core_reset_perf_metrics() -> None:
+    core.sf_core_reset_perf_metrics()

snowflake/connector/_internal/api_client/client_api.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import ctypes
+import threading
+
+from ctypes import c_char_p
+from typing import Any
+
+from snowflake.connector._internal.status_codes import (
+    STATUS_CODE_LABELS,
+    STATUS_TO_ERRNO,
+    STATUS_TO_EXCEPTION,
+    VENDOR_CODE_TO_EXCEPTION,
+)
+from snowflake.connector.errors import DatabaseError, Error, OperationalError
+
+from ..protobuf_gen.database_driver_v1_pb2 import (
+    AuthenticationError as ProtoAuthenticationError,
+)
+from ..protobuf_gen.database_driver_v1_pb2 import (
+    InvalidParameterValue as ProtoInvalidParameterValue,
+)
+from ..protobuf_gen.database_driver_v1_pb2 import (
+    LoginError as ProtoLoginError,
+)
+from ..protobuf_gen.database_driver_v1_pb2 import (
+    MissingParameter as ProtoMissingParameter,
+)
+from ..protobuf_gen.database_driver_v1_services import DatabaseDriverClient
+from ..protobuf_gen.proto_exception import (
+    ProtoApplicationException,
+    ProtoTransportException,
+)
+from .c_api import sf_core_api_call_proto, sf_core_free_buffer
+
+
+# ---------------------------------------------------------------------------
+# Proto-to-PEP-249 error conversion (kept here, at the transport boundary)
+# ---------------------------------------------------------------------------
+
+
+def _extract_error_detail(driver_exception: Any) -> str | None:
+    error = getattr(driver_exception, "error", None)
+    if error is None:
+        return None
+
+    error_type = error.WhichOneof("error_type")
+    if error_type is None:
+        return None
+
+    inner = getattr(error, error_type, None)
+    if inner is None:
+        return None
+
+    if isinstance(inner, ProtoAuthenticationError):
+        return inner.detail or None
+    if isinstance(inner, ProtoLoginError):
+        if inner.message and inner.code:
+            return f"{inner.message} (code={inner.code})"
+        return inner.message or None
+    if isinstance(inner, ProtoMissingParameter):
+        return f"Missing required parameter: {inner.parameter}" if inner.parameter else None
+    if isinstance(inner, ProtoInvalidParameterValue):
+        parts = [f"Invalid value {inner.value!r} for parameter {inner.parameter!r}"]
+        if inner.explanation:
+            parts.append(inner.explanation)
+        return ". ".join(parts)
+    # GenericError, InternalError have no extra fields
+    return None
+
+
+def _append_detail(base: str, detail: str) -> str:
+    """Append *detail* to *base* with `. ` separator, avoiding double punctuation."""
+    if not base:
+        return detail
+    base = base.rstrip(".")
+    return f"{base}. {detail}"
+
+
+def _proto_to_public_error(proto_exc: Exception) -> Error:
+    """Convert a proto-layer exception into a PEP 249 ``Error`` subclass.
+
+    This function **returns** the converted exception; it does not raise it.
+    The caller (``_raise_error`` in the generated client) is responsible for
+    raising the returned value.
+    """
+    if isinstance(proto_exc, ProtoApplicationException):
+        return _convert_application_error(proto_exc)
+    if isinstance(proto_exc, ProtoTransportException):
+        return OperationalError(f"Driver communication error: {proto_exc}")
+    return DatabaseError(str(proto_exc))
+
+
+def _resolve_exception_class(status_code: int, vendor_code: int | None) -> type[Error]:
+    """Pick the PEP 249 exception class for a proto error.
+
+    Resolution order:
+      1. VENDOR_CODE_TO_EXCEPTION — Snowflake-specific vendor_code overrides (e.g. 100072 → IntegrityError).
+      2. STATUS_TO_EXCEPTION — default mapping from the proto StatusCode.
+      3. DatabaseError — catch-all when the status code is unrecognized.
+    """
+    if vendor_code is not None:
+        cls = VENDOR_CODE_TO_EXCEPTION.get(vendor_code)
+        if cls is not None:
+            return cls
+    return STATUS_TO_EXCEPTION.get(status_code, DatabaseError)
+
+
+def _convert_application_error(proto_exc: ProtoApplicationException) -> Error:
+    driver_exc = getattr(proto_exc, "api_error_pb", None)
+    if driver_exc is None:
+        return DatabaseError(str(proto_exc))
+
+    status_code = getattr(driver_exc, "status_code", 0)
+    message = getattr(driver_exc, "message", "") or ""
+
+    # The root_cause field carries the deepest error in the chain from the
+    # Rust core, which is typically the most informative for end users.
+    root_cause = _get_optional_str(driver_exc, "root_cause")
+    if root_cause and root_cause not in message:
+        message = _append_detail(message, root_cause)
+
+    detail = _extract_error_detail(driver_exc)
+    if detail and detail not in message:
+        message = _append_detail(message, detail)
+
+    if not message:
+        message = STATUS_CODE_LABELS.get(status_code, "Unknown error")
+
+    # Prefer the Snowflake server vendor_code when the core driver provides it
+    # (e.g. 1003 for syntax error, 904 for invalid identifier).
+    # Fall back to the old-driver-compatible errno mapping, then to the raw
+    # proto status code.
+    vendor_code = _get_optional_int(driver_exc, "vendor_code")
+
+    exc_class = _resolve_exception_class(status_code, vendor_code)
+    errno = vendor_code if vendor_code is not None else STATUS_TO_ERRNO.get(status_code, status_code)
+
+    # Prefer the server-provided sql_state; fall back to a type-derived value.
+    sqlstate = _get_optional_str(driver_exc, "sql_state") or _derive_sqlstate(driver_exc)
+
+    sfqid = _get_optional_str(driver_exc, "query_id")
+
+    return exc_class(message, errno=errno, sqlstate=sqlstate, sfqid=sfqid)
+
+
+def _get_optional_int(msg: Any, field: str) -> int | None:
+    """Read an optional int32 proto field, returning None if not set."""
+    try:
+        if msg.HasField(field):
+            return int(getattr(msg, field))
+    except (ValueError, TypeError, AttributeError):
+        # Field missing from the proto schema or cannot be coerced to int; treat as unset.
+        pass
+    return None
+
+
+def _get_optional_str(msg: Any, field: str) -> str | None:
+    """Read an optional string proto field, returning None if not set."""
+    try:
+        if msg.HasField(field):
+            return str(getattr(msg, field)) or None
+    except (ValueError, TypeError, AttributeError):
+        # Field missing from the proto schema or cannot be coerced to string; treat as unset.
+        pass
+    return None
+
+
+def _derive_sqlstate(driver_exception: Any) -> str | None:
+    """Derive sqlstate from the error type when the proto does not carry it.
+
+    Only login/auth errors have an obvious ANSI SQL state mapping today.
+    Other error types (missing_parameter, invalid_parameter_value, etc.)
+    will return ``None``; extend this function as mappings become clear.
+    """
+    error = getattr(driver_exception, "error", None)
+    if error is None:
+        return None
+    error_type = error.WhichOneof("error_type")
+    if error_type in ("login_error", "auth_error"):
+        return "08001"  # SQLSTATE_CONNECTION_WAS_NOT_ESTABLISHED
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Transport + singleton
+# ---------------------------------------------------------------------------
+
+
+class ProtoTransport:
+    def handle_message(self, api: str, method: str, message: bytes) -> tuple[int, bytes]:
+        response = ctypes.POINTER(ctypes.c_ubyte)()
+        response_len = ctypes.c_size_t()
+        api_bytes: c_char_p = ctypes.c_char_p(api.encode("utf-8"))
+        method_bytes: c_char_p = ctypes.c_char_p(method.encode("utf-8"))
+        message_buf = (ctypes.c_ubyte * len(message))()
+        message_buf[:] = message  # type: ignore
+        code = sf_core_api_call_proto(
+            api_bytes,
+            method_bytes,
+            ctypes.cast(message_buf, ctypes.POINTER(ctypes.c_ubyte)),
+            len(message),
+            ctypes.byref(response),
+            ctypes.byref(response_len),
+        )
+        if code == 0 or code == 1 or code == 2:
+            result = bytes(response[: response_len.value])
+            sf_core_free_buffer(response, response_len.value)
+            return (code, result)
+
+        raise ProtoTransportException(f"Unknown error code: {code}")
+
+
+_DATABASE_DRIVER_CLIENT: DatabaseDriverClient | None = None
+_DATABASE_DRIVER_CLIENT_LOCK = threading.Lock()
+
+
+def database_driver_client() -> DatabaseDriverClient:
+    global _DATABASE_DRIVER_CLIENT
+    if _DATABASE_DRIVER_CLIENT is None:
+        with _DATABASE_DRIVER_CLIENT_LOCK:
+            if _DATABASE_DRIVER_CLIENT is None:
+                _DATABASE_DRIVER_CLIENT = DatabaseDriverClient(ProtoTransport(), error_handler=_proto_to_public_error)
+    return _DATABASE_DRIVER_CLIENT