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

snowflake/connector/_internal/logging/core_logger.py

@@ -0,0 +1,218 @@
+"""Round-trip logging: Python -> core -> Python.
+
+:class:`CoreLogger` is a drop-in replacement for a module ``logging.Logger``.
+Wrapper logs are sent to sf_core over a direct PyO3 call so every tracing layer
+(file, OTLP, Snowflake in-band telemetry) sees them, then come back through the
+log callback onto the originating module logger. See
+``docs/logging/logging-architecture.md``.
+
+This lives in its own module (rather than in :mod:`config`) so the extension
+binding ``sf_core_python.log_event`` can be imported at module top level.
+``logging.config`` is imported at package load, before ``api_client`` — which
+itself imports ``logging`` — is ready; keeping ``CoreLogger`` here avoids that
+import cycle. :func:`logging.get_logger` imports this module lazily, once the
+package is up.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import traceback
+
+from typing import TYPE_CHECKING
+
+from snowflake.connector._core import sf_core_python
+
+from .config import LoggingConfiguration
+
+
+if TYPE_CHECKING:
+    from typing import Any
+
+# sf_core_python.log_event return codes (see python_bridge ``log_event``).
+_CORE_DELIVERED = 0  # event accepted by the tracing pipeline
+
+
+def _py_level_to_callback(level: int) -> int:
+    """Map a stdlib logging level to the sf_core callback level encoding."""
+    if level >= logging.ERROR:
+        return 0
+    if level >= logging.WARNING:
+        return 1
+    if level >= logging.INFO:
+        return 2
+    return 3  # DEBUG - finest level supported
+
+
+class CoreLogger:
+    """Drop-in replacement for a module ``logging.Logger`` that routes records
+    through sf_core.
+
+    The wrapped stdlib logger remains the single source of truth for levels:
+    :meth:`is_enabled_for` gates every core call, so a filtered message costs
+    nothing.  When troubleshooting mode is active the pre-filter is bypassed
+    and all events reach the core pipeline regardless of the stdlib level.
+    """
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+        self._py_logger = logging.getLogger(name)
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def is_enabled_for(self, level: int) -> bool:
+        return self._is_level_enabled(level)
+
+    def _is_level_enabled(self, py_level: int) -> bool:
+        cfg = LoggingConfiguration._instance
+        return (cfg is not None and cfg.is_troubleshooting_enabled()) or self._py_logger.isEnabledFor(py_level)
+
+    def _format_message(self, msg: str, args: tuple[object, ...], exc_info: Any) -> str:
+        try:
+            formatted = msg % args if args else msg
+        except Exception:
+            # A mismatched format string / args is a caller bug; logging must
+            # never raise into user code (same contract as the stdlib logger we
+            # replace, which swallows format errors in ``record.getMessage``).
+            # Still emit something useful rather than dropping the record.
+            formatted = f"{msg} {args!r}"
+        if exc_info:
+            if exc_info is True:
+                exc_info = sys.exc_info()
+            if isinstance(exc_info, BaseException):
+                exc_info = (type(exc_info), exc_info, exc_info.__traceback__)
+            if exc_info and exc_info[0] is not None:
+                formatted += "".join(traceback.format_exception(*exc_info))
+        return formatted
+
+    def _emit(
+        self,
+        py_level: int,
+        msg: str,
+        args: tuple[object, ...],
+        *,
+        exc_info: Any = False,
+        stacklevel: int = 1,
+    ) -> None:
+        """Emit a Python-originated log, resolving the caller's location.
+
+        Used by the public ``debug``/``info``/… methods, where the call site is
+        a Python stack frame.
+        """
+        if not self._is_level_enabled(py_level):
+            return
+        # frame 0 is _emit, frame 1 is the public CoreLogger method (info/log/...)
+        # stacklevel counts frames above that method
+        frame = sys._getframe(1 + stacklevel)
+        self._dispatch(
+            py_level,
+            self._format_message(msg, args, exc_info),
+            frame.f_code.co_filename,
+            frame.f_lineno,
+            frame.f_code.co_name,
+        )
+
+    def _emit_with_location(
+        self,
+        py_level: int,
+        msg: str,
+        args: tuple[object, ...],
+        *,
+        exc_info: Any = False,
+        file: str,
+        line: int,
+        function: str,
+    ) -> None:
+        """Emit a log with a caller-supplied source location.
+
+        Used by native extensions, which pass explicit C++ file/function/line
+        instead of a resolvable Python stack frame.
+        """
+        if not self._is_level_enabled(py_level):
+            return
+        self._dispatch(py_level, self._format_message(msg, args, exc_info), file, line, function)
+
+    def _dispatch(
+        self,
+        py_level: int,
+        message: str,
+        source_file: str,
+        source_line: int,
+        source_function: str,
+    ) -> None:
+        """Send a fully-resolved record to sf_core, falling back to the stdlib
+        logger when the pipeline is not live.
+        """
+        try:
+            status = sf_core_python.log_event(
+                level=_py_level_to_callback(py_level),
+                message=message,
+                file=source_file,
+                line=source_line,
+                function=source_function,
+                logger_name=self._name,
+            )
+        except Exception:
+            # Extension unusable (e.g. torn down during interpreter shutdown). Logging
+            # must never raise into user code (same contract as
+            # ``logging.Handler.handle`` and :func:`logging.safe_log`); treat as
+            # not delivered and fall back below.
+            status = None
+
+        if status == _CORE_DELIVERED:
+            return
+
+        # sf_core is not up yet (early-import events, before ``sf_core_python.init``
+        # marks the pipeline live) or the extension is gone: emit straight onto
+        # the stdlib logger so the record is not lost. The extension return
+        # code — not a Python-side flag — is the source of truth for whether
+        # it is live.
+        record = self._py_logger.makeRecord(
+            self._name,
+            py_level,
+            source_file,
+            source_line,
+            message,
+            (),
+            None,
+            source_function,
+        )
+        self._py_logger.handle(record)
+
+    def debug(self, msg: str, *args: object, exc_info: Any = False) -> None:
+        self._emit(logging.DEBUG, msg, args, exc_info=exc_info)
+
+    def info(self, msg: str, *args: object, exc_info: Any = False) -> None:
+        self._emit(logging.INFO, msg, args, exc_info=exc_info)
+
+    def warning(self, msg: str, *args: object, exc_info: Any = False) -> None:
+        self._emit(logging.WARNING, msg, args, exc_info=exc_info)
+
+    def error(self, msg: str, *args: object, exc_info: Any = False) -> None:
+        self._emit(logging.ERROR, msg, args, exc_info=exc_info)
+
+    def exception(self, msg: str, *args: object) -> None:
+        self._emit(logging.ERROR, msg, args, exc_info=True)
+
+    def log(self, level: int, msg: str, *args: object, exc_info: Any = False, stacklevel: int = 1) -> None:
+        self._emit(level, msg, args, exc_info=exc_info, stacklevel=stacklevel)
+
+    def safe_log(self, level: int, msg: str, *args: object, exc_info: bool = False) -> None:
+        """Best-effort log call — never raises.
+
+        Use on cleanup paths that run during interpreter shutdown (``atexit``,
+        ``__del__``) where the ``logging`` module itself may be partially torn
+        down and the sf_core extension may already be gone. Bypasses the round-trip
+        and logs straight onto the stdlib logger. ``stacklevel=2`` points the
+        record at the caller, not at this method.
+
+        For all other call sites prefer the standard ``logger.<level>(...)``
+        methods so genuine logging misconfiguration is not silently hidden.
+        """
+        try:
+            self._py_logger.log(level, msg, *args, exc_info=exc_info, stacklevel=2)
+        except Exception:
+            pass

snowflake/connector/_internal/logging/native_extension_logger.py

@@ -0,0 +1,144 @@
+"""Logger wrapper used by bundled native extensions (nanoarrow C++).
+
+The extension imports this module via pybind (see
+``_internal/nanoarrow_cpp/Logging/logging.cpp``) and calls
+``NativeExtensionLogger.log()`` so it can pass C++-side file / function / line
+information through :class:`.core_logger.CoreLogger`, which routes every log
+through sf_core.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+
+from typing import Any
+
+from .core_logger import CoreLogger
+
+
+def get_native_extension_logger(name: str) -> NativeExtensionLogger:
+    return NativeExtensionLogger(CoreLogger(name))
+
+
+class NativeExtensionLogger:
+    """Thin wrapper around :class:`.core_logger.CoreLogger` for native code.
+
+    Native extensions pass explicit file, function, and line metadata from C++
+    rather than relying on Python stack frames.
+    """
+
+    def __init__(self, core_logger: CoreLogger) -> None:
+        self._logger = core_logger
+
+    def debug(
+        self,
+        msg: str,
+        path_name: str | None = None,
+        func_name: str | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        self.log(logging.DEBUG, msg, *args, path_name=path_name, func_name=func_name, **kwargs)
+
+    def info(
+        self,
+        msg: str,
+        path_name: str | None = None,
+        func_name: str | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        self.log(logging.INFO, msg, *args, path_name=path_name, func_name=func_name, **kwargs)
+
+    def warning(
+        self,
+        msg: str,
+        path_name: str | None = None,
+        func_name: str | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        self.log(logging.WARNING, msg, *args, path_name=path_name, func_name=func_name, **kwargs)
+
+    def warn(
+        self,
+        msg: str,
+        path_name: str | None = None,
+        func_name: str | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        warnings.warn(
+            "The 'warn' method is deprecated, use 'warning' instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.warning(msg, *args, path_name=path_name, func_name=func_name, **kwargs)  # type: ignore[misc]
+
+    def error(
+        self,
+        msg: str,
+        path_name: str | None = None,
+        func_name: str | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        self.log(logging.ERROR, msg, *args, path_name=path_name, func_name=func_name, **kwargs)
+
+    def exception(
+        self,
+        msg: str,
+        path_name: str | None = None,
+        func_name: str | None = None,
+        *args: Any,
+        exc_info: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        self.error(msg, *args, path_name=path_name, func_name=func_name, exc_info=exc_info, **kwargs)  # type: ignore[misc]
+
+    def critical(
+        self,
+        msg: str,
+        path_name: str | None = None,
+        func_name: str | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        self.log(logging.CRITICAL, msg, *args, path_name=path_name, func_name=func_name, **kwargs)
+
+    fatal = critical
+
+    def log(
+        self,
+        level: int,
+        msg: str,
+        *args: Any,
+        path_name: str | None = None,
+        func_name: str | None = None,
+        line_num: int = 0,
+        **kwargs: Any,
+    ) -> None:
+        """Generalized log method for native extension callers.
+
+        Args:
+            level: Logging level.
+            msg: Logging message.
+            path_name: Absolute or relative path of the file where the logger gets called.
+            func_name: Function inside which the logger gets called.
+            line_num: Line number at which the logger gets called.
+        """
+        if not isinstance(level, int):
+            if logging.raiseExceptions:  # type: ignore[unreachable]
+                raise TypeError("level must be an integer")
+            return
+        exc_info = kwargs.pop("exc_info", False)
+        self._logger._emit_with_location(
+            level,
+            msg,
+            args,
+            exc_info=exc_info,
+            file=path_name or "",
+            line=line_num,
+            function=func_name or "",
+        )

snowflake/connector/_internal/logout_config_mapping.py

@@ -0,0 +1,187 @@
+"""Logout configuration for the Python wrapper (SNOW-2314152).
+
+LogoutConfig carries resolved logout settings with Python-specific defaults.
+remap_keep_alive_for_backward_compat applies the Phase 2 (SNOW-2314152) backward-compat remap.
+"""
+
+import warnings
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+class LogoutOptionKeys(StrEnum):
+    """Core API option key strings for logout configuration.
+
+    These correspond to the option keys accepted by Core's
+    connection_set_option_* RPCs for logout behavior.
+    """
+
+    SERVER_SESSION_KEEP_ALIVE = "server_session_keep_alive"
+    ENABLE_SERVER_SESSION_KEEP_ALIVE_AUTO_DETECTION = "enable_server_session_keep_alive_auto_detection"
+    LOGOUT_ERROR_STRATEGY = "logout_error_strategy"
+    LOGOUT_TOTAL_TIMEOUT_SECONDS = "logout_total_timeout_seconds"
+    LOGOUT_MAX_ATTEMPTS = "logout_max_attempts"
+    LOGOUT_REQUEST_TIMEOUT_SECONDS = "logout_request_timeout_seconds"
+
+
+class ErrorStrategy(StrEnum):
+    """Error handling strategy for logout.
+
+    These map directly to Core's ErrorStrategy enum variants.
+    """
+
+    BEST_EFFORT = "best_effort"
+    STRICT = "strict"
+
+
+_UNSET = object()  # Sentinel to distinguish "not provided" from explicit values
+
+
+@dataclass
+class LogoutConfig:
+    """Final logout configuration for Core API.
+
+    Attributes:
+        server_session_keep_alive: Final value for Core (already mapped)
+        enable_server_session_keep_alive_auto_detection: Final value for Core (None = treat as False in Core)
+        error_strategy: Error handling strategy string ("best_effort" or "strict")
+        logout_total_timeout_seconds: Total timeout budget for logout operation (all retries)
+        max_attempts: Maximum total attempts (NOT retry count: 1 = no retries, 3 = 2 retries)
+        logout_request_timeout_seconds: Per-request socket timeout (None = no per-request limit)
+    """
+
+    server_session_keep_alive: bool | None
+    enable_server_session_keep_alive_auto_detection: bool | None
+    error_strategy: ErrorStrategy = ErrorStrategy.BEST_EFFORT
+    logout_total_timeout_seconds: int | None = None  # Core default: 15s
+    max_attempts: int | None = None  # Core default: 3
+    logout_request_timeout_seconds: int | None = None  # Core default: None (total budget only)
+
+    @classmethod
+    def from_kwargs(cls, kwargs: dict) -> "LogoutConfig":
+        """Pop logout params from kwargs, apply defaults and backward-compat mapping.
+
+        Mutates kwargs in-place (pops logout-specific keys).
+        """
+        from snowflake.connector.errors import ProgrammingError
+
+        keep_alive = kwargs.pop("server_session_keep_alive", None)
+        if keep_alive is not None and not isinstance(keep_alive, bool):
+            raise ProgrammingError(f"server_session_keep_alive must be bool, got {type(keep_alive).__name__}")
+
+        auto_detection = _extract_auto_detection_param(kwargs)
+        keep_alive = remap_keep_alive_for_backward_compat(keep_alive, auto_detection)
+
+        return cls(
+            server_session_keep_alive=keep_alive,
+            enable_server_session_keep_alive_auto_detection=auto_detection,
+        )
+
+    def to_option_dict(self) -> dict[str, "bool | int | str"]:
+        """Convert to a dict suitable for ``_build_config_settings`` + ``connection_set_options``.
+
+        ``None`` fields are omitted so Core uses its own defaults for those keys.
+        """
+        options: dict[str, bool | int | str] = {}
+        if self.server_session_keep_alive is not None:
+            options[LogoutOptionKeys.SERVER_SESSION_KEEP_ALIVE] = self.server_session_keep_alive
+        if self.enable_server_session_keep_alive_auto_detection is not None:
+            options[LogoutOptionKeys.ENABLE_SERVER_SESSION_KEEP_ALIVE_AUTO_DETECTION] = (
+                self.enable_server_session_keep_alive_auto_detection
+            )
+        options[LogoutOptionKeys.LOGOUT_ERROR_STRATEGY] = self.error_strategy.value
+        if self.logout_total_timeout_seconds is not None:
+            options[LogoutOptionKeys.LOGOUT_TOTAL_TIMEOUT_SECONDS] = self.logout_total_timeout_seconds
+        if self.max_attempts is not None:
+            options[LogoutOptionKeys.LOGOUT_MAX_ATTEMPTS] = self.max_attempts
+        if self.logout_request_timeout_seconds is not None:
+            options[LogoutOptionKeys.LOGOUT_REQUEST_TIMEOUT_SECONDS] = self.logout_request_timeout_seconds
+        return options
+
+
+def _extract_auto_detection_param(kwargs: dict) -> bool | None:
+    """Pop and parse enable_server_session_keep_alive_auto_detection from kwargs.
+
+    If not provided, defaults to True and emits a FutureWarning:
+    the default will change to None in a future version (SNOW-2314152).
+    """
+    from snowflake.connector.errors import ProgrammingError
+
+    raw = kwargs.pop("enable_server_session_keep_alive_auto_detection", _UNSET)
+    if raw is _UNSET:
+        warnings.warn(
+            "enable_server_session_keep_alive_auto_detection was not set and defaults "
+            "to True. In a future version, the default will change to None. "
+            "Please provide an explicit value: "
+            "True = check for running async queries before logout (queries are preserved); "
+            "False/None = always send logout on close (async queries may be terminated by server). "
+            "Logout behavior can also be overridden with server_session_keep_alive. "
+            "See the connection parameter docs for more info.",
+            FutureWarning,
+            stacklevel=6,
+        )
+        return True
+    if raw is not None and not isinstance(raw, bool):
+        raise ProgrammingError(
+            f"enable_server_session_keep_alive_auto_detection must be bool or None, got {type(raw).__name__}"
+        )
+    return raw
+
+
+def remap_keep_alive_for_backward_compat(
+    server_session_keep_alive: bool | None,
+    enable_auto_detection: bool | None,
+) -> bool | None:
+    """Phase 2 backward-compat remap for server_session_keep_alive (SNOW-2314152).
+
+    Old Python driver: server_session_keep_alive=False (default) always checked
+    _async_sfqids before logout. Phase 2 (SNOW-2314152) preserves this: False + True → None makes
+    Core check the registry (same behavior). Phase 3 (SNOW-2314152): False will mean "force logout".
+
+    Truth table:
+    - False + auto_detection=True  → None (Core checks registry) + deprecation warning
+    - False + auto_detection=False → False (no remap, no warning — same meaning in Phase 3 (SNOW-2314152))
+    - True / None                  → pass through unchanged
+    """
+    if server_session_keep_alive is False and enable_auto_detection:
+        warnings.warn(
+            "server_session_keep_alive=False currently respects auto-detection "
+            "(async query registry is checked before logout). In a future version, "
+            "False will mean 'always logout' without registry check. "
+            "To keep current behavior, use server_session_keep_alive=None with "
+            "enable_server_session_keep_alive_auto_detection=True.",
+            FutureWarning,
+            stacklevel=5,
+        )
+        return None
+    return server_session_keep_alive
+
+
+def logout_config_options_modifier(options: dict[str, Any]) -> dict[str, Any]:
+    """``ConnectionConfig.to_options`` modifier that re-applies legacy LogoutConfig logic.
+
+    The generated :class:`ConnectionConfig` exposes the logout-related fields as
+    plain optional values, so a user-supplied ``server_session_keep_alive=False``
+    would be forwarded verbatim to the Rust core and the Python-only
+    ``best_effort`` / auto-detection defaults would be lost.
+
+    This modifier reconstructs the previous ``Connection._parse_kwargs`` behaviour:
+
+    * Pops ``server_session_keep_alive`` and
+      ``enable_server_session_keep_alive_auto_detection`` from *options*.
+    * Builds a :class:`LogoutConfig`, which:
+        - Defaults ``enable_server_session_keep_alive_auto_detection`` to ``True``
+          (with a ``FutureWarning``) when the user did not provide a value.
+        - Applies the Phase 2 ``False + True → None`` remap for
+          ``server_session_keep_alive`` (with a ``FutureWarning``).
+        - Defaults ``error_strategy`` to ``ErrorStrategy.BEST_EFFORT``.
+    * Merges the resolved values back into *options*.
+
+    Designed to be passed as one of ``options_modifiers`` to
+    :meth:`ConnectionConfig.to_options` / :meth:`ConnectionConfig.to_proto_options`.
+    """
+    config = LogoutConfig.from_kwargs(options)
+    options.update(config.to_option_dict())
+    return options

snowflake/connector/_internal/nanoarrow_cpp/ArrowIterator/ArrayConverter.cpp

@@ -0,0 +1,57 @@
+#include "ArrayConverter.hpp"
+
+#include <memory>
+
+#include "CArrowIterator.hpp"
+#include "ConverterUtil.hpp"
+#include "SnowflakeType.hpp"
+
+namespace sf {
+Logger* ArrayConverter::logger = new Logger("snowflake.connector.ArrayConverter");
+
+void ArrayConverter::generateError(const std::string& msg) const {
+  logger->error(__FILE__, __func__, __LINE__, msg.c_str());
+  PyErr_SetString(PyExc_Exception, msg.c_str());
+}
+
+ArrayConverter::ArrayConverter(ArrowSchemaView* schemaView, ArrowArrayView* array,
+                               PyObject* context, bool useNumpy) {
+  m_array = array;
+
+  if (schemaView->schema->n_children != 1) {
+    std::string errorInfo = Logger::formatString(
+        "[Snowflake Exception] invalid arrow schema for array items expected 1 "
+        "schema child, but got %d",
+        schemaView->schema->n_children);
+    this->generateError(errorInfo);
+    return;
+  }
+
+  ArrowSchema* item_schema = schemaView->schema->children[0];
+  ArrowArrayView* item_array = array->children[0];
+  m_item_converter = getConverterFromSchema(item_schema, item_array, context, useNumpy, logger);
+}
+
+PyObject* ArrayConverter::toPyObject(int64_t rowIndex) const {
+  if (ArrowArrayViewIsNull(m_array, rowIndex)) {
+    Py_RETURN_NONE;
+  }
+
+  // Array item offsets are stored in the second array buffers
+  // Infer start an end of this rows slice by looking at the
+  // current and next offset. If there isn't another offset use
+  // the end of the array instead.
+  int start = m_array->buffer_views[1].data.as_int32[rowIndex];
+  int end = m_array->children[0]->length;
+  if (rowIndex + 1 < m_array->length) {
+    end = m_array->buffer_views[1].data.as_int32[rowIndex + 1];
+  }
+
+  PyObject* list = PyList_New(end - start);
+  for (int i = start; i < end; i++) {
+    PyList_SetItem(list, i - start, m_item_converter->toPyObject(i));
+  }
+  return list;
+}
+
+}  // namespace sf

snowflake/connector/_internal/nanoarrow_cpp/ArrowIterator/ArrayConverter.hpp

@@ -0,0 +1,29 @@
+#ifndef PC_ARRAYCONVERTER_HPP
+#define PC_ARRAYCONVERTER_HPP
+
+#include <memory>
+
+#include "IColumnConverter.hpp"
+#include "logging.hpp"
+#include "nanoarrow.h"
+#include "nanoarrow.hpp"
+
+namespace sf {
+
+class ArrayConverter : public IColumnConverter {
+ public:
+  explicit ArrayConverter(ArrowSchemaView* schemaView, ArrowArrayView* array, PyObject* context,
+                          bool useNumpy);
+
+  PyObject* toPyObject(int64_t rowIndex) const override;
+
+ private:
+  void generateError(const std::string& msg) const;
+
+  ArrowArrayView* m_array;
+  std::shared_ptr<sf::IColumnConverter> m_item_converter;
+  static Logger* logger;
+};
+
+}  // namespace sf
+#endif  // PC_ARRAYCONVERTER_HPP