snowflake-connector-python 5.2.0__cp315-cp315-macosx_11_0_arm64.whl

snowflake/connector/__init__.py

@@ -0,0 +1,136 @@
+"""
+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 __future__ import annotations
+
+from typing import Any
+
+from . import util_text  # noqa: F401 - backward compatibility re-exports
+from ._internal.decorators import pep249
+from ._internal.fips import FipsStatus, get_fips_status
+from .connection import Connection, SnowflakeConnection
+from .connection_config import ConnectionConfig
+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)
+
+
+# Sentinel to distinguish "not provided" from explicit values. Forwarding ``None``
+# defaults would make ``@api_telemetry`` treat connection_name/config as passed.
+_UNSET = object()
+
+
+@pep249
+def connect(
+    *,
+    connection_name: str | None | object = _UNSET,
+    connections_file_path: str | None | object = _UNSET,
+    config: ConnectionConfig | None | object = _UNSET,
+    **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
+    """
+    conn_kwargs = dict(kwargs)
+    if connection_name is not _UNSET:
+        conn_kwargs["connection_name"] = connection_name
+    if connections_file_path is not _UNSET:
+        conn_kwargs["connections_file_path"] = connections_file_path
+    if config is not _UNSET:
+        conn_kwargs["config"] = config
+    return Connection(**conn_kwargs)
+
+
+# Export all public symbols
+__all__ = [
+    # Version
+    "__version__",
+    # Module constants
+    "apilevel",
+    "threadsafety",
+    "paramstyle",
+    # Module functions
+    "connect",
+    "get_fips_status",
+    # Classes
+    "FipsStatus",
+    "ConnectionConfig",
+    "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/_common/extras.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import functools
+import importlib
+
+from collections.abc import Callable
+from importlib import metadata
+from types import ModuleType
+from typing import Any, TypeVar, cast
+
+from snowflake.connector import errors
+from snowflake.connector._internal.errorcode import ER_NO_NUMPY, ER_NO_PYARROW
+
+from .._internal.logging import get_logger
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+logger = get_logger(__name__)
+
+DEP_PYARROW = "pyarrow"
+DEP_PANDAS = "pandas"
+DEP_NUMPY = "numpy"
+DEP_TZLOCAL = "tzlocal"
+DEP_SQLALCHEMY = "sqlalchemy"
+
+"""This module helps to manage optional dependencies.
+
+It implements MissingOptionalDependency. If a module is unavailable an instance of this will be
+returned. The point of this class is that if someone tries to use pyarrow code then by importing
+pyarrow from this module if they did pyarrow.xxx then that would raise a MissingDependencyError.
+"""
+
+
+class MissingOptionalDependency:
+    """A class to replace missing dependencies.
+
+    The only thing this class is supposed to do is raise a MissingDependencyError when __getattr__ is called.
+    This will be triggered whenever module.member is going to be called.
+
+    Supports two construction patterns:
+    - ``MissingOptionalDependency("pandas")`` — sets dep name from argument.
+    - No-arg subclass with a ``_dep_name`` class attribute (Snowpark pattern):
+      ``class MissingFoo(MissingOptionalDependency): _dep_name = "foo"``
+    """
+
+    _dep_name: str = "not set"
+
+    def __init__(self, dep: str | None = None) -> None:
+        if dep is not None:
+            self._dep_name = dep
+
+    def __getattr__(self, item: str) -> Any:
+        raise errors.MissingDependencyError(self._dep_name)
+
+    @property
+    def dep_name(self) -> str:
+        return self._dep_name
+
+
+def _import_or_missing(module_name: str) -> ModuleType | MissingOptionalDependency:
+    """Try importing an optional dependency.
+
+    If available it returns the module. Otherwise, returns a MissingOptionalDependency stub.
+    """
+    try:
+        mod = importlib.import_module(module_name)
+        try:
+            version = metadata.version(module_name)
+        except metadata.PackageNotFoundError:
+            version = "unknown"
+        logger.info("%s is installed (version: %s)", module_name, version)
+        return mod
+    except ImportError:
+        logger.info("%s is not installed; %s-based features will be unavailable", module_name, module_name)
+        return MissingOptionalDependency(dep=module_name)
+
+
+def check_dependency(module: ModuleType | MissingOptionalDependency) -> None:
+    """Raise ProgrammingError if optional dependency is not installed."""
+    if isinstance(module, MissingOptionalDependency):
+        if module.dep_name in (DEP_PYARROW, DEP_PANDAS):
+            msg = (
+                f"Optional dependency: '{module.dep_name}' is not installed, please see the following link for"
+                " install instructions: https://docs.snowflake.com/en/user-guide/python-connector-pandas.html#installation"
+            )
+            raise errors.ProgrammingError(msg=msg, errno=ER_NO_PYARROW)
+        elif module.dep_name == DEP_NUMPY:
+            msg = "Numpy module is not installed. Cannot fetch data as numpy"
+            raise errors.ProgrammingError(msg=msg, errno=ER_NO_NUMPY)
+        else:
+            raise errors.MissingDependencyError(module.dep_name)
+
+
+def requires_dependency(*modules: ModuleType | MissingOptionalDependency) -> Callable[[F], F]:
+    """Raise ProgrammingError if any of the listed dependencies are not installed."""
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            for mod in modules:
+                check_dependency(mod)
+            return func(*args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator
+
+
+def _import_pandas() -> ModuleType | MissingOptionalDependency:
+    """Lazily import pandas, returning MissingOptionalDependency if not
+    installed.
+    """
+    result = _import_or_missing(DEP_PANDAS)
+    if not isinstance(result, MissingOptionalDependency):
+        # If relative imports without dots are enabled (Snowpark's case), this
+        # import can fail when run from certain test directories.
+        from pandas import DataFrame  # noqa: F401
+    return result
+
+
+pyarrow = _import_or_missing(DEP_PYARROW)
+pandas = _import_pandas()
+numpy = _import_or_missing(DEP_NUMPY)
+tzlocal = _import_or_missing(DEP_TZLOCAL)
+sqlalchemy = _import_or_missing(DEP_SQLALCHEMY)
+
+
+# Snowpark imported these three names from ``snowflake.connector.options``
+# (now this module). The Universal Driver does not use them itself.
+ModuleLikeObject = ModuleType | MissingOptionalDependency
+
+installed_pandas: bool = not isinstance(pandas, MissingOptionalDependency)
+installed_pyarrow: bool = not isinstance(pyarrow, MissingOptionalDependency)

snowflake/connector/_common/telemetry.py

@@ -0,0 +1,221 @@
+"""In-band telemetry client that sends events to sf_core via protobuf RPC.
+
+All methods are fire-and-forget: failures are logged at DEBUG level and never
+propagate to the caller.
+"""
+
+from __future__ import annotations
+
+import json
+
+from enum import Enum, unique
+from typing import TYPE_CHECKING, Any
+
+from .._internal.api_client.client_api import async_core_driver, core_driver
+from .._internal.backward_compatibility import install_backward_compatibility_getattr
+from .._internal.decorators import backward_compatibility
+from .._internal.logging import get_logger
+from ..errors import InterfaceError
+
+
+if TYPE_CHECKING:
+    from snowflake.connector._internal.protobuf_gen.database_driver_v1_services import (
+        ConnectionHandle,
+    )
+
+logger = get_logger(__name__)
+
+
+@backward_compatibility
+@unique
+class TelemetryField(Enum):
+    """Old-driver keys for telemetry message dicts."""
+
+    KEY_SOURCE = "source"
+    KEY_TYPE = "type"
+    KEY_SFQID = "query_id"
+
+
+@backward_compatibility
+class TelemetryData:
+    """Old-driver telemetry data holder, forwarded to :class:`TelemetryClient`."""
+
+    TRUE = "true"
+    FALSE = "false"
+
+    def __init__(self, message: Any = None, timestamp: int = 0) -> None:
+        self.message = message
+        self.timestamp = timestamp
+
+    @classmethod
+    def from_telemetry_data_dict(
+        cls,
+        from_dict: dict[str, Any],
+        timestamp: int,
+        connection: Any = None,
+        is_oob_telemetry: bool = False,
+    ) -> TelemetryData:
+        return cls(message=from_dict, timestamp=timestamp)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"message": self.message, "timestamp": str(self.timestamp)}
+
+
+class TelemetryClient:
+    """Sends telemetry events to sf_core via protobuf RPC.
+
+    Wrapper identity is passed as part of ``connection_init``. This client only
+    sends runtime events — sf_core attaches the stored identity automatically.
+    """
+
+    def __init__(self, conn_handle: ConnectionHandle) -> None:
+        self._conn_handle = conn_handle
+        self._closed = False
+
+    def close(self) -> None:
+        self._closed = True
+
+    def send_api_usage(self, api_method: str, passed_arguments: list[str] | None = None) -> None:
+        """Record an API method call for telemetry.
+
+        ``passed_arguments`` lists the names of the arguments the caller
+        explicitly supplied (names only, no values, defaults omitted).
+        """
+        if self._closed:
+            return
+        try:
+            core_driver.telemetry_send_api_usage(
+                conn_handle=self._conn_handle,
+                api_method=api_method,
+                passed_arguments=passed_arguments or [],
+            )
+        except Exception:
+            logger.debug("Failed to send api_usage telemetry", exc_info=True)
+
+    def send_wrapper_error(self, exception_type: str, error_source: str) -> None:
+        """Record a wrapper error for telemetry."""
+        if self._closed:
+            return
+        try:
+            core_driver.telemetry_send_wrapper_error(
+                conn_handle=self._conn_handle,
+                exception_type=exception_type,
+                error_source=error_source,
+            )
+        except Exception:
+            logger.debug("Failed to send wrapper_error telemetry", exc_info=True)
+
+    def add_log_to_batch(self, telemetry_data: TelemetryData) -> None:
+        """Forward one caller-produced telemetry entry (e.g. Snowpark's) to sf_core.
+
+        Core owns batching, flush threshold, and ``/telemetry/send`` egress.
+        Raises :class:`~snowflake.connector.errors.InterfaceError` if the client
+        has been closed; use :meth:`try_add_log_to_batch` for the fire-and-forget
+        hot path.
+        """
+        if self._closed:
+            raise InterfaceError(
+                "Cannot add log to batch: TelemetryClient is closed. Obtain a fresh client from a new connection."
+            )
+        core_driver.telemetry_send_log(
+            conn_handle=self._conn_handle,
+            message_json=json.dumps(telemetry_data.message),
+            timestamp_ms=int(telemetry_data.timestamp),
+        )
+
+    def try_add_log_to_batch(self, telemetry_data: TelemetryData) -> None:
+        """Exception-swallowing wrapper over :meth:`add_log_to_batch` — the hot path."""
+        try:
+            self.add_log_to_batch(telemetry_data)
+        except Exception:
+            logger.debug("Failed to add log to telemetry", exc_info=True)
+
+    def send_batch(self) -> None:
+        """No-op: flush is owned by the Rust core (threshold + connection release).
+
+        Only an explicit close() or normal process exit (atexit) reliably
+        flushes buffered telemetry. Neither this driver nor the legacy
+        connector installs a signal handler, so a killed process (SIGTERM or
+        SIGKILL) loses in-buffer entries — atexit does not run on signals.
+        See ``tests/integ/telemetry/test_telemetry_crash_flush.py``.
+
+        Kept for snowflake-cli API compatibility (``_app/telemetry.py``).
+        """
+
+    @backward_compatibility
+    def send_log_batch(self) -> None:
+        """No-op: the new driver sends telemetry via RPC immediately; there is no batch to flush."""
+
+
+class AsyncTelemetryClient:
+    """Async counterpart of :class:`TelemetryClient` for :class:`~snowflake.connector.aio.Connection`.
+
+    Uses :data:`~snowflake.connector._internal.api_client.client_api.async_core_driver`
+    so telemetry RPCs do not block the event loop.
+    """
+
+    def __init__(self, conn_handle: ConnectionHandle) -> None:
+        self._conn_handle = conn_handle
+        self._closed = False
+
+    def close(self) -> None:
+        self._closed = True
+
+    async def send_api_usage(self, api_method: str, passed_arguments: list[str] | None = None) -> None:
+        """Record an API method call for telemetry.
+
+        ``passed_arguments`` lists the names of the arguments the caller
+        explicitly supplied (names only, no values, defaults omitted).
+        """
+        if self._closed:
+            return
+        try:
+            await async_core_driver.telemetry_send_api_usage(
+                conn_handle=self._conn_handle,
+                api_method=api_method,
+                passed_arguments=passed_arguments or [],
+            )
+        except Exception:
+            logger.debug("Failed to send api_usage telemetry", exc_info=True)
+
+    async def send_wrapper_error(self, exception_type: str, error_source: str) -> None:
+        """Record a wrapper error for telemetry."""
+        if self._closed:
+            return
+        try:
+            await async_core_driver.telemetry_send_wrapper_error(
+                conn_handle=self._conn_handle,
+                exception_type=exception_type,
+                error_source=error_source,
+            )
+        except Exception:
+            logger.debug("Failed to send wrapper_error telemetry", exc_info=True)
+
+    async def add_log_to_batch(self, telemetry_data: TelemetryData) -> None:
+        """Forward one caller-produced telemetry entry (e.g. Snowpark's) to sf_core.
+
+        Core owns batching, flush threshold, and ``/telemetry/send`` egress.
+        Raises :class:`~snowflake.connector.errors.InterfaceError` if the client
+        has been closed; use :meth:`try_add_log_to_batch` for the fire-and-forget
+        hot path.
+        """
+        if self._closed:
+            raise InterfaceError(
+                "Cannot add log to batch: TelemetryClient is closed. Obtain a fresh client from a new connection."
+            )
+        await async_core_driver.telemetry_send_log(
+            conn_handle=self._conn_handle,
+            message_json=json.dumps(telemetry_data.message),
+            timestamp_ms=int(telemetry_data.timestamp),
+        )
+
+    async def try_add_log_to_batch(self, telemetry_data: TelemetryData) -> None:
+        """Exception-swallowing wrapper over :meth:`add_log_to_batch` — the hot path."""
+        try:
+            await self.add_log_to_batch(telemetry_data)
+        except Exception:
+            logger.debug("Failed to add log to telemetry", exc_info=True)
+
+
+# Must be the last statement; see ``install_backward_compatibility_getattr``.
+install_backward_compatibility_getattr(__name__)

snowflake/connector/_common/wif_util.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, unique
+
+from .._internal.api_client.client_api import core_driver
+from .._internal.decorators import snowpark_compat
+from .._internal.errorcode import ER_INVALID_WIF_SETTINGS
+from ..errors import ProgrammingError
+
+
+# Kept for legacy API compatibility; the Rust core uses its own copy of this constant.
+DEFAULT_ENTRA_SNOWFLAKE_RESOURCE = "api://fd3f753b-eed3-462c-b6a7-a4b5bb650aad"
+
+
+@unique
+class AttestationProvider(Enum):
+    """A WIF provider implementation that can produce an attestation."""
+
+    AWS = "AWS"
+    AZURE = "AZURE"
+    GCP = "GCP"
+    OIDC = "OIDC"
+
+    @staticmethod
+    def from_string(provider: str) -> AttestationProvider:
+        """Convert a string to a strongly-typed enum value of AttestationProvider."""
+        try:
+            return AttestationProvider[provider.upper()]
+        except KeyError:
+            allowed = ", ".join(AttestationProvider.all_string_values())
+            raise ProgrammingError(
+                msg=f"Unknown workload_identity_provider: '{provider}'. Expected one of: {allowed}",
+                errno=ER_INVALID_WIF_SETTINGS,
+            ) from None
+
+    @staticmethod
+    def all_string_values() -> list[str]:
+        """Return a list of all string values of the AttestationProvider enum."""
+        return [provider.value for provider in AttestationProvider]
+
+
+@dataclass
+class WorkloadIdentityAttestation:
+    provider: AttestationProvider
+    # repr=False: this is a bearer credential and must not leak into
+    # tracebacks, logs, or debugger output via the default dataclass repr.
+    credential: str = field(repr=False)
+    # Always empty; sf_core doesn't yet surface per-provider identifier metadata
+    # (AWS region/partition, GCP/Azure/OIDC iss/sub claims).
+    user_identifier_components: dict = field(default_factory=dict)
+
+
+@snowpark_compat
+def create_attestation(
+    provider: AttestationProvider,
+    entra_resource: str | None = None,
+    token: str | None = None,
+    impersonation_path: list[str] | None = None,
+    aws_use_outbound_token: bool | None = None,
+    wif_host: str | None = None,
+) -> WorkloadIdentityAttestation:
+    """Acquires a Workload Identity Federation attestation for the given provider.
+
+    Delegates to the Rust core's attestation logic (the same code path used by
+    the driver's own WIF login flow), independent of any active connection.
+
+    If an explicit entra_resource is provided it is forwarded to the Rust core;
+    otherwise the Rust core applies its own default for the Azure Entra resource.
+
+    `impersonation_path` is forwarded to the Rust core, which chains
+    `sts:AssumeRole` calls (AWS), delegate impersonation (GCP), or a
+    single-hop service-principal token exchange (Azure) exactly as the
+    driver's own WIF login flow does.
+
+    `wif_host` is forwarded as the AWS STS hostname override. Unset uses the
+    regional STS default.
+
+    Any other keyword argument raises `TypeError`.
+    """
+    response = core_driver.wif_create_attestation(
+        provider=provider.value,
+        entra_resource=entra_resource,
+        token=token,
+        impersonation_path=impersonation_path or [],
+        aws_use_outbound_token=aws_use_outbound_token,
+        wif_host=wif_host,
+    )
+    return WorkloadIdentityAttestation(
+        provider=AttestationProvider.from_string(response.provider),
+        credential=response.credential,
+    )

snowflake/connector/_core/sf_core_python.pyi

@@ -0,0 +1,79 @@
+"""Type stubs for the sf_core_python native extension (auto-generated)."""
+
+def init(logger_callback: object) -> tuple[int, bool]:
+    """Initialize the core state: logging, tokio runtime, and transport.
+
+    Called by the Python connector at import time, before any API call.
+    Must be called before any other function.
+
+    Returns `(status, troubleshooting_enabled)` where:
+    - `status`: `0` = success, non-zero = failure
+    - `troubleshooting_enabled`: whether troubleshooting mode is active at init time
+
+    If already initialised, returns success with the current troubleshooting flag
+    without creating another [`Bridge`].
+    """
+    ...
+
+def log_event(level: int, message: str, file: str, line: int, function: str, logger_name: str) -> int:
+    """Emit a wrapper-originated log event through the tracing pipeline.
+
+    Uses the same level encoding as the inbound wrapper log callback:
+    0=ERROR, 1=WARN, 2=INFO, 3 or higher=DEBUG.
+
+    Returns `0` on success, `1` when the pipeline is uninitialised, and `2` if the body panics.
+    """
+    ...
+
+def call_proto(api: str, method: str, request: bytes) -> tuple[int, bytes]:
+    """Synchronous proto API call. Releases the GIL and blocks until complete.
+
+    Returns `(status_code, response_bytes)` where status is:
+    - `0` — success
+    - `1` — application error (response holds the error payload)
+    - `2` — transport error (including panics / missing init caught at this boundary)
+    """
+    ...
+
+async def call_proto_async(api: str, method: str, request: bytes) -> object:
+    """Async proto API call. Returns a Python awaitable → `(status_code, response)`.
+
+    Same contract as [`call_proto`]: always returns `(u32, bytes)`, never raises
+    for protocol-level failures.
+
+    Python cancel drops the awaitable which fires the CancellationToken.
+    """
+    ...
+
+def perf_enabled() -> bool:
+    """Returns True if perf_timing feature is compiled in.
+    """
+    ...
+
+def get_perf_data() -> tuple[int, int, int]:
+    """Read-and-reset perf counters. Returns (batch_wait_ns, chunk_download_ns, arrow_decode_ns).
+    """
+    ...
+
+def reset_perf_metrics() -> None:
+    """Reset perf counters without reading.
+    """
+    ...
+
+def native_arrow_enabled() -> bool:
+    """Returns True if the ``native-arrow`` Cargo feature is compiled in.
+    """
+    ...
+
+def split_sql_script(sql: str, delimiter: str, remove_comments: bool) -> list[tuple[str, bool | None]]:
+    """Split a SQL script into statements.
+
+    Each item is the statement text and a PUT/GET flag: `True` for `PUT` and
+    `GET`, `False` for other statements and `!` commands, and `None` when the
+    text is empty or comment-only. The delimiter is rewritten as `;`.
+
+    An unterminated quote, block comment, or dollar quote keeps the rest of
+    the script in that statement. An empty delimiter raises `ValueError`.
+    """
+    ...
+

snowflake/connector/_internal/__init__.py

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