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

snowflake/connector/pandas_tools.py

@@ -0,0 +1,191 @@
+"""Public API for writing pandas DataFrames to Snowflake tables.
+
+Usage:
+    from snowflake.connector.pandas_tools import write_pandas
+    success, nchunks, nrows, _ = write_pandas(conn, df, 'my_table')
+
+Implementation details are in snowflake.connector._internal.write_pandas_operation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from functools import partial, wraps
+from typing import TYPE_CHECKING, Any, Literal, TypeVar, cast
+
+from ._common.extras import pandas, requires_dependency, sqlalchemy
+from ._internal.decorators import api_telemetry
+from ._internal.errorhandler import route_exception
+from ._internal.write_pandas_operation import (
+    WritePandasConfig,
+    WritePandasOperation,
+    WritePandasResult,
+    qualify_name,
+)
+from .errors import Error, ProgrammingError
+
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+    from pandas.io.sql import SQLTable
+    from sqlalchemy import engine
+
+    from .connection import Connection
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _reject_kwargs(*names: str) -> Callable[[F], F]:
+    """Reject the listed *names* if they appear in ``**kwargs``.
+
+    Both ``pd_writer`` and ``make_pd_writer`` accept open-ended
+    ``**kwargs`` that are forwarded to :func:`write_pandas`.  Some of
+    those keyword names (``table``, ``conn``, ``keys``, ``data_iter``,
+    ``df``, ``table_name``, ``schema``) overlap with arguments that
+    pandas' ``to_sql`` injects automatically or that ``pd_writer``
+    derives from SQLAlchemy objects.
+
+    If a caller accidentally passes one of them, ``functools.partial``
+    (in ``make_pd_writer``) or ``pd_writer`` itself would silently
+    pre-bind the value and then collide with the positional argument
+    that pandas supplies at call time, producing a confusing
+    ``TypeError: got multiple values for argument '...'``.
+
+    This decorator turns that into an explicit
+    :class:`~snowflake.connector.errors.ProgrammingError` with a
+    clear message *before* the call is made.
+    """
+    forbidden = frozenset(names)
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            found = forbidden & kwargs.keys()
+            if found:
+                raise ProgrammingError(
+                    f"{', '.join(sorted(found))} cannot be passed to {func.__name__}; "
+                    f"{'it is' if len(found) == 1 else 'they are'} derived automatically."
+                )
+            return func(*args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator
+
+
+@requires_dependency(pandas)
+@api_telemetry
+def write_pandas(
+    conn: Connection,
+    df: DataFrame,
+    table_name: str,
+    database: str | None = None,
+    schema: str | None = None,
+    chunk_size: int | None = None,
+    compression: Literal["gzip", "snappy"] = "gzip",
+    on_error: str = "abort_statement",
+    parallel: int = 4,
+    quote_identifiers: bool = True,
+    infer_schema: bool = False,
+    auto_create_table: bool = False,
+    overwrite: bool = False,
+    table_type: Literal["", "temp", "temporary", "transient"] = "",
+    use_logical_type: bool | None = None,
+    iceberg_config: dict[str, str] | None = None,
+    bulk_upload_chunks: bool = False,
+    use_vectorized_scanner: bool = False,
+    **kwargs: Any,
+) -> WritePandasResult:
+    """Write a pandas DataFrame to a Snowflake table via Parquet stage upload.
+
+    Returns a WritePandasResult named tuple (success, nchunks, nrows, copy_results).
+    Backward-compatible with plain tuple unpacking and indexing.
+    """
+    try:
+        cfg = WritePandasConfig(
+            conn,
+            df,
+            table_name,
+            database=database,
+            schema=schema,
+            chunk_size=chunk_size,
+            compression=compression,
+            on_error=on_error,
+            parallel=parallel,
+            quote_identifiers=quote_identifiers,
+            infer_schema=infer_schema,
+            auto_create_table=auto_create_table,
+            overwrite=overwrite,
+            table_type=table_type,
+            use_logical_type=use_logical_type,
+            iceberg_config=iceberg_config,
+            bulk_upload_chunks=bulk_upload_chunks,
+            use_vectorized_scanner=use_vectorized_scanner,
+            **kwargs,
+        )
+        return WritePandasOperation(cfg).execute()
+    except Error as exc:
+        route_exception(conn, None, exc)
+
+
+# ------------------------------------------------------------------
+# Snowpark import surface: snowpark's analyzer_utils imports this name
+# directly from snowflake.connector.pandas_tools.
+# ------------------------------------------------------------------
+
+# Legacy name for a fully-qualified object name; identical to qualify_name, so
+# alias rather than duplicate the escaping logic.
+build_location_helper = qualify_name
+
+
+@requires_dependency(pandas, sqlalchemy)
+@_reject_kwargs("table", "conn", "keys", "data_iter")
+def make_pd_writer(
+    **kwargs: Any,
+) -> Callable:
+    """Return a ``pd_writer`` with pre-bound keyword arguments.
+
+    Useful when you need to pass extra options (e.g. ``parallel``,
+    ``quote_identifiers``) through ``DataFrame.to_sql(method=...)``.
+
+    Example::
+
+        df.to_sql("t", engine, index=False, method=make_pd_writer(parallel=1, quote_identifiers=False))
+    """
+    return partial(pd_writer, **kwargs)
+
+
+@requires_dependency(pandas, sqlalchemy)
+@_reject_kwargs("conn", "df", "table_name", "schema")
+def pd_writer(
+    table: SQLTable,
+    conn: engine.Engine | engine.Connection,
+    keys: Iterable,
+    data_iter: Iterable,
+    **kwargs: Any,
+) -> None:
+    """Adapter for ``DataFrame.to_sql(method=pd_writer)``.
+
+    Wraps :func:`write_pandas` so it satisfies the pandas ``method`` callable
+    protocol.  Extra ``**kwargs`` are forwarded to ``write_pandas`` (except
+    ``conn``, ``df``, ``table_name``, and ``schema`` which are derived from
+    the SQLAlchemy objects).
+
+    Note:
+        Lower-case column names must be quoted in the DataFrame (e.g.
+        ``'"my_col"'``) because snowflake-sqlalchemy creates tables
+        case-insensitively while ``write_pandas`` quotes columns by default.
+
+    Example::
+
+        df.to_sql("driver_versions", engine, index=False, method=pd_writer)
+    """
+    sf_connection = conn.connection.connection
+    df = pandas.DataFrame(data_iter, columns=keys)
+    write_pandas(
+        conn=sf_connection,
+        df=df,
+        table_name=table.name.upper(),
+        schema=table.schema,
+        **kwargs,
+    )

snowflake/connector/result_batch.py

@@ -0,0 +1,216 @@
+"""Result batch classes for distributed fetch.
+
+This module provides ``ResultBatch`` objects that represent individual chunks
+of a query result set.  Each batch can independently fetch and convert its
+data, making them suitable for distributed processing.
+
+These objects are pickleable for easy distribution and replication.
+Note that the URLs stored in remote batches expire; the lifetime is
+dictated by the Snowflake back-end (typically 6 hours).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any, cast
+
+from ._common.extras import pandas, pyarrow, requires_dependency
+from ._internal.api_client.client_api import core_driver
+from ._internal.arrow_stream_utils import (
+    collect_arrow_table,
+    create_row_iterator,
+    create_table_iterator,
+)
+from ._internal.backward_compatibility import install_backward_compatibility_getattr
+from ._internal.decorators import backward_compatibility
+from ._internal.protobuf_gen.database_driver_v1_pb2 import (
+    ColumnMetadata,
+    ResultChunk,
+)
+from ._internal.result_batch import IterTableStructure, IterUnit, ResultBatchMixin
+from ._internal.statement_utils import get_stream_ptr
+
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+    from pyarrow import Table
+
+    from .connection import Connection
+    from .cursor import ResultMetadata
+
+
+class ResultBatch(ResultBatchMixin):
+    """Represents a single chunk of a query result set.
+
+    Each ``ResultBatch`` corresponds to what the Snowflake back-end calls
+    a "result chunk".  Batches know how to retrieve their own data and
+    convert it into Python-native formats.
+
+    Fetching is lazy: the actual download/decode happens when
+    :meth:`create_iter`, :meth:`to_arrow`, or :meth:`to_pandas` is called.
+
+    These objects are pickleable for easy distribution and replication.
+    Remote chunks use presigned URLs and can be fetched without a live
+    connection. Pass an optional :class:`~snowflake.connector.Connection`
+    when you need the connection-scoped HTTP client (for example after
+    unpickling in a worker that opens a fresh session).
+    """
+
+    _connection: Connection | None
+
+    def __init__(
+        self,
+        chunk: ResultChunk,
+        description: list[ResultMetadata],
+        connection: Connection | None,
+        columns: list[ColumnMetadata] | None = None,
+    ) -> None:
+        super().__init__(chunk, description, connection, columns)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def connection(self) -> Connection | None:
+        return self._connection
+
+    @connection.setter
+    def connection(self, value: Connection | None) -> None:
+        self._connection = value
+
+    @property
+    def _errorhandler_connection(self) -> Connection | None:
+        return self._connection
+
+    # ------------------------------------------------------------------
+    # Connection resolution
+    # ------------------------------------------------------------------
+
+    def _resolve_connection(self, connection: Connection | None = None) -> Connection | None:
+        return connection or self._connection
+
+    # ------------------------------------------------------------------
+    # Data fetching
+    # ------------------------------------------------------------------
+
+    def _fetch_arrow_stream_ptr(self, connection: Connection | None = None) -> int:
+        conn_handle = connection.conn_handle if connection is not None else None
+        response = core_driver.database_fetch_chunk(
+            conn_handle=conn_handle,
+            chunk=self._chunk,
+            columns=self._columns,
+        )
+        return get_stream_ptr(response)
+
+    def _take_arrow_stream_ptr(self, connection: Connection | None = None) -> int:
+        """Return the Arrow stream pointer, fetching first if necessary."""
+        if self._arrow_stream_ptr is None:
+            self.populate_data(connection=connection)
+        stream_ptr = cast(int, self._arrow_stream_ptr)
+        self._arrow_stream_ptr = None
+        return stream_ptr
+
+    @backward_compatibility
+    def populate_data(self, connection: Connection | None = None, **kwargs: Any) -> ResultBatch:
+        """Pre-fetch this batch's data and store it for later consumption."""
+        conn = self._resolve_connection(connection)
+        self._arrow_stream_ptr = self._fetch_arrow_stream_ptr(conn)
+        return self
+
+    def __iter__(self) -> Iterator[tuple | dict | Exception]:
+        return self.create_iter()
+
+    def create_iter(
+        self,
+        connection: Connection | None = None,
+        iter_unit: IterUnit | str = IterUnit.ROW_UNIT,
+        structure: IterTableStructure | str = IterTableStructure.PANDAS,
+        use_dict_result: bool = False,
+        number_to_decimal: bool = False,
+        force_microsecond_precision: bool = False,
+    ) -> Iterator[tuple | dict | Exception] | Iterator[Table] | Iterator[DataFrame]:
+        """Create an iterator over this batch's data."""
+        iter_unit = IterUnit.of(iter_unit)
+        structure = IterTableStructure.of(structure)
+
+        conn = self._resolve_connection(connection)
+        if iter_unit == IterUnit.TABLE_UNIT:
+            if structure == IterTableStructure.PANDAS:
+                return iter(
+                    [
+                        self.to_pandas(
+                            connection=conn,
+                            number_to_decimal=number_to_decimal,
+                            force_microsecond_precision=force_microsecond_precision,
+                        )
+                    ]
+                )
+            return iter(
+                [
+                    self.to_arrow(
+                        connection=conn,
+                        number_to_decimal=number_to_decimal,
+                        force_microsecond_precision=force_microsecond_precision,
+                    )
+                ]
+            )
+
+        stream_ptr = self._take_arrow_stream_ptr(conn)
+        return create_row_iterator(
+            stream_ptr,
+            context=self._arrow_context,
+            use_dict_result=use_dict_result,
+            use_numpy=self._numpy,
+            use_core_arrow=self._use_core_arrow,
+        )
+
+    @requires_dependency(pyarrow)
+    def to_arrow(
+        self,
+        connection: Connection | None = None,
+        number_to_decimal: bool = False,
+        force_microsecond_precision: bool = False,
+    ) -> Table:
+        conn = self._resolve_connection(connection)
+        stream_ptr = self._take_arrow_stream_ptr(conn)
+        return collect_arrow_table(
+            create_table_iterator(
+                stream_ptr,
+                context=self._arrow_context,
+                number_to_decimal=number_to_decimal,
+                force_microsecond_precision=force_microsecond_precision,
+                use_core_arrow=self._use_core_arrow,
+            ),
+            self._description,
+        )
+
+    @requires_dependency(pandas)
+    def to_pandas(
+        self,
+        connection: Connection | None = None,
+        number_to_decimal: bool = False,
+        force_microsecond_precision: bool = False,
+    ) -> DataFrame:
+        return self.to_arrow(
+            connection=connection,
+            number_to_decimal=number_to_decimal,
+            force_microsecond_precision=force_microsecond_precision,
+        ).to_pandas()
+
+
+@backward_compatibility
+class ArrowResultBatch(ResultBatch):
+    """Backward-compatibility wrapper around :class:`ResultBatch`."""
+
+
+@backward_compatibility
+class JSONResultBatch(ResultBatch):
+    """Backward-compatibility wrapper around :class:`ResultBatch`."""
+
+
+__all__ = ["IterUnit", "IterTableStructure", "ResultBatch", "ArrowResultBatch", "JSONResultBatch"]
+
+
+# Must be the last statement; see ``install_backward_compatibility_getattr``.
+install_backward_compatibility_getattr(__name__)

snowflake/connector/telemetry.py

@@ -0,0 +1,40 @@
+"""BACKWARD COMPATIBILITY MODULE ONLY"""
+
+import warnings
+
+from enum import Enum
+
+from ._internal.backward_compatibility import _is_caller_external
+
+
+class TelemetryData:
+    TRUE = 1  # snowpark_compat
+    FALSE = 0  # snowpark_compat
+
+    def __init__(self, message: str, timestamp: int) -> None:
+        self.message = message
+        self.timestamp = timestamp
+
+
+class TelemetryField(Enum):
+    KEY_SOURCE = "source"
+    KEY_TYPE = "type"
+
+
+_TRY_ADD_LOG_TO_BATCH_WARNED = False
+
+
+class TelemetryClient:
+    def try_add_log_to_batch(self, *args, **kwargs):  # type: ignore
+        global _TRY_ADD_LOG_TO_BATCH_WARNED
+        if not _TRY_ADD_LOG_TO_BATCH_WARNED and _is_caller_external():
+            _TRY_ADD_LOG_TO_BATCH_WARNED = True
+            warnings.warn(
+                "'snowflake.connector.telemetry.TelemetryClient.try_add_log_to_batch' "
+                "is retained only for backward compatibility and is not used by the "
+                "Universal Driver; use 'snowflake.connector._common.telemetry' instead. "
+                "It may be removed in a future release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        raise NotImplementedError()

snowflake/connector/time_util.py

@@ -0,0 +1,11 @@
+"""BACKWARD COMPATIBILITY MODULE ONLY"""
+
+import time
+
+from snowflake.connector._internal import internal_api
+
+
+@internal_api
+def get_time_millis() -> int:
+    """Return the current time in milliseconds."""
+    return int(time.time() * 1000)

snowflake/connector/types.py

@@ -0,0 +1,134 @@
+"""
+PEP 249 Database API 2.0 Type Objects and Constructors
+
+This module defines the type constructors and type objects as specified in PEP 249.
+"""
+
+import datetime
+
+from typing import Any
+
+
+# Type Constructors
+def Date(year: int, month: int, day: int) -> datetime.date:
+    """
+    Construct an object holding a date value.
+
+    Args:
+        year: Year
+        month: Month
+        day: Day
+
+    Returns:
+        datetime.date: Date object
+    """
+    return datetime.date(year, month, day)
+
+
+def Time(hour: int, minute: int, second: int) -> datetime.time:
+    """
+    Construct an object holding a time value.
+
+    Args:
+        hour: Hour
+        minute: Minute
+        second: Second
+
+    Returns:
+        datetime.time: Time object
+    """
+    return datetime.time(hour, minute, second)
+
+
+def Timestamp(year: int, month: int, day: int, hour: int, minute: int, second: int) -> datetime.datetime:
+    """
+    Construct an object holding a timestamp value.
+
+    Args:
+        year: Year
+        month: Month
+        day: Day
+        hour: Hour
+        minute: Minute
+        second: Second
+
+    Returns:
+        datetime.datetime: Timestamp object
+    """
+    return datetime.datetime(year, month, day, hour, minute, second)
+
+
+def DateFromTicks(ticks: float) -> datetime.date:
+    """
+    Construct an object holding a date value from the given ticks value.
+
+    Args:
+        ticks: Seconds since the epoch
+
+    Returns:
+        datetime.date: Date object
+    """
+    return datetime.date.fromtimestamp(ticks)
+
+
+def TimeFromTicks(ticks: float) -> datetime.time:
+    """
+    Construct an object holding a time value from the given ticks value.
+
+    Args:
+        ticks: Seconds since the epoch
+
+    Returns:
+        datetime.time: Time object
+    """
+    return datetime.datetime.fromtimestamp(ticks).time()
+
+
+def TimestampFromTicks(ticks: float) -> datetime.datetime:
+    """
+    Construct an object holding a timestamp value from the given ticks value.
+
+    Args:
+        ticks: Seconds since the epoch
+
+    Returns:
+        datetime.datetime: Timestamp object
+    """
+    return datetime.datetime.fromtimestamp(ticks)
+
+
+def Binary(string: str | bytes) -> bytes:
+    """
+    Construct an object capable of holding a binary (long) string value.
+
+    Args:
+        string: Binary data
+
+    Returns:
+        bytes: Binary object
+    """
+    if isinstance(string, str):
+        return string.encode("utf-8")
+    return bytes(string)
+
+
+# Type Objects for comparison
+class DBAPITypeObject:
+    """Base class for type objects that support comparison with database types."""
+
+    def __init__(self, *values: str) -> None:
+        self.values = values
+
+    def __eq__(self, other: Any) -> bool:
+        return other in self.values
+
+    def __ne__(self, other: Any) -> bool:
+        return other not in self.values
+
+
+# Type objects for describing database column types
+STRING = DBAPITypeObject("STRING", "VARCHAR", "CHAR", "TEXT")
+BINARY = DBAPITypeObject("BINARY", "VARBINARY", "BLOB")
+NUMBER = DBAPITypeObject("NUMBER", "INTEGER", "INT", "FLOAT", "DOUBLE", "DECIMAL", "NUMERIC")
+DATETIME = DBAPITypeObject("DATETIME", "DATE", "TIME", "TIMESTAMP")
+ROWID = DBAPITypeObject("ROWID", "OID")

snowflake/connector/util_text.py

@@ -0,0 +1,3 @@
+"""BACKWARD COMPATIBILITY MODULE ONLY"""
+
+from ._internal.text_utils import split_statements  # noqa

snowflake/connector/version.py

@@ -0,0 +1,23 @@
+# PEP 440 compliant version string (used by hatch for packaging)
+__version__ = "5.2.0"
+
+
+def _release_components(version: str) -> tuple[int, ...]:
+    components = []
+    for segment in version.split("."):
+        numeric = ""
+        for char in segment:
+            if char.isdigit():
+                numeric += char
+            else:
+                break
+        if not numeric:
+            break
+        components.append(int(numeric))
+        if len(numeric) != len(segment):
+            break
+    return tuple(components)
+
+
+# Compatibility with old driver pattern
+VERSION = (*_release_components(__version__), None)

snowflake_connector_python-5.2.0.dist-info/DELVEWHEEL

@@ -0,0 +1,2 @@
+Version: 1.13.0
+Arguments: ['C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-xhv57y_d\\cp315-win_amd64\\build\\venv\\Scripts\\delvewheel', 'repair', '--namespace-pkg', 'snowflake', '-w', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-xhv57y_d\\cp315-win_amd64\\repaired_wheel', '-v', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-xhv57y_d\\cp315-win_amd64\\built_wheel\\snowflake_connector_python-5.2.0-cp315-cp315-win_amd64.whl']