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

snowflake/connector/_internal/errorhandler.py

@@ -0,0 +1,278 @@
+"""PEP 249 error-handler routing via ``ErrorHandlerMixin``.
+
+How to raise errors in the driver:
+- Classes (Connection, Cursor, ResultBatch): inherit ``ErrorHandlerMixin``.
+  Public methods are wrapped automatically via ``__init_subclass__``.
+  Then use plain ``raise``.
+- Free functions with a ``conn`` argument (e.g. ``write_pandas``): wrap the body
+  in ``try/except Error`` and call ``route_exception(conn, None, exc)``.
+
+This wrapping is also where ``wrapper_error`` telemetry is collected (see
+``_report_wrapper_error`` / ``_report_wrapper_error_async``): every wrapped
+call that catches an exception reports it, tagged with its own method name,
+but only the outermost frame in a call chain hands the error to the PEP 249
+errorhandler, so PEP 249 routing still fires exactly once.
+
+Hot-path methods may use ``@simplified_error_handling`` instead of the mixin wrap:
+failures still go through ``_reraise_via_errorhandler``, but the success path
+skips the ContextVar round-trip.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+
+from collections.abc import Callable
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any, NoReturn, TypeVar, cast
+
+from ..errors import Error, ErrorDetails
+from .decorators import _schedule_async_telemetry, _telemetry_client_if_enabled
+from .logging import get_logger
+
+
+if TYPE_CHECKING:
+    from ..aio.connection import Connection as AsyncConnection
+    from ..aio.cursor import SnowflakeCursorBase as AsyncSnowflakeCursorBase
+    from ..connection import Connection
+    from ..cursor import SnowflakeCursorBase
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Set on an Error that has already been through ``route_exception`` / the
+# default handler, so a @simplified_error_handling hot path does not PEP 249-route
+# twice when an inner wrapped method already did.
+_ROUTED_ATTR = "_sf_errorhandler_routed"
+_SIMPLIFIED_ERROR_HANDLING_ATTR = "_simplified_error_handling"
+
+
+def simplified_error_handling(func: F) -> F:
+    """Route failures without the mixin ContextVar round-trip on the success path.
+
+    Skips ``ErrorHandlerMixin`` auto-wrapping and installs a cheap ``try/except``
+    that calls ``_reraise_via_errorhandler`` (PEP 249 routing + ``wrapper_error`` telemetry).
+    """
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_wrapper(self: ErrorHandlerMixin, *args: Any, **kwargs: Any) -> Any:
+            try:
+                return await func(self, *args, **kwargs)
+            except Exception as exc:
+                await self._reraise_via_errorhandler_async(func, exc)
+
+        wrapper: Callable[..., Any] = async_wrapper
+    else:
+
+        @functools.wraps(func)
+        def sync_wrapper(self: ErrorHandlerMixin, *args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(self, *args, **kwargs)
+            except Exception as exc:
+                self._reraise_via_errorhandler(func, exc)
+
+        wrapper = sync_wrapper
+
+    setattr(wrapper, _SIMPLIFIED_ERROR_HANDLING_ATTR, True)
+    return cast(F, wrapper)
+
+
+def _mark_errorhandler_routed(exc: BaseException) -> None:
+    setattr(exc, _ROUTED_ATTR, True)
+
+
+def route_exception(
+    connection: Connection | AsyncConnection | None,
+    cursor: SnowflakeCursorBase | AsyncSnowflakeCursorBase | None,
+    exc: Error,
+) -> NoReturn:
+    """Route an ``Error`` through the PEP 249 errorhandler chain, then re-raise.
+
+    The handler may observe, log, or replace the error (by raising a different
+    exception), but it cannot suppress it — the original is always re-raised.
+    """
+    _mark_errorhandler_routed(exc)
+    error_value = _error_to_value(exc)
+    Error.hand_to_other_handler(connection, cursor, type(exc), error_value)
+    raise exc
+
+
+class ErrorHandlerMixin:
+    """Mixin that routes ``Error`` exceptions from public methods through PEP 249 errorhandler.
+
+    Inherit this class and override ``_errorhandler_connection`` and/or
+    ``_errorhandler_cursor`` to supply context.  Public methods are wrapped
+    automatically at class creation time via ``__init_subclass__``.
+    """
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        _apply_errorhandler(cls)
+
+    @property
+    def _errorhandler_connection(self) -> Connection | AsyncConnection | None:
+        return None
+
+    @property
+    def _errorhandler_cursor(self) -> SnowflakeCursorBase | AsyncSnowflakeCursorBase | None:
+        return None
+
+    def _reraise_via_errorhandler(self, method: Callable[..., Any], exc: BaseException) -> NoReturn:
+        """Report ``wrapper_error`` telemetry and PEP 249-route *exc* unless already routed.
+
+        Used by ``@simplified_error_handling`` instead of paying a ContextVar
+        round-trip on every successful call.
+        """
+        _report_wrapper_error(self, method, exc)
+        if isinstance(exc, Error) and not _errorhandler_active.get() and not getattr(exc, _ROUTED_ATTR, False):
+            route_exception(self._errorhandler_connection, self._errorhandler_cursor, exc)
+        raise exc
+
+    async def _reraise_via_errorhandler_async(self, method: Callable[..., Any], exc: BaseException) -> NoReturn:
+        """Async counterpart of :meth:`_reraise_via_errorhandler`."""
+        await _report_wrapper_error_async(self, method, exc)
+        if isinstance(exc, Error) and not _errorhandler_active.get() and not getattr(exc, _ROUTED_ATTR, False):
+            route_exception(self._errorhandler_connection, self._errorhandler_cursor, exc)
+        raise exc
+
+
+def _apply_errorhandler(cls: type) -> None:
+    """Wrap public methods of *cls* with error-handler routing."""
+    for name in list(vars(cls)):
+        # private/dunder — not part of the public API surface
+        if name.startswith("_"):
+            continue
+        attr = vars(cls)[name]
+        if getattr(attr, _SIMPLIFIED_ERROR_HANDLING_ATTR, False):
+            continue
+        # descriptors — not regular instance methods
+        if isinstance(attr, (property, classmethod, staticmethod)):
+            continue
+        # class-level constants or non-callable attributes
+        if not callable(attr):
+            continue
+        # generators/async generators yield lazily; errors surface at iteration
+        # time, not call time — the inner calls they drive are wrapped individually.
+        if inspect.isgeneratorfunction(attr) or inspect.isasyncgenfunction(attr):
+            continue
+        if inspect.iscoroutinefunction(attr):
+            setattr(cls, name, _wrap_async_method(attr))
+        else:
+            setattr(cls, name, _wrap_method(attr))
+
+
+# Prevents double-routing when a wrapped public method calls another.
+# Global (not per-object):
+# if conn A's method somehow triggers conn B's method in the same context, conn B's errors won't be routed.
+# This is acceptable because a connection method should never call into another connection
+# and per-object tracking would add overhead on every call for a scenario that should not occur.
+_errorhandler_active: ContextVar[bool] = ContextVar("_errorhandler_active", default=False)
+
+
+def _report_wrapper_error(self: Any, method: Callable[..., Any], exc: BaseException) -> None:
+    """Send ``wrapper_error`` telemetry for *exc*."""
+    try:
+        # circular-import: telemetry.py imports errorhandler helpers; defer this import
+        # to call time so the module-level import graph doesn't cycle.
+        from .._common.telemetry import AsyncTelemetryClient
+
+        error_source = f"{type(self).__name__}.{method.__name__}"
+        client = _telemetry_client_if_enabled(self)
+        if client is None:
+            return
+        if isinstance(client, AsyncTelemetryClient):
+            # A sync method on an async-flavored class (e.g. a non-coroutine method on
+            # AsyncConnection/AsyncCursorBase) still carries an AsyncTelemetryClient.
+            _schedule_async_telemetry(client.send_wrapper_error(type(exc).__name__, error_source))
+        else:
+            client.send_wrapper_error(type(exc).__name__, error_source)
+    except Exception:
+        logger.debug("Failed to send wrapper_error telemetry")
+
+
+async def _report_wrapper_error_async(self: Any, method: Callable[..., Any], exc: BaseException) -> None:
+    """Async counterpart of :func:`_report_wrapper_error`."""
+    try:
+        # circular-import: telemetry.py imports errorhandler helpers; defer this import
+        # to call time so the module-level import graph doesn't cycle.
+        from .._common.telemetry import AsyncTelemetryClient
+
+        error_source = f"{type(self).__name__}.{method.__name__}"
+        client = _telemetry_client_if_enabled(self)
+        if client is None:
+            return
+        if isinstance(client, AsyncTelemetryClient):
+            await client.send_wrapper_error(type(exc).__name__, error_source)
+        else:
+            client.send_wrapper_error(type(exc).__name__, error_source)
+    except Exception:
+        logger.debug("Failed to send wrapper_error telemetry")
+
+
+def _wrap_method(method: Callable) -> Callable:
+    """Wrap a method to report ``wrapper_error`` telemetry and route ``Error`` through the errorhandler chain."""
+
+    @functools.wraps(method)
+    def wrapper(self: ErrorHandlerMixin, *args: Any, **kwargs: Any) -> Any:
+        nested = _errorhandler_active.get()
+        if not nested:
+            token = _errorhandler_active.set(True)
+        try:
+            return method(self, *args, **kwargs)
+        except Exception as exc:
+            _report_wrapper_error(self, method, exc)
+            if not nested and isinstance(exc, Error):
+                route_exception(
+                    self._errorhandler_connection,
+                    self._errorhandler_cursor,
+                    exc,
+                )
+            raise
+        finally:
+            if not nested:
+                _errorhandler_active.reset(token)
+
+    return wrapper
+
+
+def _wrap_async_method(method: Callable) -> Callable:
+    """Async counterpart of :func:`_wrap_method`."""
+
+    @functools.wraps(method)
+    async def wrapper(self: ErrorHandlerMixin, *args: Any, **kwargs: Any) -> Any:
+        nested = _errorhandler_active.get()
+        if not nested:
+            token = _errorhandler_active.set(True)
+        try:
+            return await method(self, *args, **kwargs)
+        except Exception as exc:
+            await _report_wrapper_error_async(self, method, exc)
+            if not nested and isinstance(exc, Error):
+                route_exception(
+                    self._errorhandler_connection,
+                    self._errorhandler_cursor,
+                    exc,
+                )
+            raise
+        finally:
+            if not nested:
+                _errorhandler_active.reset(token)
+
+    return wrapper
+
+
+def _error_to_value(exc: Error) -> ErrorDetails:
+    """Deconstruct an ``Error`` into the dict expected by ``hand_to_other_handler``."""
+    return {
+        "msg": exc.raw_msg,
+        "errno": exc.errno,
+        "sqlstate": exc.sqlstate,
+        "sfqid": exc.sfqid,
+        "query": exc.query,
+        "request_id": exc.request_id,
+        "parameter": exc.parameter,
+        "validation_code": exc.validation_code,
+    }

snowflake/connector/_internal/fips.py

@@ -0,0 +1,28 @@
+"""FIPS status for this process.
+
+``snowflake.connector`` re-exports :class:`FipsStatus` and :func:`get_fips_status`.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from .api_client.client_api import core_driver
+from .decorators import pep249
+
+
+class FipsStatus(NamedTuple):
+    """Whether this process is the FIPS driver.
+
+    ``is_fips`` is true when this binary was built with ``fips`` and its linked
+    TLS provider is in FIPS mode. A standard build returns false.
+    """
+
+    is_fips: bool
+
+
+@pep249
+def get_fips_status() -> FipsStatus:
+    """Report whether this process is the FIPS driver without opening a connection."""
+    response = core_driver.driver_get_fips_status()
+    return FipsStatus(is_fips=response.is_fips)

snowflake/connector/_internal/logging/__init__.py

@@ -0,0 +1,52 @@
+"""Logging for the snowflake.connector module.
+
+This package owns **configuration** of the ``snowflake.connector`` and
+``snowflake.connector._core`` stdlib loggers (``setup_logging`` and the internal
+``_get_*_stdlib_logger`` accessors), including the ``sf_core`` FFI callback
+logger, plus the public :func:`get_logger` entry point that wrapper code uses.
+
+Round-trip logging (:class:`.core_logger.CoreLogger`, which sends wrapper logs
+to sf_core over a direct FFI call and receives them back through the FFI
+callback) lives in :mod:`.core_logger` so its FFI import stays off this
+module's load path. See ``docs/logging/logging-architecture.md``.
+"""
+
+from __future__ import annotations
+
+import functools
+
+from typing import TYPE_CHECKING
+
+from .config import (
+    CONNECTOR_LOGGER_NAME,
+    SF_CORE_LOGGER_NAME,
+    _get_connector_stdlib_logger,
+    _get_sf_core_stdlib_logger,
+    _needs_handler,
+    setup_logging,
+)
+from .native_extension_logger import NativeExtensionLogger, get_native_extension_logger
+
+
+if TYPE_CHECKING:
+    from .core_logger import CoreLogger
+
+
+@functools.cache
+def get_logger(name: str) -> CoreLogger:
+    from .core_logger import CoreLogger
+
+    return CoreLogger(name)
+
+
+__all__ = [
+    "CONNECTOR_LOGGER_NAME",
+    "SF_CORE_LOGGER_NAME",
+    "NativeExtensionLogger",
+    "_get_connector_stdlib_logger",
+    "_get_sf_core_stdlib_logger",
+    "_needs_handler",
+    "get_logger",
+    "get_native_extension_logger",
+    "setup_logging",
+]

snowflake/connector/_internal/logging/config.py

@@ -0,0 +1,134 @@
+"""Logging configuration for snowflake.connector."""
+
+from __future__ import annotations
+
+import logging
+
+
+# Logger names
+CONNECTOR_LOGGER_NAME = "snowflake.connector"
+SF_CORE_LOGGER_NAME = "snowflake.connector._core"
+
+# Set up loggers once at module load with NullHandler (standard library practice
+# per https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library).
+# Propagation is left ON so that external log capture (e.g. pytest caplog, root-level
+# handlers configured by the application) works out of the box -- matching
+# the behavior of snowflake-connector-python.
+# When setup_logging() is called explicitly, propagation is turned OFF on the
+# loggers that receive a dedicated handler to prevent duplicate output.
+_sf_core_logger = logging.getLogger(SF_CORE_LOGGER_NAME)
+_sf_core_logger.addHandler(logging.NullHandler())
+
+_connector_logger = logging.getLogger(CONNECTOR_LOGGER_NAME)
+_connector_logger.addHandler(logging.NullHandler())
+
+
+def _needs_handler(logger: logging.Logger) -> bool:
+    """Return True if the logger has no handlers or only NullHandler(s)."""
+    if not logger.handlers:
+        return True
+    return all(isinstance(h, logging.NullHandler) for h in logger.handlers)
+
+
+def setup_logging(
+    level: int = logging.INFO,
+    sf_core_level: int = logging.INFO,
+    format_string: str | None = None,
+    stream: object | None = None,
+) -> None:
+    """Configure basic logging for the snowflake.connector module.
+
+    Propagation behaviour
+    ---------------------
+    By default (before this function is called) both loggers have
+    ``propagate=True``.  This means log records bubble up to the root
+    logger so that application-level handlers and test frameworks such as
+    ``pytest caplog`` capture connector output without any extra
+    configuration.
+
+    When this function adds a dedicated StreamHandler to a logger it also
+    sets ``propagate=False`` on that logger to prevent every message from
+    appearing twice — once via the dedicated handler and once via the root
+    handler chain.
+
+    **The propagate flag is only changed when a handler is actually added.**
+    If the logger already has a non-NullHandler (meaning the caller has
+    configured it themselves), this function leaves ``propagate`` and the
+    existing handler untouched and only updates the logger's *level*.
+    This respects application-level logging configuration while still
+    honouring the requested verbosity.
+
+    Summary:
+      * No prior handler → adds StreamHandler, sets propagate=False.
+      * Prior non-Null handler exists → updates level only, propagate unchanged.
+      * Called multiple times with no prior handler → second call is a no-op
+        for handler/propagation (handler already present from the first call).
+
+    Args:
+        level: Logging level for the snowflake.connector logger.
+               Defaults to logging.INFO.
+        sf_core_level: Logging level for the sf_core logger.
+                       Defaults to logging.INFO.
+        format_string: Custom format string for log messages.
+                       If None, uses a default format.
+        stream: Stream to write logs to. If None, uses sys.stderr.
+
+    Example:
+        >>> from snowflake.connector._internal.logging import setup_logging
+        >>> import logging
+        >>> setup_logging(level=logging.DEBUG, sf_core_level=logging.DEBUG)
+    """
+    if format_string is None:
+        format_string = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+    formatter = logging.Formatter(format_string)
+    handler = logging.StreamHandler(stream)  # type: ignore [arg-type]
+    handler.setFormatter(formatter)
+
+    _connector_logger.setLevel(level)
+    if _needs_handler(_connector_logger):
+        _connector_logger.addHandler(handler)
+        _connector_logger.propagate = False
+
+    _sf_core_logger.setLevel(sf_core_level)
+    if _needs_handler(_sf_core_logger):
+        _sf_core_logger.addHandler(handler)
+        _sf_core_logger.propagate = False
+
+
+def _get_connector_stdlib_logger() -> logging.Logger:
+    """Return the package stdlib logger used by logging infrastructure.
+
+    Internal — not for wrapper contributor use.  Call :func:`logging.get_logger`
+    to obtain a :class:`~.core_logger.CoreLogger` for module logging.
+    """
+    return _connector_logger
+
+
+def _get_sf_core_stdlib_logger() -> logging.Logger:
+    """Return the stdlib logger that receives core-originated FFI callback events.
+
+    Internal — used by :mod:`~.api_client` callback dispatch only.
+    Wrapper code should use :func:`logging.get_logger` instead.
+    """
+    return _sf_core_logger
+
+
+class LoggingConfiguration:
+    """Process-wide logging knobs — currently just troubleshooting mode."""
+
+    _instance: LoggingConfiguration | None = None
+
+    def __init__(self, *, troubleshooting_enabled: bool) -> None:
+        self._troubleshooting_enabled = troubleshooting_enabled
+
+    @classmethod
+    def initialize(cls, *, troubleshooting_enabled: bool) -> LoggingConfiguration:
+        """Create the process-wide instance. Call once after ``sf_core_python.init``."""
+        if cls._instance is None:
+            cls._instance = cls(troubleshooting_enabled=troubleshooting_enabled)
+        return cls._instance
+
+    def is_troubleshooting_enabled(self) -> bool:
+        """Return whether wrapper logs should bypass the ``CoreLogger`` pre-filter."""
+        return self._troubleshooting_enabled