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

snowflake/connector/_internal/decorators.py

@@ -0,0 +1,539 @@
+"""Marker, annotation, and precondition wrapper decorators for internal APIs.
+
+The runtime machinery for ``@backward_compatibility`` (call-time wrapper,
+module ``__getattr__`` installer, dedup state) lives in
+:mod:`._internal.backward_compatibility`; this module is intentionally kept
+to just the decorator façade.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import types
+
+from collections.abc import AsyncGenerator, Awaitable, Callable, Coroutine, Generator
+from contextvars import ContextVar
+from typing import Any, Generic, ParamSpec, Protocol, TypeVar, cast, overload
+
+from .backward_compatibility import apply_backward_compatibility
+from .logging import get_logger
+
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+P = ParamSpec("P")
+
+# Generic pass-through: functions, classes, and descriptors all round-trip
+# through ``@backward_compatibility`` as the same logical type (a class stays
+# the same class; a wrapped function preserves its signature via
+# ``functools.wraps``). Using ``TypeVar("T")`` lets mypy preserve the input
+# type across the decorator instead of widening it to ``Any``.
+T = TypeVar("T")
+
+
+def internal_api(func: F) -> F:
+    """
+    Mark a method or function as internal.
+    This is an identity function that returns the function unchanged.
+    It serves as a marker for internal APIs that should not be used by external consumers.
+    Args:
+        func: The function or method to mark as internal
+    Returns:
+        The unchanged function
+    """
+    return func
+
+
+def pep249(func: F) -> F:
+    """Mark a method or property as defined by PEP 249 (required or optional)."""
+    return func
+
+
+def snowpark_compat(func: F) -> F:
+    """No-op marker: method/property added only for Snowpark's private-API surface (like :func:`pep249`)."""
+    return func
+
+
+class _AsyncContextManagerLike(Protocol):
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Any: ...
+
+
+R = TypeVar("R", bound=_AsyncContextManagerLike)
+
+
+class _AwaitableContextManager(Generic[R]):
+    """Wrapper returned by :func:`awaitable_context_manager` decorated functions.
+
+    Supports both ``await fn(...)`` and ``async with fn(...) as result:``.
+    The ``__aexit__`` delegates to the returned object's ``__aexit__``, so
+    the wrapped coroutine must return an async context manager.
+    """
+
+    def __init__(self, coro: Coroutine[Any, Any, R]) -> None:
+        self._coro = coro
+        self._obj: R | None = None
+
+    def __await__(self) -> Generator[Any, None, R]:
+        return self._coro.__await__()
+
+    async def __aenter__(self) -> R:
+        self._obj = await self._coro
+        return self._obj
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Any:
+        if self._obj is not None:
+            return await self._obj.__aexit__(exc_type, exc_val, exc_tb)
+
+
+def awaitable_context_manager(
+    func: Callable[P, Coroutine[Any, Any, R]],
+) -> Callable[P, _AwaitableContextManager[R]]:
+    """Make an ``async def`` factory support both ``await`` and ``async with``.
+
+    The decorated function must return an object that implements
+    ``__aenter__`` / ``__aexit__`` (i.e. an async context manager).
+
+    Usage::
+
+        @awaitable_context_manager
+        async def connect(**kwargs):
+            conn = Connection(**kwargs)
+            await conn.open()
+            return conn
+
+
+        # Both patterns work:
+        conn = await connect(...)
+        async with connect(...) as conn:
+            ...
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> _AwaitableContextManager[R]:
+        return _AwaitableContextManager(func(*args, **kwargs))
+
+    return wrapper
+
+
+@overload
+def backward_compatibility(obj: T, *, recommendation: str | None = None) -> T: ...
+
+
+@overload
+def backward_compatibility(*, recommendation: str | None = None) -> Callable[[T], T]: ...
+
+
+def backward_compatibility(obj: T | None = None, *, recommendation: str | None = None) -> T | Callable[[T], T]:
+    """Mark an object as a backward-compatibility shim and, where applicable,
+    wrap it so that first external use emits a ``DeprecationWarning``.
+
+    The emitted message always names the symbol (``module.qualname``) and
+    explains that it is retained only for backward compatibility. Usable bare
+    (``@backward_compatibility``) or, to name a specific replacement API in the
+    warning, called with a keyword argument
+    (``@backward_compatibility(recommendation="Use `foo` instead.")``).
+    ``recommendation`` only affects function/method targets — see below.
+
+    Behavior by target type:
+
+    * **Class** — registered only; the object is returned unchanged. Paired
+      with
+      :func:`~snowflake.connector._internal.backward_compatibility.install_backward_compatibility_getattr`,
+      the warning fires on first attribute access (e.g.
+      ``from ...errors import HttpError`` or ``errors.HttpError``). Classes
+      are never wrapped because "use" of a class takes too many shapes
+      (``isinstance``, ``raise``, subclassing); ``recommendation`` is ignored.
+
+    * **Function / method** — wrapped so the first *external* call emits a
+      warning. Calls originating from inside ``snowflake.connector.*`` are
+      silent, so the driver's own internal uses don't consume the one-shot
+      warning slot before the customer ever sees it.
+
+    * **Descriptor (``property``, ``staticmethod``, ``classmethod``, …)** —
+      registered only; the descriptor is returned unchanged. To warn on
+      descriptor access, apply ``@backward_compatibility`` to the *raw
+      function* (i.e. *below* ``@property`` / ``@prop.setter``) so the
+      call-time wrapper is installed before the descriptor is built on top.
+
+    * **Plain value** (e.g. a module-level string constant) — registered
+      only; the value is returned unchanged. Like classes, it warns on first
+      attribute access once paired with
+      :func:`~snowflake.connector._internal.backward_compatibility.install_backward_compatibility_getattr`,
+      since there is no "call" to intercept.
+    """
+    if obj is None:
+        return lambda target: apply_backward_compatibility(target, recommendation=recommendation)
+    return apply_backward_compatibility(obj, recommendation=recommendation)
+
+
+# ------------------------------------------------------------------
+# Precondition wrappers (connection/cursor @requires_open, etc.)
+# ------------------------------------------------------------------
+
+
+def wrap_method_with_sync_pre(
+    func: F,
+    *,
+    pre: Callable[[Any], None],
+) -> F:
+    """Wrap *func* with a sync pre-call hook (used for both sync and async methods)."""
+    if inspect.isasyncgenfunction(func):
+
+        @functools.wraps(func)
+        async def gen_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            pre(self)
+            async for value in func(self, *args, **kwargs):
+                yield value
+
+        return cast(F, gen_wrapper)
+
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            pre(self)
+            return await func(self, *args, **kwargs)
+
+        return cast(F, async_wrapper)
+
+    @functools.wraps(func)
+    def sync_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        pre(self)
+        return func(self, *args, **kwargs)
+
+    return cast(F, sync_wrapper)
+
+
+def wrap_method_with_awaitable_pre(
+    func: F,
+    *,
+    sync_pre: Callable[[Any], None],
+    async_pre: Callable[[Any], Awaitable[None]],
+) -> F:
+    """Wrap *func* with sync/async pre-call hooks when the pre itself may await."""
+    if inspect.isasyncgenfunction(func):
+
+        @functools.wraps(func)
+        async def gen_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            await async_pre(self)
+            async for value in func(self, *args, **kwargs):
+                yield value
+
+        return cast(F, gen_wrapper)
+
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            await async_pre(self)
+            return await func(self, *args, **kwargs)
+
+        return cast(F, async_wrapper)
+
+    @functools.wraps(func)
+    def sync_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        sync_pre(self)
+        return func(self, *args, **kwargs)
+
+    return cast(F, sync_wrapper)
+
+
+_TRACKING: ContextVar[bool] = ContextVar("_api_tracking", default=True)
+
+
+def _telemetry_client_if_enabled(self: Any) -> Any:
+    """Return the telemetry client for *self*, or ``None`` if there is none to send to
+    or ``Connection.telemetry_enabled`` is currently ``False``.
+
+    Deliberately re-implements the ``telemetry_enabled`` AND rather than reading
+    the public property: that property is ``@api_telemetry``-decorated, and
+    calling it from here (inside telemetry dispatch) would recurse into sending
+    telemetry about itself.
+    """
+    from snowflake.connector.aio.connection._connection import Connection as AsyncConnection
+    from snowflake.connector.aio.cursor._base import SnowflakeCursorBase as AsyncSnowflakeCursorBase
+    from snowflake.connector.connection import Connection
+    from snowflake.connector.cursor._base import SnowflakeCursorBase
+
+    if isinstance(self, (Connection, AsyncConnection)):
+        connection = self
+    elif isinstance(self, (SnowflakeCursorBase, AsyncSnowflakeCursorBase)):
+        connection = self._connection
+    else:
+        raise TypeError(f"Unexpected telemetry target: {type(self)!r}")
+
+    client = getattr(connection, "_telemetry_client", None)
+    if client is None or getattr(client, "_closed", False):
+        return None
+    if not (connection._client_param_telemetry_enabled and connection._server_param_telemetry_enabled()):
+        return None
+    return client
+
+
+def _passed_argument_names(
+    sig: inspect.Signature,
+    self: Any,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> list[str]:
+    """Return the names of the arguments the caller explicitly passed.
+
+    Signature only — never argument values. Parameters the caller left at
+    their default are omitted, because :attr:`BoundArguments.arguments` only
+    contains arguments that were actually supplied (we deliberately do not
+    call ``apply_defaults()``). ``**kwargs`` entries are expanded to the
+    keyword names the caller used, since the var-keyword parameter name
+    itself (e.g. ``"kwargs"``) carries no signal. The first positional
+    (connection/cursor instance) is dropped.
+
+    Defensive by design: any binding failure yields ``[]`` so telemetry can
+    never break the wrapped call.
+    """
+    try:
+        bound = sig.bind(self, *args, **kwargs)
+    except TypeError:
+        return []
+    names: list[str] = []
+    for index, (name, bound_arg) in enumerate(bound.arguments.items()):
+        if index == 0:
+            continue  # first positional (connection/cursor), always bound first by the wrapper
+        param = sig.parameters[name]
+        if param.kind is inspect.Parameter.VAR_KEYWORD:
+            names.extend(bound_arg.keys())
+        else:
+            names.append(name)
+    return names
+
+
+def _schedule_async_telemetry(coro: Any) -> None:
+    """Fire-and-forget async telemetry when a sync decorated method runs under a loop."""
+    try:
+        asyncio.get_running_loop().create_task(coro)
+    except RuntimeError:
+        coro.close()
+        logger.debug("Skipped async telemetry with no running event loop", exc_info=True)
+
+
+def _api_method_name(self: Any, func: Callable[..., Any], *, async_path: bool) -> str:
+    name = f"{type(self).__name__}.{func.__name__}"
+    if async_path:
+        return f"async {name}"
+    return name
+
+
+def _send_api_usage(self: Any, func: Callable[..., Any], passed_arguments: list[str]) -> None:
+    """Send the ``{ClassName}.{method_name}`` API-usage telemetry for *self*."""
+    try:
+        from snowflake.connector._common.telemetry import AsyncTelemetryClient
+
+        api_name = _api_method_name(self, func, async_path=False)
+        client = _telemetry_client_if_enabled(self)
+        if client is None:
+            return
+        if isinstance(client, AsyncTelemetryClient):
+            _schedule_async_telemetry(client.send_api_usage(api_name, passed_arguments))
+        else:
+            client.send_api_usage(api_name, passed_arguments)
+    except Exception:
+        logger.debug("Failed to send api_usage telemetry", exc_info=True)
+
+
+async def _send_api_usage_async(self: Any, func: Callable[..., Any], passed_arguments: list[str]) -> None:
+    """Async counterpart of :func:`_send_api_usage`.
+
+    Coroutine and async-generator methods record
+    ``async {ClassName}.{method_name}`` so they are distinguishable from the
+    sync methods that share the same class and function names.
+    """
+    try:
+        from snowflake.connector._common.telemetry import AsyncTelemetryClient
+
+        api_name = _api_method_name(self, func, async_path=True)
+        client = _telemetry_client_if_enabled(self)
+        if client is None:
+            return
+        if isinstance(client, AsyncTelemetryClient):
+            await client.send_api_usage(api_name, passed_arguments)
+        else:
+            client.send_api_usage(api_name, passed_arguments)
+    except Exception:
+        logger.debug("Failed to send api_usage telemetry", exc_info=True)
+
+
+def api_telemetry(func: F) -> F:
+    """Record API-usage telemetry for the outermost call.
+
+    Suppresses ``_TRACKING`` for the method body so nested decorated calls
+    are not recorded.  Generator results are wrapped to suppress only during
+    each iteration step (see :func:`_suppress_tracking_generator`).
+
+    Supports synchronous functions, coroutine functions, and async generator
+    functions — the suppression always spans the actual execution of the
+    wrapped callable (the awaited body or each iteration step). Sync methods
+    record ``{ClassName}.{method_name}``; coroutine and async-generator
+    methods record ``async {ClassName}.{method_name}``.
+
+    Alongside the method name, the names of the arguments the caller
+    explicitly passed are recorded (see :func:`_passed_argument_names`) —
+    names only, never values, and parameters left at their default are
+    omitted.
+
+    Free functions (first parameter name is neither ``self`` nor ``cls``) are
+    wrapped with a signature-transparent ``(*args, **kwargs)`` wrapper.
+    Telemetry dispatch is skipped for free functions because there is no
+    ``self`` from which to retrieve the telemetry client; ``_TRACKING``
+    suppression still applies so nested decorated calls are not double-counted.
+    """
+    sig = inspect.signature(func)
+    params = list(sig.parameters)
+    _is_method = bool(params) and params[0] in ("self", "cls")
+
+    if inspect.iscoroutinefunction(func):
+        if _is_method:
+
+            @functools.wraps(func)
+            async def async_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+                if _TRACKING.get():
+                    await _send_api_usage_async(self, func, _passed_argument_names(sig, self, args, kwargs))
+                    _TRACKING.set(False)
+                    try:
+                        return await func(self, *args, **kwargs)
+                    finally:
+                        _TRACKING.set(True)
+                return await func(self, *args, **kwargs)
+
+            return cast(F, async_wrapper)
+
+        @functools.wraps(func)
+        async def async_free_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if _TRACKING.get():
+                _TRACKING.set(False)
+                try:
+                    return await func(*args, **kwargs)
+                finally:
+                    _TRACKING.set(True)
+            return await func(*args, **kwargs)
+
+        return cast(F, async_free_wrapper)
+
+    if inspect.isasyncgenfunction(func):
+        if _is_method:
+
+            @functools.wraps(func)
+            async def async_gen_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+                if _TRACKING.get():
+                    await _send_api_usage_async(self, func, _passed_argument_names(sig, self, args, kwargs))
+                    async for value in _suppress_tracking_async_generator(func(self, *args, **kwargs)):
+                        yield value
+                else:
+                    async for value in func(self, *args, **kwargs):
+                        yield value
+
+            return cast(F, async_gen_wrapper)
+
+        @functools.wraps(func)
+        async def async_gen_free_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if _TRACKING.get():
+                async for value in _suppress_tracking_async_generator(func(*args, **kwargs)):
+                    yield value
+            else:
+                async for value in func(*args, **kwargs):
+                    yield value
+
+        return cast(F, async_gen_free_wrapper)
+
+    if _is_method:
+
+        @functools.wraps(func)
+        def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            if _TRACKING.get():
+                if func.__name__ == "__init__":
+                    # Compute argument names before calling (kwargs are not consumed by
+                    # the call), but send telemetry post-call so _telemetry_client is ready.
+                    passed_args = _passed_argument_names(sig, self, args, kwargs)
+                    _TRACKING.set(False)
+                    try:
+                        result = func(self, *args, **kwargs)
+                    finally:
+                        _TRACKING.set(True)
+                    _send_api_usage(self, func, passed_args)
+                    return result
+
+                _send_api_usage(self, func, _passed_argument_names(sig, self, args, kwargs))
+
+                _TRACKING.set(False)
+                try:
+                    result = func(self, *args, **kwargs)
+                finally:
+                    _TRACKING.set(True)
+
+                if isinstance(result, types.GeneratorType):
+                    return _suppress_tracking_generator(result)
+
+                return result
+            return func(self, *args, **kwargs)
+
+        return cast(F, wrapper)
+
+    @functools.wraps(func)
+    def free_wrapper(*args: Any, **kwargs: Any) -> Any:
+        if _TRACKING.get():
+            _TRACKING.set(False)
+            try:
+                result = func(*args, **kwargs)
+            finally:
+                _TRACKING.set(True)
+
+            if isinstance(result, types.GeneratorType):
+                return _suppress_tracking_generator(result)
+
+            return result
+        return func(*args, **kwargs)
+
+    return cast(F, free_wrapper)
+
+
+def _suppress_tracking_generator(
+    gen: Generator[Any, Any, Any],
+) -> Generator[Any, Any, Any]:
+    """Suppress ``_TRACKING`` during each iteration step, restore between yields.
+
+    Safe against never-started generators: the wrapper body only runs when
+    iterated, and ``api_telemetry`` resets ``_TRACKING`` before creating it.
+    """
+    _TRACKING.set(False)
+    try:
+        for value in gen:
+            _TRACKING.set(True)
+            try:
+                yield value
+            except GeneratorExit:
+                gen.close()
+                return
+            _TRACKING.set(False)
+    finally:
+        _TRACKING.set(True)
+
+
+async def _suppress_tracking_async_generator(
+    agen: AsyncGenerator[Any, Any],
+) -> AsyncGenerator[Any, Any]:
+    """Async counterpart of :func:`_suppress_tracking_generator`.
+
+    Suppress ``_TRACKING`` during each iteration step, restore between yields.
+    """
+    _TRACKING.set(False)
+    try:
+        async for value in agen:
+            _TRACKING.set(True)
+            try:
+                yield value
+            except GeneratorExit:
+                await agen.aclose()
+                return
+            _TRACKING.set(False)
+    finally:
+        _TRACKING.set(True)

snowflake/connector/_internal/error_kinds.py

@@ -0,0 +1,111 @@
+"""
+Proto ErrorKind → PEP 249 exception class / errno mappings.
+
+ERROR_KIND_* values are imported from the generated pb2 module so they
+stay in sync with the Rust core automatically.
+"""
+
+from __future__ import annotations
+
+from ..errors import (
+    DatabaseError,
+    Error,
+    IntegrityError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+)
+from .errorcode import (
+    ER_COMPRESSION_NOT_SUPPORTED,
+    ER_FAILED_TO_CONNECT_TO_DB,
+    ER_FILE_NOT_EXISTS,
+    ER_INVALID_VALUE,
+)
+from .protobuf_gen.database_driver_v1_pb2 import (
+    ERROR_KIND_AUTHENTICATION_ERROR,
+    ERROR_KIND_CANCELLED,
+    ERROR_KIND_INTERNAL_ERROR,
+    ERROR_KIND_INVALID_ARGUMENT,
+    ERROR_KIND_INVALID_PARAMETER_VALUE,
+    ERROR_KIND_IO,
+    ERROR_KIND_LOCAL_FILE_NOT_FOUND,
+    ERROR_KIND_LOGIN_ERROR,
+    ERROR_KIND_MISSING_PARAMETER,
+    ERROR_KIND_NOT_IMPLEMENTED,
+    ERROR_KIND_QUERY_FAILED,
+    ERROR_KIND_REMOTE_FILE_NOT_FOUND,
+    ERROR_KIND_STAGE_BINDING,
+    ERROR_KIND_TIMEOUT,
+    ERROR_KIND_UNSUPPORTED_COMPRESSION,
+)
+
+
+ERROR_KIND_LABELS: dict[int, str] = {
+    ERROR_KIND_AUTHENTICATION_ERROR: "Authentication error",
+    ERROR_KIND_NOT_IMPLEMENTED: "Not implemented",
+    ERROR_KIND_INVALID_ARGUMENT: "Invalid argument",
+    ERROR_KIND_IO: "I/O error",
+    ERROR_KIND_CANCELLED: "Cancelled",
+    ERROR_KIND_INTERNAL_ERROR: "Internal error",
+    ERROR_KIND_MISSING_PARAMETER: "Missing parameter",
+    ERROR_KIND_INVALID_PARAMETER_VALUE: "Invalid parameter value",
+    ERROR_KIND_LOGIN_ERROR: "Login error",
+    ERROR_KIND_LOCAL_FILE_NOT_FOUND: "Local file not found",
+    ERROR_KIND_REMOTE_FILE_NOT_FOUND: "Remote file not found",
+    ERROR_KIND_UNSUPPORTED_COMPRESSION: "Unsupported compression type",
+    ERROR_KIND_QUERY_FAILED: "Query failed",
+    ERROR_KIND_TIMEOUT: "Timeout",
+    ERROR_KIND_STAGE_BINDING: "Stage binding",
+}
+
+KIND_TO_EXCEPTION: dict[int, type[Error]] = {
+    ERROR_KIND_AUTHENTICATION_ERROR: DatabaseError,
+    ERROR_KIND_NOT_IMPLEMENTED: NotSupportedError,
+    ERROR_KIND_INVALID_ARGUMENT: ProgrammingError,
+    ERROR_KIND_IO: OperationalError,
+    ERROR_KIND_CANCELLED: OperationalError,
+    # Leftover driver faults (locks, parse, spool). Query failures use QUERY_FAILED.
+    ERROR_KIND_INTERNAL_ERROR: InternalError,
+    ERROR_KIND_MISSING_PARAMETER: ProgrammingError,
+    ERROR_KIND_INVALID_PARAMETER_VALUE: ProgrammingError,
+    ERROR_KIND_LOGIN_ERROR: DatabaseError,
+    ERROR_KIND_LOCAL_FILE_NOT_FOUND: ProgrammingError,
+    ERROR_KIND_REMOTE_FILE_NOT_FOUND: OperationalError,
+    ERROR_KIND_UNSUPPORTED_COMPRESSION: ProgrammingError,
+    ERROR_KIND_QUERY_FAILED: ProgrammingError,
+    ERROR_KIND_TIMEOUT: OperationalError,
+    # CSV bind-upload to SYSTEM$BIND failed. Same class as other transfer I/O.
+    ERROR_KIND_STAGE_BINDING: OperationalError,
+}
+
+# Snowflake vendor_code → exception overrides.
+#
+# KIND_TO_EXCEPTION maps the proto ErrorKind (a broad category) to a default PEP 249 class.
+# Some Snowflake server errors share the same ErrorKind (e.g. ERROR_KIND_QUERY_FAILED)
+# but carry a vendor_code that warrants a more specific exception.
+# Entries here take precedence over KIND_TO_EXCEPTION when a vendor_code is present.
+VENDOR_CODE_TO_EXCEPTION: dict[int, type[Error]] = {
+    100072: IntegrityError,  # NULL result in a non-nullable column
+}
+
+
+def is_stage_binding_disabled(exc: Exception) -> bool:
+    """Whether *exc* came from a disabled ``SYSTEM$BIND`` stage.
+
+    ``errno`` falls back to the raw ``kind`` when no vendor_code or
+    KIND_TO_ERRNO entry applies (see ``_convert_application_error``), so
+    ``ERROR_KIND_STAGE_BINDING`` survives unchanged onto the exception.
+    """
+    return isinstance(exc, OperationalError) and getattr(exc, "errno", None) == ERROR_KIND_STAGE_BINDING
+
+
+# Prefer the Snowflake server vendor_code when the core driver provides it, fallback to this mapping if not present.
+KIND_TO_ERRNO: dict[int, int] = {
+    ERROR_KIND_AUTHENTICATION_ERROR: ER_FAILED_TO_CONNECT_TO_DB,
+    ERROR_KIND_LOGIN_ERROR: ER_FAILED_TO_CONNECT_TO_DB,
+    ERROR_KIND_INVALID_PARAMETER_VALUE: ER_INVALID_VALUE,
+    ERROR_KIND_LOCAL_FILE_NOT_FOUND: ER_FILE_NOT_EXISTS,
+    ERROR_KIND_REMOTE_FILE_NOT_FOUND: ER_FILE_NOT_EXISTS,
+    ERROR_KIND_UNSUPPORTED_COMPRESSION: ER_COMPRESSION_NOT_SUPPORTED,
+}

snowflake/connector/_internal/errorcode.py

@@ -0,0 +1,35 @@
+"""
+Snowflake error codes.
+
+These codes are intentionally aligned with the reference snowflake-connector-python
+so that users can rely on stable, documented error numbers across driver implementations.
+"""
+
+from __future__ import annotations
+
+
+# network
+ER_FAILED_TO_CONNECT_TO_DB = 250001
+ER_CONNECTION_IS_CLOSED = 250002
+
+# connection
+ER_NO_ACCOUNT_NAME = 251001
+ER_NO_USER = 251005
+ER_NO_PASSWORD = 251006
+ER_INVALID_VALUE = 251007
+ER_INVALID_WIF_SETTINGS = 251017
+
+# cursor
+ER_FAILED_TO_REWRITE_MULTI_ROW_INSERT = 252001
+ER_FAILED_TO_CONVERT_ROW_TO_PYTHON_TYPE = 252005
+ER_CURSOR_IS_CLOSED = 252006
+ER_NO_DATA_FOUND = 252009
+
+# file transfer
+ER_FILE_NOT_EXISTS = 253006
+ER_COMPRESSION_NOT_SUPPORTED = 253007
+
+# converter
+ER_NOT_SUPPORT_DATA_TYPE = 255001
+ER_NO_PYARROW = 255002
+ER_NO_NUMPY = 255006