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

snowflake/connector/_internal/arrow.py

@@ -0,0 +1,47 @@
+"""Shared protocols for Arrow row and table iterators (Cython nanoarrow and native PyO3)."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, Protocol
+
+
+class ArrowRowIterator(Protocol):
+    """Row iterator produced by ``create_row_iterator``.
+
+    Both the Cython ``ArrowStreamIterator`` and the PyO3
+    ``sf_core_python.ArrowStreamIterator`` (``native-arrow`` builds) satisfy
+    this protocol, so call sites do not branch on the backend.
+    """
+
+    def __iter__(self) -> ArrowRowIterator: ...
+    def __next__(self) -> Any: ...
+    def fetch_many(self, size: int) -> list[Any]: ...
+    def fetch_all(self) -> list[Any]: ...
+
+
+class AsyncArrowRowIterator(Protocol):
+    """Async row iterator used by the aio cursor and ResultBatch.
+
+    The ``to_thread`` wrapper over a sync iterator and the driver over the
+    PyO3 batch reader (``native-arrow`` builds) both satisfy this protocol.
+    """
+
+    def __aiter__(self) -> AsyncIterator[Any]: ...
+    async def __anext__(self) -> Any: ...
+    async def fetch_next(self, default: object = None) -> Any: ...
+    async def fetch_many(self, size: int) -> list[Any]: ...
+    async def fetch_all(self) -> list[Any]: ...
+
+
+class ArrowTableIterator(Protocol):
+    """RecordBatch iterator produced by ``create_table_iterator``.
+
+    Both the Cython ``ArrowStreamTableIterator`` and the PyO3
+    ``sf_core_python.ArrowStreamTableIterator`` (``native-arrow`` builds)
+    satisfy this protocol, so call sites do not branch on the backend.
+    """
+
+    def __iter__(self) -> ArrowTableIterator: ...
+    def __next__(self) -> Any: ...
+    def get_converted_schema(self) -> Any: ...

snowflake/connector/_internal/arrow_context.py

@@ -0,0 +1,240 @@
+"""Arrow converter context for type conversions.
+
+This module is based on the original snowflake-connector-python arrow_context.py
+and provides Python helper functions for Arrow conversions in the C++ converters.
+"""
+
+from __future__ import annotations
+
+import decimal
+
+from datetime import datetime, timedelta, timezone, tzinfo
+from sys import byteorder
+from typing import TYPE_CHECKING, Any, Callable
+
+import pytz
+
+from .logging import get_logger
+from .._common.extras import numpy as np
+from .._common.extras import tzlocal, MissingOptionalDependency
+
+if TYPE_CHECKING:
+    from numpy import datetime64, float64, int64, timedelta64
+
+    from ..aio.connection import Connection as AsyncConnection
+    from ..connection import Connection
+
+
+ZERO_EPOCH = datetime.fromtimestamp(0, timezone.utc).replace(tzinfo=None)
+PARAMETER_TIMEZONE = "TIMEZONE"
+logger = get_logger(__name__)
+
+
+def _generate_tzinfo_from_tzoffset(tzoffset_minutes: int) -> tzinfo:
+    """Generate tzinfo object from tzoffset."""
+    return pytz.FixedOffset(tzoffset_minutes)
+
+
+def interval_year_month_to_string(interval: int, scale: int) -> str:
+    """Convert a year-month interval to a string.
+
+    Args:
+        interval: The year-month interval value in months.
+        scale: The scale of the interval which represents subtype as follows:
+            0: INTERVAL YEAR TO MONTH
+            1: INTERVAL YEAR
+            2: INTERVAL MONTH
+
+    Returns:
+        The string representation of the interval.
+    """
+    sign = "+" if interval >= 0 else "-"
+    interval = abs(interval)
+    if scale == 2:  # INTERVAL MONTH
+        return f"{sign}{interval}"
+    years = interval // 12
+    if scale == 1:  # INTERVAL YEAR
+        return f"{sign}{years}"
+    # INTERVAL YEAR TO MONTH
+    months = interval % 12
+    return f"{sign}{years}-{months:02}"
+
+
+class ArrowConverterContext:
+    """Python helper functions for arrow conversions.
+
+    Windows timestamp functions are necessary because Windows cannot handle -ve timestamps.
+    Putting the OS check into the non-windows function would probably take up more CPU cycles then
+    just deciding this at compile time.
+    """
+
+    def __init__(
+        self,
+        timezone: str | None = None,
+        *,
+        timezone_supplier: Callable[[], str | None] | None = None,
+    ) -> None:
+        # An explicit ``timezone`` takes precedence and marks the value resolved.
+        # Otherwise, ``timezone_supplier`` (if any) is invoked lazily on first access.
+        self._tz_value = timezone
+        self._tz_supplier = timezone_supplier if timezone is None else None
+
+    @classmethod
+    def create(cls, connection: Connection | AsyncConnection) -> ArrowConverterContext:
+        """Create a context whose timezone resolves lazily from the session."""
+        return cls(
+            timezone_supplier=lambda: connection._session_parameters._get_string(PARAMETER_TIMEZONE),
+        )
+
+    @property
+    def _timezone(self) -> str | None:
+        """Resolved session timezone, invoking the supplier once on first read.
+
+        Named ``_timezone`` because the C++ table iterator reads this attribute
+        directly via ``PyObject_GetAttrString(context, "_timezone")``.
+        """
+        supplier = self._tz_supplier
+        if supplier is not None:
+            self._tz_value = supplier()
+            self._tz_supplier = None
+        return self._tz_value
+
+    @property
+    def timezone(self) -> str | None:
+        return self._timezone
+
+    @timezone.setter
+    def timezone(self, tz: str | None) -> None:
+        self._tz_value = tz
+        self._tz_supplier = None
+
+    def __getstate__(self) -> dict[str, Any]:
+        # resolve timezone before pickling
+        return {"timezone": self._timezone}
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        self._tz_value = state.get("timezone")
+        self._tz_supplier = None
+
+    def _get_session_tz(self) -> tzinfo:
+        """Get the session timezone or use the local computer's timezone."""
+        try:
+            tz = "UTC" if not self.timezone else str(self.timezone)
+            return pytz.timezone(tz)
+        except pytz.exceptions.UnknownTimeZoneError:
+            logger.warning("converting to tzinfo failed")
+            if not isinstance(tzlocal, MissingOptionalDependency):
+                return tzlocal.get_localzone()  # type: ignore[no-any-return]
+            else:
+                return timezone.utc
+
+    def TIMESTAMP_TZ_to_python(self, epoch: int, microseconds: int, tz: int) -> datetime:
+        tzinfo = _generate_tzinfo_from_tzoffset(tz - 1440)
+        return datetime.fromtimestamp(epoch, tz=tzinfo) + timedelta(microseconds=microseconds)
+
+    def TIMESTAMP_TZ_to_python_windows(self, epoch: int, microseconds: int, tz: int) -> datetime:
+        tzinfo = _generate_tzinfo_from_tzoffset(tz - 1440)
+        t = ZERO_EPOCH + timedelta(seconds=epoch, microseconds=microseconds)
+        if pytz.utc != tzinfo:
+            offset = tzinfo.utcoffset(t)
+            if offset is not None:
+                t += offset
+        return t.replace(tzinfo=tzinfo)
+
+    def TIMESTAMP_NTZ_to_python(self, epoch: int, microseconds: int) -> datetime:
+        return datetime.fromtimestamp(epoch, timezone.utc).replace(tzinfo=None) + timedelta(microseconds=microseconds)
+
+    def TIMESTAMP_NTZ_to_python_windows(self, epoch: int, microseconds: int) -> datetime:
+        return ZERO_EPOCH + timedelta(seconds=epoch, microseconds=microseconds)
+
+    def TIMESTAMP_LTZ_to_python(self, epoch: int, microseconds: int) -> datetime:
+        tzinfo = self._get_session_tz()
+        return datetime.fromtimestamp(epoch, tz=tzinfo) + timedelta(microseconds=microseconds)
+
+    def TIMESTAMP_LTZ_to_python_windows(self, epoch: int, microseconds: int) -> datetime:
+        tzinfo = self._get_session_tz()
+        ts = ZERO_EPOCH + timedelta(seconds=epoch, microseconds=microseconds)
+        return pytz.utc.localize(ts, is_dst=False).astimezone(tzinfo)
+
+    def REAL_to_numpy_float64(self, py_double: float) -> float64:
+        return np.float64(py_double)  # type: ignore[no-any-return]
+
+    def FIXED_to_numpy_int64(self, py_long: int) -> int64:
+        return np.int64(py_long)  # type: ignore[no-any-return]
+
+    def FIXED_to_numpy_float64(self, py_long: int, scale: int) -> float64:
+        return np.float64(decimal.Decimal(py_long).scaleb(-scale))  # type: ignore[no-any-return]
+
+    def DATE_to_numpy_datetime64(self, py_days: int) -> datetime64:
+        return np.datetime64(py_days, "D")  # type: ignore[no-any-return]
+
+    def TIMESTAMP_NTZ_ONE_FIELD_to_numpy_datetime64(self, value: int, scale: int) -> datetime64:
+        nanoseconds = int(decimal.Decimal(value).scaleb(9 - scale))
+        return np.datetime64(nanoseconds, "ns")  # type: ignore[no-any-return]
+
+    def TIMESTAMP_NTZ_TWO_FIELD_to_numpy_datetime64(self, epoch: int, fraction: int) -> datetime64:
+        nanoseconds = int(decimal.Decimal(epoch).scaleb(9) + decimal.Decimal(fraction))
+        return np.datetime64(nanoseconds, "ns")  # type: ignore[no-any-return]
+
+    def DECIMAL128_to_decimal_or_int(self, int128_bytes: bytes, scale: int) -> decimal.Decimal | int:
+        """When scale=0 (integer), returns Python int. When scale>0 (decimal), returns Python Decimal.
+
+        Large scale integers (int128) fall back here as they're not supported by native C++ conversion.
+        """
+        int128 = int.from_bytes(int128_bytes, byteorder=byteorder, signed=True)
+        if scale == 0:
+            return int128
+        digits = [int(digit) for digit in str(int128) if digit != "-"]
+        sign = int128 < 0
+        return decimal.Decimal((sign, digits, -scale))
+
+    def DECFLOAT_to_decimal(self, exponent: int, significand: bytes) -> decimal.Decimal:
+        # significand is two's complement big endian.
+        significand_int = int.from_bytes(significand, byteorder="big", signed=True)
+        return decimal.Decimal(significand_int).scaleb(exponent)
+
+    def DECFLOAT_to_numpy_float64(self, exponent: int, significand: bytes) -> float64:
+        return np.float64(self.DECFLOAT_to_decimal(exponent, significand))  # type: ignore[no-any-return]
+
+    def INTERVAL_YEAR_MONTH_to_str(self, months: int, scale: int) -> str:
+        return interval_year_month_to_string(months, scale)
+
+    def INTERVAL_YEAR_MONTH_to_numpy_timedelta(self, months: int, scale: int) -> timedelta64:
+        if scale == 1:
+            return np.timedelta64(months // 12, "Y")  # type: ignore[no-any-return]
+        return np.timedelta64(months, "M")  # type: ignore[no-any-return]
+
+    def INTERVAL_DAY_TIME_int_to_numpy_timedelta(self, nanos: int) -> timedelta64:
+        return np.timedelta64(nanos, "ns")  # type: ignore[no-any-return]
+
+    def INTERVAL_DAY_TIME_int_to_timedelta(self, nanos: int) -> timedelta:
+        # Python timedelta only supports microsecond precision. We receive value in
+        # nanoseconds.
+        return timedelta(microseconds=nanos // 1000)
+
+    def INTERVAL_DAY_TIME_decimal_to_numpy_timedelta(self, value: bytes) -> timedelta64:
+        # Snowflake supports up to 9 digits leading field precision for the day-time
+        # interval. That when represented in nanoseconds can not be stored in a 64-bit
+        # integer. So we send these as Decimal128 from server to client.
+        # Arrow uses little-endian by default.
+        # https://arrow.apache.org/docs/format/Columnar.html#byte-order-endianness
+        nanos = int.from_bytes(value, byteorder="little", signed=True)
+        # Numpy timedelta only supports up to 64-bit integers, so we need to change the
+        # unit to milliseconds to avoid overflow.
+        # Max value received from server
+        #   = 10**9 * NANOS_PER_DAY - 1
+        #   = 86399999999999999999999 nanoseconds
+        #   = 86399999999999999 milliseconds
+        # math.log2(86399999999999999) = 56.3 < 64
+        return np.timedelta64(nanos // 1_000_000, "ms")  # type: ignore[no-any-return]
+
+    def INTERVAL_DAY_TIME_decimal_to_timedelta(self, value: bytes) -> timedelta:
+        # Snowflake supports up to 9 digits leading field precision for the day-time
+        # interval. That when represented in nanoseconds can not be stored in a 64-bit
+        # integer. So we send these as Decimal128 from server to client.
+        # Arrow uses little-endian by default.
+        # https://arrow.apache.org/docs/format/Columnar.html#byte-order-endianness
+        nanos = int.from_bytes(value, byteorder="little", signed=True)
+        # Python timedelta only supports microsecond precision. We receive value in
+        # nanoseconds.
+        return timedelta(microseconds=nanos // 1000)

snowflake/connector/_internal/arrow_stream_async.py

@@ -0,0 +1,266 @@
+"""Async adapters over the synchronous nanoarrow iterators.
+
+Why every advance goes through ``asyncio.to_thread``
+----------------------------------------------------
+The Arrow stream iterators (:class:`ArrowStreamIterator`,
+the table iterator from :func:`create_table_iterator`) and the helpers in :mod:`arrow_stream_utils`
+expose a purely synchronous API: there is no native async entry point. A single
+``next()`` does two kinds of work, and both are unfriendly to the event loop:
+
+1. **Thread-blocking I/O at chunk boundaries.** Under the hood the core builds a
+   prefetching reader whose ``next()`` calls ``blocking_recv()`` on a channel:
+   it parks the *calling OS thread* until a background task has finished
+   downloading and parsing the next result chunk. The downloads themselves run
+   on the core's own (multi-threaded Tokio) runtime, so they do **not** depend
+   on the Python event loop, but the consuming ``next()`` still blocks its
+   thread waiting for them.
+2. **GIL-bound CPU work.** Decoding a row/batch into Python objects (building
+   tuples/dicts, running the per-column converters) holds the GIL the entire
+   time. Only the chunk-boundary fetch above releases the GIL; the decode does
+   not.
+
+If we called ``next()`` directly inside a coroutine, both of those would run on
+the event-loop thread: chunk-boundary advances would block the loop on network
+I/O, and every decode would hold the GIL, so no other task could make progress.
+This does *not* deadlock (the downloads complete independently on the core
+runtime), but it defeats the point of an async API. Offloading to a worker
+thread via :func:`asyncio.to_thread` keeps the loop free while a blocking
+advance is in flight.
+
+So why offload *every* call rather than just the slow ones? From Python there
+is no reliable way to tell a cheap advance (popping an already-buffered row)
+from an expensive one (a chunk-boundary ``blocking_recv`` or a heavy decode), so
+the uniform, safe choice is to offload them all and accept a thread handoff on
+the cheap ones.
+
+Possible modifications (intentionally not done yet)
+---------------------------------------------------
+The row path pays this hop *per row*: ``__anext__`` / :meth:`fetch_next` offload
+a single ``next()`` each, so a large result set incurs one ``to_thread`` hop
+(and a round of GIL ping-pong) for every row. ``fetch_many`` / ``fetch_all``
+already avoid this by batching many rows into one native call under a single
+hop. Row iteration could be made similarly cheap by backing ``__anext__`` with
+an internal buffer refilled via :meth:`fetch_many` under one hop, instead of one
+hop per row.
+
+Alternatively, if performance tests show the offload is unnecessary for the
+common case (e.g. the loop-blocking cost is negligible in practice), the advance
+could simply be a plain synchronous ``next()`` call with no ``to_thread`` hop at
+all. Left as-is for now; revisit either way if async iteration shows up as a
+bottleneck.
+
+
+This module centralizes those ``to_thread`` hops behind small async wrappers so
+the async cursor and async result batch share one implementation (and one
+place documenting this rationale) instead of repeating
+``await asyncio.to_thread(...)`` at every call site.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from collections.abc import AsyncIterator, Sequence
+from typing import TYPE_CHECKING, Any, Protocol
+
+from snowflake.connector._core import sf_core_python
+
+from .arrow_stream_utils import (
+    _missing_native_class,
+    collect_arrow_table,
+    create_row_iterator,
+)
+
+
+if TYPE_CHECKING:
+    from pyarrow import Table
+
+    from .arrow import ArrowRowIterator, ArrowTableIterator, AsyncArrowRowIterator
+    from .arrow_context import ArrowConverterContext
+    from .cursor.result_metadata import ResultMetadata
+    from .protobuf_gen.database_driver_v1_pb2 import ResultSetHandle
+
+
+# Sentinel handed to ``next(iterator, default)`` so a ``StopIteration`` raised
+# inside a worker thread never has to cross the ``to_thread`` boundary (where it
+# would be wrapped in confusing ways). The caller compares identity against it.
+_ITER_DONE = object()
+
+
+def _next_or_default(iterator: Any, default: object) -> Any:
+    """Typed ``next(iterator, default)`` suitable for :func:`asyncio.to_thread`.
+
+    The builtin ``next`` is overloaded, which mypy refuses to pass directly to
+    ``to_thread``. This thin wrapper gives it a concrete, checkable signature.
+    """
+    return next(iterator, default)
+
+
+class AsyncArrowStreamIterator(AsyncIterator[Any]):
+    """Async facade over a synchronous nanoarrow iterator.
+
+    Wraps an :class:`ArrowRowIterator` (row iterator) or an
+    :class:`ArrowTableIterator` (RecordBatch iterator) and exposes async
+    iteration plus bulk ``fetch_many`` / ``fetch_all`` helpers. Every advance of
+    the underlying iterator runs on a worker thread via :func:`asyncio.to_thread`
+    (see module docstring for why).
+    """
+
+    def __init__(
+        self,
+        iterator: ArrowRowIterator | ArrowTableIterator,
+    ) -> None:
+        self._iterator = iterator
+
+    def __aiter__(self) -> AsyncArrowStreamIterator:
+        return self
+
+    async def __anext__(self) -> Any:
+        item = await asyncio.to_thread(_next_or_default, self._iterator, _ITER_DONE)
+        if item is _ITER_DONE:
+            raise StopAsyncIteration
+        return item
+
+    async def fetch_next(self, default: object = None) -> Any:
+        """Return the next item, or *default* when the stream is exhausted.
+
+        Unlike :meth:`__anext__` this never raises ``StopAsyncIteration``; it
+        is the async analogue of ``next(it, default)`` and is convenient for
+        manual fetch loops (e.g. ``fetchone``).
+        """
+        item = await asyncio.to_thread(_next_or_default, self._iterator, _ITER_DONE)
+        return default if item is _ITER_DONE else item
+
+    async def fetch_many(self, size: int) -> list[Any]:
+        """Fetch up to *size* rows in a single threaded C++ call."""
+        return await asyncio.to_thread(self._iterator.fetch_many, size)  # type: ignore[union-attr]
+
+    async def fetch_all(self) -> list[Any]:
+        """Fetch all remaining rows in a single threaded C++ call."""
+        return await asyncio.to_thread(self._iterator.fetch_all)  # type: ignore[union-attr]
+
+
+class NativeArrowBatchReader(Protocol):
+    """The ``native-arrow`` reader: one awaitable for I/O, the rest synchronous."""
+
+    async def next_batch(self) -> bool: ...
+    def take_row(self, default: object = None) -> Any: ...
+    def convert(self, count: int | None = None) -> int: ...
+    def take_converted(self) -> list[Any]: ...
+
+
+class NativeAsyncArrowRowIterator(AsyncIterator[Any]):
+    """Row iterator over a :class:`NativeArrowBatchReader`.
+
+    Only ``next_batch`` suspends, and it does no Python-object work. Every row
+    is materialized by a synchronous call, so conversion runs on whichever
+    thread drives the coroutine — the event-loop thread — rather than on a
+    core runtime worker.
+    """
+
+    def __init__(self, reader: NativeArrowBatchReader) -> None:
+        self._reader = reader
+
+    def __aiter__(self) -> NativeAsyncArrowRowIterator:
+        return self
+
+    async def __anext__(self) -> Any:
+        row = await self.fetch_next(_ITER_DONE)
+        if row is _ITER_DONE:
+            raise StopAsyncIteration
+        return row
+
+    async def fetch_next(self, default: object = None) -> Any:
+        while True:
+            row = self._reader.take_row(_ITER_DONE)
+            if row is not _ITER_DONE:
+                return row
+            if not await self._reader.next_batch():
+                return default
+
+    async def fetch_many(self, size: int) -> list[Any]:
+        remaining = size
+        while remaining > 0:
+            remaining -= self._reader.convert(remaining)
+            if remaining > 0 and not await self._reader.next_batch():
+                break
+        return self._reader.take_converted()
+
+    async def fetch_all(self) -> list[Any]:
+        while True:
+            self._reader.convert()
+            if not await self._reader.next_batch():
+                return self._reader.take_converted()
+
+
+async def create_async_row_iterator_from_result_set(
+    result_set_handle: ResultSetHandle,
+    *,
+    context: ArrowConverterContext,
+    use_dict_result: bool = False,
+    use_numpy: bool = False,
+) -> AsyncArrowRowIterator:
+    """Yield rows from the live result set; upcoming chunks download in the background."""
+    iterator_cls = getattr(sf_core_python, "AsyncArrowStreamIterator", None)
+    if iterator_cls is None:
+        raise _missing_native_class("AsyncArrowStreamIterator")
+    reader = await iterator_cls.from_result_set(
+        result_set_handle.id,
+        result_set_handle.magic,
+        session_timezone=context.timezone,
+        use_dict_result=use_dict_result,
+        use_numpy=use_numpy,
+    )
+    return NativeAsyncArrowRowIterator(reader)
+
+
+def create_async_row_iterator_from_stream_ptr(
+    stream_ptr: int,
+    *,
+    context: ArrowConverterContext,
+    use_dict_result: bool = False,
+    use_numpy: bool = False,
+    use_core_arrow: bool = False,
+) -> AsyncArrowRowIterator:
+    """Wrap the sync iterator in ``asyncio.to_thread``.
+
+    Used when native-arrow is off, and for ResultBatches that still
+    arrive as a C stream pointer.
+    """
+    return AsyncArrowStreamIterator(
+        create_row_iterator(
+            stream_ptr,
+            context=context,
+            use_dict_result=use_dict_result,
+            use_numpy=use_numpy,
+            use_core_arrow=use_core_arrow,
+        )
+    )
+
+
+async def collect_arrow_table_async(
+    table_iterator: ArrowTableIterator,
+    columns_metadata: Sequence[ResultMetadata] | None = None,
+    force_return_table: bool = False,
+) -> Table | None:
+    """Async wrapper for :func:`collect_arrow_table`.
+
+    Draining *table_iterator* into a single Arrow table runs every blocking
+    ``next()`` plus the final ``Table.from_batches`` on a worker thread.
+    """
+    return await asyncio.to_thread(
+        collect_arrow_table,
+        table_iterator,
+        columns_metadata,
+        force_return_table,
+    )
+
+
+async def to_pandas_async(table: Table, **kwargs: Any) -> Any:
+    """Convert an Arrow table to a pandas DataFrame off the event loop.
+
+    ``Table.to_pandas`` is CPU-heavy C/Cython work with no async entry point, so
+    it is offloaded for the same reason as the fetch path. ``**kwargs`` are
+    forwarded to ``Table.to_pandas`` (e.g. ``split_blocks``, ``self_destruct``).
+    """
+    return await asyncio.to_thread(table.to_pandas, **kwargs)

snowflake/connector/_internal/arrow_stream_iterator.pyi

@@ -0,0 +1,42 @@
+"""Type stubs for the Cython arrow_stream_iterator extension module.
+
+The actual implementation is compiled from
+nanoarrow_cpp/ArrowIterator/arrow_stream_iterator.pyx at wheel-build time.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+class ArrowStreamIterator(Iterator[Any]):
+    """Python wrapper for C++ Arrow stream iterator.
+
+    Reads directly from an ArrowArrayStream pointer.
+    """
+
+    def __init__(
+        self,
+        stream_ptr: int,
+        arrow_context: Any,
+        use_dict_result: bool = False,
+        use_numpy: bool = False,
+    ) -> None: ...
+    def __iter__(self) -> ArrowStreamIterator: ...
+    def __next__(self) -> Any: ...
+    def fetch_many(self, size: int) -> list[Any]: ...
+    def fetch_all(self) -> list[Any]: ...
+
+class ArrowStreamTableIterator(Iterator[Any]):
+    """Iterator that yields one pyarrow RecordBatch per batch with Snowflake type conversions applied."""
+
+    def __init__(
+        self,
+        stream_ptr: int,
+        arrow_context: Any,
+        number_to_decimal: bool = False,
+        force_microsecond_precision: bool = False,
+    ) -> None: ...
+    def __iter__(self) -> ArrowStreamTableIterator: ...
+    def __next__(self) -> Any: ...
+    def get_converted_schema(self) -> Any: ...