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

snowflake/connector/_internal/arrow_stream_utils.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, cast
+
+from snowflake.connector._core import sf_core_python
+from snowflake.connector.errors import InternalError
+
+from .._common.extras import pyarrow
+from .arrow_context import ArrowConverterContext
+from .arrow_stream_iterator import ArrowStreamIterator as CythonArrowStreamIterator
+from .arrow_stream_iterator import ArrowStreamTableIterator as CythonArrowStreamTableIterator
+from .type_codes import FIXED
+
+
+if TYPE_CHECKING:
+    from pyarrow import Schema, Table
+
+    from .arrow import ArrowRowIterator, ArrowTableIterator
+    from .cursor.result_metadata import ResultMetadata
+
+
+def _missing_native_class(name: str) -> InternalError:
+    return InternalError(
+        msg=f"sf_core_python.{name} is unavailable; rebuild with --features native-arrow / SF_NATIVE_ARROW=1",
+    )
+
+
+def release_arrow_stream(stream_ptr: int | None) -> None:
+    """Release an ArrowArrayStream pointer to prevent memory leaks.
+
+    Works by creating a throwaway ArrowStreamIterator whose C++ destructor
+    calls ``stream->release(stream)`` when it goes out of scope.  This is
+    indirect — the C++ from_stream() factory also reads the schema — but it
+    is the only release path currently exposed to Python.
+
+    If the stream is in a bad state (already released, corrupt), the
+    ArrowStreamIterator constructor will fail.  We catch that to avoid
+    propagating errors into callers that are doing best-effort cleanup
+    (e.g. from_prepare_result cleanup).
+    """
+    if not stream_ptr:
+        return
+    try:
+        _ = CythonArrowStreamIterator(stream_ptr, ArrowConverterContext())
+    except Exception:
+        pass
+
+
+def create_row_iterator(
+    stream_ptr: int,
+    *,
+    context: ArrowConverterContext,
+    use_dict_result: bool = False,
+    use_numpy: bool = False,
+    use_core_arrow: bool = False,
+) -> ArrowRowIterator:
+    """Build a sync row iterator that yields one row at a time.
+
+    When ``use_core_arrow`` is true and ``sf_core_python`` is built with the
+    ``native-arrow`` feature, returns the PyO3 ``ArrowStreamIterator`` directly.
+    Otherwise uses the Cython nanoarrow iterator.
+    """
+    if use_core_arrow and sf_core_python.native_arrow_enabled():
+        # Class is only exported when built with ``native-arrow``; stub_gen
+        # emits ``#[pyfunction]``s only, so do not attribute-access it on the stub.
+        iterator_cls = getattr(sf_core_python, "ArrowStreamIterator", None)
+        if iterator_cls is None:
+            release_arrow_stream(stream_ptr)
+            raise _missing_native_class("ArrowStreamIterator")
+        return cast(
+            "ArrowRowIterator",
+            iterator_cls(
+                stream_ptr,
+                session_timezone=context.timezone,
+                use_dict_result=use_dict_result,
+                use_numpy=use_numpy,
+            ),
+        )
+    return CythonArrowStreamIterator(
+        stream_ptr,
+        context,
+        use_dict_result=use_dict_result,
+        use_numpy=use_numpy,
+    )
+
+
+def create_table_iterator(
+    stream_ptr: int,
+    *,
+    context: ArrowConverterContext,
+    number_to_decimal: bool = False,
+    force_microsecond_precision: bool = False,
+    use_core_arrow: bool = False,
+) -> ArrowTableIterator:
+    """Build a table iterator that yields one RecordBatch at a time.
+
+    When ``use_core_arrow`` is true and ``sf_core_python`` is built with the
+    ``native-arrow`` feature, returns the PyO3 ``ArrowStreamTableIterator``.
+    Otherwise uses the Cython nanoarrow iterator.
+    """
+    if use_core_arrow and sf_core_python.native_arrow_enabled():
+        # Class is only exported when built with ``native-arrow``; stub_gen
+        # emits ``#[pyfunction]``s only, so do not attribute-access it on the stub.
+        iterator_cls = getattr(sf_core_python, "ArrowStreamTableIterator", None)
+        if iterator_cls is None:
+            release_arrow_stream(stream_ptr)
+            raise _missing_native_class("ArrowStreamTableIterator")
+        return cast(
+            "ArrowTableIterator",
+            iterator_cls(
+                stream_ptr,
+                session_timezone=context.timezone,
+                number_to_decimal=number_to_decimal,
+                force_microsecond_precision=force_microsecond_precision,
+            ),
+        )
+    return CythonArrowStreamTableIterator(
+        stream_ptr,
+        context,
+        number_to_decimal=number_to_decimal,
+        force_microsecond_precision=force_microsecond_precision,
+    )
+
+
+def normalize_fixed_column_types(
+    schema: Schema,
+    description: Sequence[ResultMetadata],
+) -> Schema:
+    """Rewrite FIXED columns in an Arrow schema to int64 for backward compatibility.
+
+    When the result set has zero rows, sf-core may choose a narrower integer
+    type (e.g. int8) for NUMBER columns.  The old driver always exposed int64,
+    so we normalize here to keep behavior consistent.
+    """
+    new_fields = []
+    changed = False
+    for field, metadata in zip(schema, description, strict=False):
+        if metadata.type_code == FIXED and field.type != pyarrow.int64():
+            new_fields.append(field.with_type(pyarrow.int64()))
+            changed = True
+        else:
+            new_fields.append(field)
+    return pyarrow.schema(new_fields) if changed else schema
+
+
+def collect_arrow_table(
+    table_iterator: ArrowTableIterator,
+    columns_metadata: Sequence[ResultMetadata] | None = None,
+    force_return_table: bool = False,
+) -> Table | None:
+    """Collect all RecordBatches from *table_iterator* into a single Arrow Table.
+
+    When *force_return_table* is ``True`` an empty result set produces a
+    properly-typed empty table.  When ``False`` (the default), an empty result
+    set returns ``None``.
+
+    When *columns_metadata* is provided the empty-table schema is normalized via
+    :func:`normalize_fixed_column_types` so that FIXED columns are int64.
+    """
+    batches = list(table_iterator)
+    if batches:
+        return pyarrow.Table.from_batches(batches)
+
+    if not force_return_table:
+        return None
+
+    schema = table_iterator.get_converted_schema()
+    if columns_metadata:
+        schema = normalize_fixed_column_types(schema, columns_metadata)
+    return schema.empty_table()

snowflake/connector/_internal/authenticator_type.py

@@ -0,0 +1,53 @@
+"""The ``AuthenticatorType`` enum: one member per authenticator the driver accepts.
+
+DEPRECATED. Retained only for backward compatibility with
+snowflake-connector-python, whose callers imported these values to pass to
+``authenticator=``. The Universal Driver itself never reads this enum — it only
+needs the raw string. New code should pass the string directly (e.g.
+``authenticator="OAUTH"``); this exists so existing code keeps working.
+
+MUST BE KEPT IN SYNC WITH THE RUST CORE. Every value below has to be a spelling
+the core's connection-config parser accepts, because callers read a value from
+here and hand it straight back as ``authenticator=`` — a value listed here but
+rejected by the core is a broken round trip. Nothing generates this file, so the
+guard is a test on the Rust side:
+``sf_core::config::connection_config``'s
+``recognises_every_authenticator_spelling_exposed_to_python``. It reads *this
+file* and runs the real parser over every value, so adding a member here that
+the core does not accept fails the Rust test suite. If you add one, add the
+matching arm in ``sf_core/src/config/connection_config.rs`` too.
+
+The reverse does not hold, deliberately: the core accepts spellings this enum
+does not list (``""`` and ``"SNOWFLAKE_PASSWORD"`` for password auth,
+``https://`` URLs for native Okta SSO). Only listing something the core rejects
+is a bug.
+
+Re-exported by :mod:`snowflake.connector.constants`. Unlike the flat
+``*_AUTHENTICATOR`` constants in :mod:`snowflake.connector.network`, this enum
+does not emit a deprecation warning on access: it's re-exported from two
+modules, and the shared warn-once machinery only lets a single defining module
+warn, so there's no clean way to fire exactly one warning across both re-export
+paths.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class AuthenticatorType(StrEnum):
+    """Authenticator types accepted by the Universal Driver's ``authenticator=`` connection parameter."""
+
+    DEFAULT = "SNOWFLAKE"
+    EXTERNAL_BROWSER = "EXTERNALBROWSER"
+    KEY_PAIR = "SNOWFLAKE_JWT"
+    OAUTH = "OAUTH"
+    OAUTH_AUTHORIZATION_CODE = "OAUTH_AUTHORIZATION_CODE"
+    OAUTH_CLIENT_CREDENTIALS = "OAUTH_CLIENT_CREDENTIALS"
+    USERNAME_PASSWORD_MFA = "USERNAME_PASSWORD_MFA"
+    PROGRAMMATIC_ACCESS_TOKEN = "PROGRAMMATIC_ACCESS_TOKEN"
+    PAT_WITH_EXTERNAL_SESSION = "PAT_WITH_EXTERNAL_SESSION"
+    WORKLOAD_IDENTITY = "WORKLOAD_IDENTITY"
+
+
+__all__ = ["AuthenticatorType"]

snowflake/connector/_internal/backward_compatibility.py

@@ -0,0 +1,245 @@
+"""Runtime machinery backing the ``@backward_compatibility`` decorator.
+
+The public decorator itself lives in :mod:`.decorators` for discoverability;
+everything that supports it — the call-time wrapper, the module-level
+``__getattr__`` installer, the dedup state, and the caller-origin check —
+lives here so ``decorators.py`` stays a thin file of marker/annotation
+decorators.
+
+Three collaborators form the public surface of this module:
+
+* :func:`apply_backward_compatibility` — used by the decorator in
+  :mod:`.decorators`; never called directly by user code.
+* :func:`install_backward_compatibility_getattr` — called at the bottom of
+  modules that export ``@backward_compatibility``-decorated classes, to wire
+  up the PEP 562 ``__getattr__`` that warns on first attribute access.
+* :data:`_BACKWARD_COMPAT_WARNED` — process-wide dedup set; exported for
+  tests only.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import sys
+import warnings
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+
+F = TypeVar("F", bound=Callable)
+T = TypeVar("T")
+
+
+# Callers whose module name starts with any of these prefixes are considered
+# internal and will NOT trigger a backward-compatibility warning. This keeps
+# internal uses (e.g. ``self.populate_data(...)`` called from elsewhere in the
+# driver) silent so the dedup slot remains available for the first external use.
+_INTERNAL_CALLER_PREFIX = "snowflake.connector"
+
+# (module, qualname) pairs that have already emitted a deprecation warning.
+# Used to enforce once-per-process dedup across both the ``__getattr__`` and
+# call-wrapper paths.
+_BACKWARD_COMPAT_WARNED: set[tuple[str, str]] = set()
+
+# Registry of objects processed by ``@backward_compatibility``. We track
+# membership here rather than stamping the decorated object with a marker
+# attribute: (a) descriptors such as ``property`` reject arbitrary attribute
+# assignment, so the marker approach silently failed for them, and (b) the
+# decorator stays non-invasive — the decorated object is never mutated.
+# Classes, functions, and stdlib descriptors are held by identity under the
+# default hash. Plain values (e.g. module-level string constants) hash and
+# compare by *value* instead, so two unrelated constants with the same value
+# would collide here; harmless today (no such collision exists), but a
+# byte-for-byte identical string added elsewhere would be swept in too.
+_MARKED_BACKWARD_COMPAT: set[Any] = set()
+
+_DEPRECATION_WARNING_MSG_SUFFIX = (
+    "is retained only for backward compatibility and is not used by the new driver; "
+    "it may be removed in a future release."
+)
+
+
+def apply_backward_compatibility(obj: T, *, recommendation: str | None = None) -> T:
+    """Implement the ``@backward_compatibility`` decorator.
+
+    Plain functions are wrapped so the first *external* call emits a warning.
+    Classes, descriptors (property, staticmethod, classmethod, etc.), and
+    plain values (e.g. module-level string constants) are passed through
+    unchanged; for those, the module-level ``__getattr__`` installed by
+    :func:`install_backward_compatibility_getattr` turns registry membership
+    into a warn-on-first-access behavior.
+
+    ``recommendation``, if given, is appended to the emitted warning to name
+    the replacement API. Only takes effect for the wrapped-function path;
+    classes ignore it since they never reach :func:`_wrap_fn_with_warning`.
+
+    The returned object is recorded in :data:`_MARKED_BACKWARD_COMPAT` so
+    :func:`install_backward_compatibility_getattr` can later identify which
+    module globals to stash, and so repeated ``@backward_compatibility``
+    decoration is a no-op.
+    """
+    if _is_marked_backward_compat(obj):
+        return obj  # idempotent re-decoration
+
+    result = _wrap_fn_with_warning(obj, recommendation=recommendation) if inspect.isfunction(obj) else obj
+    _mark_backward_compat(result)
+    return result
+
+
+def install_backward_compatibility_getattr(module_name: str) -> None:
+    """Install a module-level ``__getattr__`` that warns on first access of
+    each ``@backward_compatibility``-decorated top-level **class or
+    module-level constant**.
+
+    Must be called at the *bottom* of the target module, after all decorated
+    names have been defined. The tagged names are removed from the module's
+    globals and stashed privately so PEP 562 ``__getattr__`` is invoked on
+    access — which is what lets us distinguish "someone imported this name"
+    from mere module import.
+
+    Top-level functions decorated with ``@backward_compatibility`` are NOT
+    moved here; they already emit a warning on first external call via the
+    call-time wrapper installed by :func:`apply_backward_compatibility`.
+    """
+    module = sys.modules[module_name]
+    stash: dict[str, Any] = {}
+
+    for name, value in list(vars(module).items()):
+        if name.startswith("_"):
+            continue
+        # Functions self-warn via the call-time wrapper installed by
+        # ``apply_backward_compatibility``; never stash them here.
+        if inspect.isfunction(value):
+            continue
+        # ``value`` may be an unhashable module global (e.g. a dict/list),
+        # which can never be a registry member. Probe defensively so the
+        # membership test can't raise TypeError on those globals.
+        try:
+            marked = _is_marked_backward_compat(value)
+        except TypeError:
+            continue
+        if not marked:
+            continue
+        # Classes: only stash those DEFINED in this module, not re-exports.
+        # Non-class marked values (module-level constants) carry no meaningful
+        # ``__module__``, so this re-export guard is scoped to classes.
+        if inspect.isclass(value) and getattr(value, "__module__", None) != module_name:
+            continue
+        stash[name] = value
+        delattr(module, name)
+
+    if not stash:
+        return
+
+    existing_getattr: Callable[[str], Any] | None = module.__dict__.get("__getattr__")
+    module.__getattr__ = _module_getattr_with_warning(  # type: ignore[method-assign]
+        module_name, stash, existing_getattr
+    )
+
+
+def _mark_backward_compat(obj: Any) -> None:
+    _MARKED_BACKWARD_COMPAT.add(obj)
+
+
+def _is_marked_backward_compat(obj: Any) -> bool:
+    return obj in _MARKED_BACKWARD_COMPAT
+
+
+def _wrap_fn_with_warning(obj: F, *, recommendation: str | None = None) -> F:
+    module = getattr(obj, "__module__", None) or ""
+    # Prefer __qualname__ so method warnings read "Class.method" rather than just "method".
+    name = getattr(obj, "__qualname__", None) or getattr(obj, "__name__", None) or ""
+
+    @functools.wraps(obj)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        if _is_caller_external():
+            _emit_backward_compatibility_warning(module, name, recommendation=recommendation)
+        return obj(*args, **kwargs)
+
+    return wrapper  # type: ignore[return-value]
+
+
+def _is_caller_external() -> bool:
+    """Return ``True`` when the frame that invoked our direct caller is NOT
+    part of the ``snowflake.connector`` package tree.
+
+    Used from both the call-time wrapper (:func:`_wrap_fn_with_warning`) and
+    the PEP 562 ``__getattr__`` installed by
+    :func:`install_backward_compatibility_getattr` to suppress warnings for
+    accesses originating inside ``snowflake.connector.*`` — driver-internal
+    use must never consume the once-per-process dedup slot before a customer
+    does. Both call sites sit exactly one Python frame below the caller we
+    care about, which is why the skip count below is fixed at 2.
+    """
+    try:
+        frame = sys._getframe(2)  # skip: this helper + our direct caller
+    except ValueError:
+        return True
+    caller_module = frame.f_globals.get("__name__") or ""
+    return not caller_module.startswith(_INTERNAL_CALLER_PREFIX)
+
+
+def _module_getattr_with_warning(
+    module_name: str,
+    stash: dict[str, Any],
+    existing_getattr: Callable[[str], Any] | None,
+) -> Callable[[str], Any]:
+    """Build the PEP 562 ``__getattr__`` that emits a warning on first access
+    of a stashed backward-compat name and delegates unknown names to any
+    pre-existing module ``__getattr__``.
+
+    Internal accesses (from within ``snowflake.connector.*``) bypass the
+    warning via :func:`_is_caller_external` — the value is still returned so
+    nothing breaks if a driver module does end up importing one of these
+    names, but the one-shot dedup slot stays available for the first real
+    user. A static test enforces that no such internal access exists today.
+    """
+
+    def __getattr__(name: str) -> Any:
+        if name in stash:
+            if _is_caller_external():
+                _emit_backward_compatibility_warning(module_name, name)
+            return stash[name]
+        if existing_getattr is not None:
+            return existing_getattr(name)
+        raise AttributeError(f"module {module_name!r} has no attribute {name!r}")
+
+    return __getattr__
+
+
+def _emit_backward_compatibility_warning(module: str, name: str, *, recommendation: str | None = None) -> None:
+    """Emit a ``DeprecationWarning`` the first time ``module.name`` is used.
+
+    Deduplication is done against an explicit set so the warning is emitted at
+    most once per process per ``(module, name)`` pair regardless of the user's
+    ``warnings`` filter configuration, and regardless of whether the first use
+    was an import (module ``__getattr__``) or a call (wrapped callable).
+
+    ``recommendation``, if given, is appended verbatim to name the replacement
+    API for this specific symbol.
+
+    Concurrency: the check-then-add is not locked. Two threads racing on the
+    same key may each see it as absent and both emit the warning once — an
+    acceptable trade-off vs. taking a lock on every call.
+
+    Stack-level invariant: this function must be called from exactly one
+    Python frame below the user — i.e. from the wrapped-callable wrapper or
+    from the module ``__getattr__``, and nowhere else. Given that, the two
+    call chains are ``user -> wrapper -> _emit -> warn`` and
+    ``user -> __getattr__ -> _emit -> warn``, so ``stacklevel=3`` puts the
+    reported source at the user's frame in both cases. If you add a third
+    call site, keep this invariant or this helper's stacklevel must grow a
+    parameter.
+    """
+    key = (module, name)
+    if key in _BACKWARD_COMPAT_WARNED:
+        return
+    _BACKWARD_COMPAT_WARNED.add(key)
+    suffix = f" {recommendation}" if recommendation else ""
+    warnings.warn(
+        f"'{module}.{name}' {_DEPRECATION_WARNING_MSG_SUFFIX}{suffix}",
+        DeprecationWarning,
+        stacklevel=3,
+    )