confluent-sql 0.4.0__tar.gz → 0.4.2__tar.gz

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/ARCHITECTURE.md

@@ -45,7 +45,7 @@ Every statement progresses through these phases:
 
 ### How Phases Progress
 
-**Snapshot queries (the default):** _(⚠️ [Early Access](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html))_
+**Snapshot queries (the default):**
 
 ```
 PENDING  → RUNNING → COMPLETED

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this dbapi driver will be documented in this file.
 
+## 0.4.2, 2026-07-17
+
+### Changed
+
+- Snapshot queries on Confluent Cloud Flink SQL are now Generally Available. Removed the Early Access warning previously emitted on first creation of a snapshot-mode cursor, along with the Early Access advisories throughout the documentation (`README.md`, `ARCHITECTURE.md`, `DBAPI_EXTENSIONS.md`, `STREAMING.md`). (#119, #160)
+
+## 0.4.1, 2026-07-07
+
+### Fixed
+
+- Idempotent GET requests (`list_statements()`'s page-fetch loop, `get_statement()`, and result-page fetching) now retry transient transport errors -- connection resets (`httpx.NetworkError`) and servers that close pooled connections without responding (`httpx.RemoteProtocolError`) -- up to 3 times with a short exponential backoff, instead of failing on the first blip. POST/PATCH/DELETE requests (statement submission, `stop_statement()`, `delete_statement()`) are deliberately left unretried, since re-issuing them after a connection reset could double-submit or double-mutate state. (#137)
+- The same idempotent GET requests now also retry transient HTTP response statuses (429, 500, 502, 503, 504), not just transport-level exceptions -- a request that reaches Confluent Cloud but gets a momentarily-overloaded gateway response was previously failing on the first such response instead of being retried like a dropped connection. (#140)
+- Increased the default HTTP timeout from 5 to 10s for safety. `connect()` and `Connection.__init__()` no longer accept explicit `None` for `http_timeout_secs`.
+
 ## 0.4.0, 2026-06-15
 
 ### Added

confluent_sql-0.4.2/CLAUDE.md

@@ -0,0 +1,29 @@
+# Project-specific instructions for confluent-sql
+
+## HTTP request routing: idempotent GETs vs mutating requests
+
+`Connection` exposes two ways to issue an HTTP request (`src/confluent_sql/connection.py`):
+
+- `_request_get(url, **kwargs)` — for idempotent GETs. Forwards `kwargs` (`params`, `headers`,
+  `timeout`, etc.) to `_request`, forcing `method="GET"`, and wraps the whole call in
+  `call_with_retries()` (`src/confluent_sql/retry.py`), which retries both transient transport
+  errors (`httpx.NetworkError`, `httpx.RemoteProtocolError`; #137) and transient HTTP response
+  statuses (429/500/502/503/504, via `DEFAULT_RETRYABLE_STATUS_CODES`; #140) with a short
+  exponential backoff before giving up. Status-code retries are wired in via a private
+  `_RetryableStatusError` sentinel raised inside `_request_get` -- `call_with_retries` itself
+  stays HTTP-agnostic, unchanged from #137.
+- `_request(url, method="GET", ...)` — for everything else, including POST/PATCH/DELETE.
+
+**Every idempotent GET call site must go through `_request_get`, not `_request` directly.**
+Re-issuing a GET after a dropped connection is safe; re-issuing a POST/PATCH/DELETE is not — it
+can double-submit or double-mutate state. When adding a new GET call site (e.g. a future
+`list_connectors()` or similar read-only endpoint), route it through `_request_get`. When adding a
+mutating call site, use `_request` directly and do not wrap it in retry logic.
+
+This distinction was introduced in #137 (see `CHANGELOG.md` 0.4.1) after a reported
+`ECONNRESET` while polling a single statement via `get_statement()`/`_get_statement()`; the same
+PR additionally retries `list_statements()`'s page-fetch loop and result-page fetching, since
+those are equally idempotent GETs even though they weren't the reported failure. #140 extended
+the same call sites to also retry on retryable HTTP status codes, not just transport exceptions.
+The reasoning, and the case for a plain function over a decorator, is captured in `retry.py`'s
+module docstring and `_request_get`'s docstring.

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/DBAPI_EXTENSIONS.md

@@ -4,8 +4,6 @@ The `confluent-sql` driver extends the standard [DB-API v2](https://peps.python.
 
 ## Understanding Snapshot vs Streaming Modes
 
-> **⚠️ Early Access:** [Snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) on Confluent Cloud Flink SQL are currently in Early Access and may be subject to change.
-
 **By default, the driver operates in [SNAPSHOT mode](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html)**, producing behavior very similar to traditional SQL databases:
 
 - Queries execute and block until complete

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confluent-sql
-Version: 0.4.0
+Version: 0.4.2
 Summary: DB-API v2 compliant driver for Confluent Cloud Flink SQL
 Project-URL: Repository, https://github.com/confluentinc/confluent-sql
 Project-URL: Documentation, https://github.com/confluentinc/confluent-sql?tab=readme-ov-file#confluent-sql
@@ -245,7 +245,7 @@ This is pre-production code mainly developed as the lower level portion of a `db
 
 The behavior of snapshot-mode cursors, complying with dbapi semantics, are well stable. The streaming query extensions are more of a work in progress at this time. Feedback and suggestions are welcome!
 
-> **⚠️ Early Access:** [Snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) on Confluent Cloud Flink SQL are currently in Early Access and may be subject to change. You will need to request access to snapshot queries for your organization from Confluent. The driver defaults to snapshot mode for all queries unless streaming mode is explicitly requested.
+The driver defaults to [snapshot mode](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) for all queries unless streaming mode is explicitly requested.
 
 ## Prerequisites
 

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/README.md

@@ -14,7 +14,7 @@ This is pre-production code mainly developed as the lower level portion of a `db
 
 The behavior of snapshot-mode cursors, complying with dbapi semantics, are well stable. The streaming query extensions are more of a work in progress at this time. Feedback and suggestions are welcome!
 
-> **⚠️ Early Access:** [Snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) on Confluent Cloud Flink SQL are currently in Early Access and may be subject to change. You will need to request access to snapshot queries for your organization from Confluent. The driver defaults to snapshot mode for all queries unless streaming mode is explicitly requested.
+The driver defaults to [snapshot mode](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) for all queries unless streaming mode is explicitly requested.
 
 ## Prerequisites
 

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/STREAMING.md

@@ -4,8 +4,6 @@ The `confluent-sql` driver provides full support for continuous streaming querie
 
 ## Overview
 
-> **⚠️ Early Access:** [Snapshot queries](https://docs.confluent.io/cloud/current/flink/concepts/snapshot-queries.html) on Confluent Cloud Flink SQL are currently in Early Access and may be subject to change. The SNAPSHOT mode described below relies on this feature.
-
 This driver supports two primary execution modes:
 
 | Mode                   | Use Case              | Query Examples                  | Result Behavior                                                              |

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "confluent-sql"
-version = "0.4.0"
+version = "0.4.2"
 description = "DB-API v2 compliant driver for Confluent Cloud Flink SQL"
 readme = "README.md"
 requires-python = ">=3.10"

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/src/confluent_sql/connection.py

@@ -29,12 +29,22 @@ from .exceptions import (
 )
 from .execution_mode import ExecutionMode
 from .polling import sleep_with_backoff
+from .retry import (
+    DEFAULT_RETRYABLE_EXCEPTIONS,
+    DEFAULT_RETRYABLE_STATUS_CODES,
+    call_with_retries,
+)
 from .statement import LABEL_PREFIX as STATEMENT_LABEL_PREFIX
 from .statement import ChangelogRow, Statement
 from .types import PropertiesDict, RowPythonTypes
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_HTTP_TIMEOUT_SECS: float = 10.0
+"""Applied to the httpx client whenever a caller doesn't pass http_timeout_secs explicitly,
+so the effective default is ours to control rather than an implicit dependency on httpx's own
+default (5s)."""
+
 
 def _resolve_api_credentials(
     global_api_key: str | None,
@@ -96,7 +106,7 @@ def connect(  # noqa: PLR0913
     dbname: str | None = None,  # deprecated, use database parameter
     result_page_fetch_pause_millis: int = 100,
     http_user_agent: str | None = None,
-    http_timeout_secs: float | None = None,
+    http_timeout_secs: float = DEFAULT_HTTP_TIMEOUT_SECS,
 ) -> Connection:
     """
     Create a connection to a Confluent SQL service.
@@ -146,8 +156,8 @@ def connect(  # noqa: PLR0913
                        "Confluent-SQL-Dbapi/v<version> (https://confluent.io; support@confluent.io)"
                        where version is from __version__.py
         http_timeout_secs: Timeout in seconds for HTTP requests made by the underlying httpx
-                       client. Must be a positive number. If None (default), the httpx default
-                       of 5 seconds applies to connect, read, write, and pool operations.
+                       client. Must be a positive number. Defaults to DEFAULT_HTTP_TIMEOUT_SECS,
+                       applied to connect, read, write, and pool operations.
 
     Returns:
         A Connection object representing the database connection
@@ -205,6 +215,15 @@ def connect(  # noqa: PLR0913
     )
 
 
+class _RetryableStatusError(Exception):
+    """Wraps a response carrying a retryable HTTP status (#140) so call_with_retries' existing
+    exception-based retry loop drives status-code retries too. Never escapes _request_get."""
+
+    def __init__(self, response: httpx.Response):
+        self.response = response
+        super().__init__(f"transient HTTP status {response.status_code}")
+
+
 class Connection:
     """
     A connection to a Confluent SQL service.
@@ -239,15 +258,11 @@ class Connection:
     _database: str | None
     _client: httpx.Client
     _http_user_agent: str
-    _http_timeout_secs: float | None
+    _http_timeout_secs: float
 
     _row_type_registry: RowTypeRegistry
     """Registry for user-defined row types, see register_row_type()."""
 
-    _snapshot_warning_issued: bool
-    """Internal flag to track whether the snapshot query early access warning has been issued.
-        Remove after snapshot queries reach open preview (expected May 2026)."""
-
     def __init__(  # noqa: PLR0913
         self,
         environment_id: str,
@@ -264,7 +279,7 @@ class Connection:
         database: str | None = None,
         statement_results_page_fetch_pause_millis: int = 100,
         http_user_agent: str | None = None,
-        http_timeout_secs: float | None = None,
+        http_timeout_secs: float = DEFAULT_HTTP_TIMEOUT_SECS,
     ):
         """
         Initialize a new connection to a Confluent SQL service.
@@ -303,8 +318,7 @@ class Connection:
                            Defaults to the value of DEFAULT_USER_AGENT, which includes the
                            driver name/version, documentation URL, and support email.
             http_timeout_secs: Timeout in seconds applied to the underlying httpx client.
-                           Must be a positive number. If None (default), the httpx default
-                           of 5 seconds applies.
+                           Must be a positive number. Defaults to DEFAULT_HTTP_TIMEOUT_SECS.
         """
         self.environment_id = environment_id
         # Fold a falsy pool ("" or None) into None so the attribute honestly reports the
@@ -330,20 +344,14 @@ class Connection:
             http_user_agent if http_user_agent is not None else self.DEFAULT_USER_AGENT
         )
 
-        if http_timeout_secs is not None:
-            # Reject bool explicitly: bool is a subclass of int in Python, but a True/False
-            # value here is almost certainly a programming error rather than a valid timeout.
-            if isinstance(http_timeout_secs, bool) or not isinstance(
-                http_timeout_secs, (int, float)
-            ):
-                raise InterfaceError(
-                    f"http_timeout_secs must be a number, "
-                    f"got {type(http_timeout_secs).__name__}"
-                )
-            if http_timeout_secs <= 0:
-                raise InterfaceError(
-                    f"http_timeout_secs must be positive, got {http_timeout_secs}"
-                )
+        # Reject bool explicitly: bool is a subclass of int in Python, but a True/False
+        # value here is almost certainly a programming error rather than a valid timeout.
+        if isinstance(http_timeout_secs, bool) or not isinstance(http_timeout_secs, (int, float)):
+            raise InterfaceError(
+                f"http_timeout_secs must be a number, got {type(http_timeout_secs).__name__}"
+            )
+        if http_timeout_secs <= 0:
+            raise InterfaceError(f"http_timeout_secs must be positive, got {http_timeout_secs}")
         self._http_timeout_secs = http_timeout_secs
 
         if not endpoint and not (cloud_provider and cloud_region):
@@ -377,15 +385,11 @@ class Connection:
                 "User-Agent": self._http_user_agent,
             },
         }
-        if self._http_timeout_secs is not None:
-            client_kwargs["timeout"] = self._http_timeout_secs
+        client_kwargs["timeout"] = self._http_timeout_secs
         self._client = httpx.Client(**client_kwargs)
 
         self._row_type_registry = RowTypeRegistry()
 
-        # TODO: remove after snapshot queries reach open preview (May 2026)
-        self._snapshot_warning_issued = False
-
     def close(self) -> None:
         """
         Close the connection.
@@ -498,15 +502,6 @@ class Connection:
         if self._closed:
             raise InterfaceError("Connection is closed")
 
-        # TODO: remove after snapshot queries reach open preview (May 2026)
-        if mode.is_snapshot and not self._snapshot_warning_issued:
-            self._snapshot_warning_issued = True
-            warnings.warn(
-                "Snapshot queries on Confluent Cloud Flink SQL are currently in "
-                "Early Access and may be subject to change.",
-                stacklevel=2,
-            )
-
         return Cursor(self, as_dict=as_dict, execution_mode=mode)
 
     def streaming_cursor(self, *, as_dict: bool = False) -> Cursor:
@@ -811,7 +806,7 @@ class Connection:
         has_more_pages = True
         next_page_token: str | None = None
         while has_more_pages:
-            response = self._request("/statements", params=parameters)
+            response = self._request_get("/statements", params=parameters)
             resp_json = response.json()
             statements_json = resp_json.get("data", [])
             statements.extend(Statement.from_response(self, s) for s in statements_json)
@@ -1057,10 +1052,10 @@ class Connection:
         return self._closed
 
     @property
-    def http_timeout_secs(self) -> float | None:
+    def http_timeout_secs(self) -> float:
         """
-        Get the configured timeout (in seconds) for HTTP requests, or None if the
-        httpx default (5 seconds) is in effect.
+        Get the effective timeout (in seconds) applied to HTTP requests, which is
+        DEFAULT_HTTP_TIMEOUT_SECS unless a value was supplied at construction time.
         """
         return self._http_timeout_secs
 
@@ -1319,7 +1314,7 @@ class Connection:
             OperationalError: If other API errors occur
         """
         try:
-            return self._request(f"/statements/{statement_name}").json()
+            return self._request_get(f"/statements/{statement_name}").json()
         except OperationalError as e:
             # Check if this is a 404 error
             if e.http_status_code == 404:
@@ -1353,7 +1348,7 @@ class Connection:
             next_url = f"/statements/{statement_name}/results"
 
         try:
-            response = self._request(next_url).json()
+            response = self._request_get(next_url).json()
         except OperationalError as e:
             # Check if this is a 404 error indicating the statement was deleted
             if e.http_status_code == 404:
@@ -1402,16 +1397,43 @@ class Connection:
 
         return (results, next_url)
 
-    def _request(self, url, method="GET", raise_for_status=True, **kwargs) -> httpx.Response:
-        if self._closed:
-            raise InterfaceError("Connection is closed")
+    def _request_get(self, url, **kwargs) -> httpx.Response:
+        """Issue a GET, retrying transient transport errors (#137) and transient HTTP status
+        codes (#140) alike -- both feed the same call_with_retries backoff/attempt budget.
+
+        Only for idempotent GETs -- retrying a call with side effects (POST/PATCH/DELETE) could
+        double-submit or double-mutate state, so those call sites use `_request` directly.
+        Forwards arbitrary kwargs (params, headers, timeout, etc.) to `_request`, forcing
+        `method="GET"` regardless of what's passed, so a call site cannot accidentally opt out of
+        the retry policy just because it needs a kwarg beyond `params`. `raise_for_status` is
+        dropped if present -- this method always manages it internally, since it must inspect
+        the raw response to decide whether to retry before translating a final error.
+        """
+        kwargs["method"] = "GET"
+        kwargs.pop("raise_for_status", None)
 
-        try:
-            response = self._client.request(method, url, **kwargs)
-            logger.debug("Response: %s", response.content)
-            if raise_for_status:
-                response.raise_for_status()
+        def _get_or_flag_retryable_status() -> httpx.Response:
+            response = self._request(url, raise_for_status=False, **kwargs)
+            if response.status_code in DEFAULT_RETRYABLE_STATUS_CODES:
+                raise _RetryableStatusError(response)
             return response
+
+        try:
+            response = call_with_retries(
+                _get_or_flag_retryable_status,
+                exceptions=(*DEFAULT_RETRYABLE_EXCEPTIONS, _RetryableStatusError),
+            )
+        except _RetryableStatusError as e:
+            response = e.response
+
+        self._raise_for_status_as_operational_error(response)
+        return response
+
+    def _raise_for_status_as_operational_error(self, response: httpx.Response) -> None:
+        """Translate a 4xx/5xx response into OperationalError, chaining the original
+        httpx.HTTPStatusError and including any server-provided error detail."""
+        try:
+            response.raise_for_status()
         except httpx.HTTPStatusError as e:
             try:
                 res = e.response.json()
@@ -1425,6 +1447,16 @@ class Connection:
                 http_status_code=e.response.status_code,
             ) from e
 
+    def _request(self, url, method="GET", raise_for_status=True, **kwargs) -> httpx.Response:
+        if self._closed:
+            raise InterfaceError("Connection is closed")
+
+        response = self._client.request(method, url, **kwargs)
+        logger.debug("Response: %s", response.content)
+        if raise_for_status:
+            self._raise_for_status_as_operational_error(response)
+        return response
+
     def _get_next_page_token(self, next_url: str | None) -> str | None:
         """Extract the next page token from the next_url, if present."""
         if next_url is None:

confluent_sql-0.4.2/src/confluent_sql/retry.py

@@ -0,0 +1,82 @@
+"""Retry helper for idempotent, side-effect-free calls.
+
+Centralizes retrying of calls that intermittently fail with transient transport errors, so this
+policy lives in one place rather than being reimplemented at each call site. Only appropriate for
+calls where re-issuing after a partial failure is safe -- retrying a call with side effects (e.g. a
+POST that already reached the server before the response was lost) could double-submit or
+double-mutate state.
+"""
+
+import logging
+import random
+import time
+from collections.abc import Callable
+from typing import TypeVar
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+DEFAULT_RETRYABLE_EXCEPTIONS: tuple[type[BaseException], ...] = (
+    httpx.NetworkError,
+    httpx.RemoteProtocolError,
+)
+"""Transient transport errors worth retrying: connection resets/drops (httpx.NetworkError covers
+ConnectError/ReadError/WriteError/CloseError) and servers that close pooled connections without
+responding (httpx.RemoteProtocolError). httpx.TimeoutException is deliberately excluded --
+retrying a timeout compounds latency (up to (max_retries + 1)x the configured timeout) rather than
+recovering from a blip; pass a custom `exceptions` tuple to opt in."""
+
+DEFAULT_RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+"""HTTP statuses worth retrying on an idempotent GET: 429 (rate limited) and 500/502/503/504
+(gateway/server transients). Consumed by `Connection._request_get`, not by `call_with_retries`
+itself, which has no HTTP-specific knowledge. 408 (Request Timeout) is deliberately excluded --
+same "don't compound latency on a timeout" reasoning as excluding httpx.TimeoutException from
+DEFAULT_RETRYABLE_EXCEPTIONS above. Honoring a Retry-After header on 429/503 is out of scope."""
+
+_RETRY_BASE_DELAY_SECS = 0.1
+"""Delay before the first retry sleep -- tuned for sub-second transient network blips rather than
+the multi-second server-state polling that polling.sleep_with_backoff paces."""
+
+_RETRY_DELAY_GROWTH = 2.0
+"""Multiplier applied to the delay after each retry."""
+
+_RETRY_JITTER_BAND = (0.75, 1.25)
+"""Multiplicative jitter band (+-25%) applied to each sleep to avoid thundering-herd alignment."""
+
+
+def call_with_retries(
+    func: Callable[..., T],
+    *args,
+    max_retries: int = 3,
+    exceptions: tuple[type[BaseException], ...] = DEFAULT_RETRYABLE_EXCEPTIONS,
+    **kwargs,
+) -> T:
+    """Call func(*args, **kwargs), retrying up to max_retries times on the given exceptions.
+
+    Sleeps a short exponential backoff with jitter between attempts and logs one INFO line per
+    retry naming the attempt number. After max_retries retries (max_retries + 1 total attempts),
+    the original exception from the final attempt is re-raised.
+    """
+    delay = _RETRY_BASE_DELAY_SECS
+    attempt = 0
+    while True:
+        try:
+            return func(*args, **kwargs)
+        except exceptions as e:
+            attempt += 1
+            if attempt > max_retries:
+                raise
+            sleep_secs = delay * random.uniform(*_RETRY_JITTER_BAND)
+            logger.info(
+                'Retrying %s after transient error (attempt %d/%d): "%s"; sleeping %.3fs',
+                getattr(func, "__name__", repr(func)),
+                attempt,
+                max_retries,
+                e,
+                sleep_secs,
+            )
+            time.sleep(sleep_secs)
+            delay *= _RETRY_DELAY_GROWTH

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/tests/conftest.py

@@ -7,6 +7,7 @@ from typing import TypeAlias
 import pytest
 
 from confluent_sql import Connection, connect
+from confluent_sql.connection import DEFAULT_HTTP_TIMEOUT_SECS
 
 
 def pytest_runtest_setup(item):
@@ -61,7 +62,7 @@ def connection_factory() -> Generator[ConnectionFactory, None, None]:
         database: str | None = None,
         result_page_fetch_pause_millis: int = 100,
         http_user_agent: str | None = None,
-        http_timeout_secs: float | None = None,
+        http_timeout_secs: float = DEFAULT_HTTP_TIMEOUT_SECS,
         endpoint: str | None = None,
     ) -> Connection:
         if global_api_key is None:

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/tests/integration/test_connection.py

@@ -8,6 +8,7 @@ Credentials must be provided via environment variables.
 import os
 import time
 
+import httpx
 import pytest
 
 import confluent_sql
@@ -273,6 +274,49 @@ class TestConnection:
         assert exc_info.value.statement_name == "non-existent-statement-name"
 
 
+@pytest.mark.integration
+class TestRetryOnTransientResultFetchErrors:
+    """Integration coverage for #137's retry-on-idempotent-GET behavior."""
+
+    def test_result_fetch_retries_past_simulated_econnresets_then_hits_confluent_cloud_for_real(
+        self, connection: Connection, mocker
+    ):
+        """Simulates two ECONNRESET-style drops on the results-fetch GET, then lets the third
+        attempt travel all the way through to Confluent Cloud for real.
+
+        NOTE: this is largely redundant with the fully-mocked coverage in
+        tests/unit/test_retry_unit.py and TestConnectionRetriesIdempotentGets
+        (tests/unit/test_connection_unit.py) -- those already prove call_with_retries' counting,
+        backoff, and exception-filtering, and that Connection wires it into
+        _get_statement_results correctly. It's written anyway, against a real environment, in
+        the spirit of treating #137 as a release-branch bugfix: showing the retry survives an
+        actual round trip is worth the extra network call, not just asserting it in the abstract.
+        """
+        with connection.closing_cursor() as cursor:
+            cursor.execute("SELECT 1 as answer FROM `INFORMATION_SCHEMA`.`TABLES`")
+
+            # Capture the real bound method before patching so the third call can still reach
+            # Confluent Cloud for real.
+            real_request = connection._client.request
+            call_count = 0
+
+            def flaky_then_real_request(*args, **kwargs):
+                nonlocal call_count
+                call_count += 1
+                if call_count <= 2:
+                    raise httpx.ReadError("[Errno 54] Connection reset by peer")
+                return real_request(*args, **kwargs)
+
+            request_mock = mocker.patch.object(
+                connection._client, "request", side_effect=flaky_then_real_request
+            )
+
+            row = cursor.fetchone()
+
+            assert row == (1,)
+            assert request_mock.call_count == 3
+
+
 @pytest.mark.integration
 class TestStopStatement:
     """Integration tests for stop_statement against a real environment."""

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/tests/unit/conftest.py

@@ -239,7 +239,6 @@ def mock_connection_factory(mocker, statement_response_factory) -> MockConnectio
         mock_conn.closing_cursor = types.MethodType(Connection.closing_cursor, mock_conn)
 
         mock_conn._row_type_registry = RowTypeRegistry()
-        mock_conn._snapshot_warning_issued = False
 
         return mock_conn
 

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/tests/unit/test_connection_unit.py

@@ -11,6 +11,7 @@ import pytest
 from confluent_sql import InterfaceError, OperationalError, StatementNotFoundError
 from confluent_sql.__version__ import VERSION
 from confluent_sql.connection import (
+    DEFAULT_HTTP_TIMEOUT_SECS,
     Connection,
     RowTypeRegistry,
     _resolve_api_credentials,
@@ -1561,6 +1562,317 @@ class TestGetStatement:
         logger_info_spy.assert_called_with("Getting statement 'log-test-statement'")
 
 
+@pytest.mark.unit
+class TestConnectionRetriesIdempotentGets:
+    """Tests that idempotent GET paths retry transient transport errors (#137), while
+    mutating (POST/PATCH/DELETE) paths deliberately do not."""
+
+    def test_list_statements_retries_and_succeeds(
+        self,
+        invalid_credential_connection: Connection,
+        statement_response_factory: StatementResponseFactory,
+        mocker,
+    ):
+        mocker.patch("confluent_sql.retry.time.sleep")
+        mock_response = Mock()
+        mock_response.json.return_value = {
+            "data": [statement_response_factory(name="stmt-1")],
+            "metadata": {},
+        }
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[httpx.ReadError("reset"), mock_response],
+        )
+
+        statements = invalid_credential_connection.list_statements()
+
+        assert [s.name for s in statements] == ["stmt-1"]
+        assert request_mock.call_count == 2
+
+    def test_get_statement_retries_and_succeeds(
+        self,
+        invalid_credential_connection: Connection,
+        statement_response_factory: StatementResponseFactory,
+        mocker,
+    ):
+        mocker.patch("confluent_sql.retry.time.sleep")
+        mock_response = Mock()
+        mock_response.json.return_value = statement_response_factory(name="stmt-1")
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[httpx.ReadError("reset"), mock_response],
+        )
+
+        result = invalid_credential_connection._get_statement("stmt-1")
+
+        assert result["name"] == "stmt-1"
+        assert request_mock.call_count == 2
+
+    def test_get_statement_results_retries_and_succeeds(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        mocker.patch("confluent_sql.retry.time.sleep")
+        mock_response = Mock()
+        mock_response.json.return_value = {
+            "results": {"data": [{"row": ["v1"]}]},
+            "metadata": {},
+        }
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[httpx.ReadError("reset"), mock_response],
+        )
+
+        results, next_url = invalid_credential_connection._get_statement_results("stmt-1", None)
+
+        assert [r.row for r in results] == [["v1"]]
+        assert next_url is None
+        assert request_mock.call_count == 2
+
+    def test_idempotent_get_reraises_original_exception_after_exhausting_retries(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        """Documents today's unwrapped-transport-error behavior (tracked as #138): after retries
+        are exhausted, the raw httpx exception propagates rather than an OperationalError."""
+        mocker.patch("confluent_sql.retry.time.sleep")
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[httpx.ReadError("reset")] * 4,
+        )
+
+        with pytest.raises(httpx.ReadError):
+            invalid_credential_connection._get_statement("stmt-1")
+
+        assert request_mock.call_count == 4
+
+    def test_non_idempotent_path_does_not_retry_on_transient_error(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        """delete_statement's DELETE must not be retried: retrying a mutating call after a
+        connection reset could double-mutate state, which is exactly what #137 scopes retries
+        away from."""
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=httpx.ReadError("reset"),
+        )
+
+        with pytest.raises(httpx.ReadError):
+            invalid_credential_connection.delete_statement("stmt-1")
+
+        request_mock.assert_called_once()
+
+    def test_list_statements_retries_on_retryable_status_and_succeeds(
+        self,
+        invalid_credential_connection: Connection,
+        statement_response_factory: StatementResponseFactory,
+        mocker,
+    ):
+        mocker.patch("confluent_sql.retry.time.sleep")
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "data": [statement_response_factory(name="stmt-1")],
+            "metadata": {},
+        }
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[_http_error_response(503), mock_response],
+        )
+
+        statements = invalid_credential_connection.list_statements()
+
+        assert [s.name for s in statements] == ["stmt-1"]
+        assert request_mock.call_count == 2
+
+    def test_get_statement_retries_on_retryable_status_and_succeeds(
+        self,
+        invalid_credential_connection: Connection,
+        statement_response_factory: StatementResponseFactory,
+        mocker,
+    ):
+        mocker.patch("confluent_sql.retry.time.sleep")
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = statement_response_factory(name="stmt-1")
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[_http_error_response(503), mock_response],
+        )
+
+        result = invalid_credential_connection._get_statement("stmt-1")
+
+        assert result["name"] == "stmt-1"
+        assert request_mock.call_count == 2
+
+    def test_get_statement_results_retries_on_retryable_status_and_succeeds(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        mocker.patch("confluent_sql.retry.time.sleep")
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "results": {"data": [{"row": ["v1"]}]},
+            "metadata": {},
+        }
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[_http_error_response(503), mock_response],
+        )
+
+        results, next_url = invalid_credential_connection._get_statement_results("stmt-1", None)
+
+        assert [r.row for r in results] == [["v1"]]
+        assert next_url is None
+        assert request_mock.call_count == 2
+
+    def test_idempotent_get_raises_operational_error_after_exhausting_status_retries(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        """Unlike #137's transport-exception exhaustion (which leaks the raw httpx exception,
+        tracked as #138), a persistently-retryable status IS translated to OperationalError --
+        _raise_for_status_as_operational_error runs on the final response either way."""
+        mocker.patch("confluent_sql.retry.time.sleep")
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[_http_error_response(503)] * 4,
+        )
+
+        with pytest.raises(OperationalError) as exc_info:
+            invalid_credential_connection._get_statement("stmt-1")
+
+        assert exc_info.value.http_status_code == 503
+        assert request_mock.call_count == 4
+
+    def test_get_statement_does_not_retry_non_retryable_status(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        """A 404 must not be treated as retryable -- it's the caller's job to see
+        StatementNotFoundError on the very first response, not after a wasted retry budget."""
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            return_value=_http_error_response(404),
+        )
+
+        with pytest.raises(StatementNotFoundError):
+            invalid_credential_connection._get_statement("stmt-1")
+
+        request_mock.assert_called_once()
+
+    def test_get_statement_retries_share_budget_across_transient_error_and_status(
+        self,
+        invalid_credential_connection: Connection,
+        statement_response_factory: StatementResponseFactory,
+        mocker,
+    ):
+        """A transport exception and a retryable status draw from the same attempt/backoff
+        budget -- proof that #140's status-code retries reuse #137's call_with_retries loop
+        rather than adding a second, independent retry mechanism."""
+        mocker.patch("confluent_sql.retry.time.sleep")
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = statement_response_factory(name="stmt-1")
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            side_effect=[httpx.ReadError("reset"), _http_error_response(503), mock_response],
+        )
+
+        result = invalid_credential_connection._get_statement("stmt-1")
+
+        assert result["name"] == "stmt-1"
+        assert request_mock.call_count == 3
+
+    def test_delete_statement_does_not_retry_on_retryable_status(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        """delete_statement's DELETE must not be retried on a retryable status either -- #140's
+        status-code check must live in _request_get, not leak into _request itself."""
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client,
+            "request",
+            return_value=_http_error_response(503),
+        )
+
+        with pytest.raises(OperationalError, match="Error deleting statement"):
+            invalid_credential_connection.delete_statement("stmt-1")
+
+        request_mock.assert_called_once()
+
+    def test_request_get_forwards_arbitrary_kwargs_to_request(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        """A future GET call site needing e.g. headers/timeout must not have to bypass
+        _request_get (and thus the retry policy) just because _request_get only knew about
+        `params`."""
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client, "request", return_value=Mock()
+        )
+
+        invalid_credential_connection._request_get(
+            "/statements", headers={"X-Test": "1"}, timeout=5
+        )
+
+        request_mock.assert_called_once_with(
+            "GET", "/statements", headers={"X-Test": "1"}, timeout=5
+        )
+
+    def test_request_get_forces_get_method_even_if_caller_passes_method(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        """_request_get must never issue anything but a GET, even if a caller mistakenly
+        passes a method= kwarg -- that guarantee is what makes it safe to retry."""
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client, "request", return_value=Mock()
+        )
+
+        invalid_credential_connection._request_get("/statements", method="POST")
+
+        request_mock.assert_called_once_with("GET", "/statements")
+
+    def test_request_get_drops_caller_supplied_raise_for_status_kwarg(
+        self,
+        invalid_credential_connection: Connection,
+        mocker,
+    ):
+        """_request_get always manages raise_for_status itself (it must see the raw response
+        to decide whether to retry before translating it) -- a caller passing raise_for_status
+        in kwargs must not collide with that and blow up with a duplicate-keyword TypeError."""
+        request_mock = mocker.patch.object(
+            invalid_credential_connection._client, "request", return_value=Mock()
+        )
+
+        invalid_credential_connection._request_get("/statements", raise_for_status=True)
+
+        request_mock.assert_called_once_with("GET", "/statements")
+
+
 @pytest.mark.unit
 class TestExecuteStatement:
     """Tests for _execute_statement method."""
@@ -2104,13 +2416,18 @@ class TestHttpUserAgentProperty:
 class TestHttpTimeoutSecs:
     """Tests for the http_timeout_secs constructor parameter and property."""
 
-    def test_default_is_none_and_httpx_default_applies(
+    def test_default_reports_confluent_sql_default(
         self, invalid_credential_connection: Connection
     ):
-        """When not provided, the property is None and the httpx default (5s) is used."""
-        assert invalid_credential_connection.http_timeout_secs is None
-        # httpx's default Timeout(timeout=5.0) is wrapped in a Timeout object on the client.
-        assert invalid_credential_connection._client.timeout == httpx.Timeout(5.0)
+        """When not provided, the property reports the effective default, not None."""
+        assert invalid_credential_connection.http_timeout_secs == DEFAULT_HTTP_TIMEOUT_SECS
+        assert invalid_credential_connection._client.timeout == httpx.Timeout(
+            DEFAULT_HTTP_TIMEOUT_SECS
+        )
+
+    def test_default_http_timeout_secs_is_ten_seconds(self):
+        """Pin the exact default value so a silent change here doesn't slip by unnoticed."""
+        assert DEFAULT_HTTP_TIMEOUT_SECS == 10.0
 
     @pytest.mark.parametrize("timeout_value", [0.5, 1, 10, 30.0, 120])
     def test_custom_timeout_via_constructor(

{confluent_sql-0.4.0 → confluent_sql-0.4.2}/tests/unit/test_cursor_unit.py

@@ -1,6 +1,5 @@
 import re
 import types
-import warnings
 
 import pytest
 
@@ -1673,63 +1672,6 @@ class TestMayHaveResults:
         assert mock_connection_cursor.may_have_results is True
 
 
-@pytest.mark.unit
-class TestSnapshotWarning:
-    """Tests for the early access warning emitted when creating snapshot mode cursors."""
-
-    def test_snapshot_warning_emitted_once_per_connection(self, mock_connection_factory):
-        """Verify that snapshot mode warning is emitted exactly once per connection."""
-        mock_connection = mock_connection_factory(None, None)
-
-        # First snapshot cursor should emit the warning
-        with pytest.warns(
-            UserWarning,
-            match="Snapshot queries on Confluent Cloud Flink SQL are currently in Early Access",
-        ):
-            cursor1 = mock_connection.cursor(mode=ExecutionMode.SNAPSHOT)
-
-        # Flag should now be set
-        assert mock_connection._snapshot_warning_issued is True
-
-        # Second snapshot cursor should NOT emit warning
-        with warnings.catch_warnings(record=True) as warning_list:
-            warnings.simplefilter("always")
-            cursor2 = mock_connection.cursor(mode=ExecutionMode.SNAPSHOT)
-
-        # Filter to only UserWarnings about snapshot
-        snapshot_warnings = [
-            w for w in warning_list
-            if issubclass(w.category, UserWarning)
-            and "Snapshot queries" in str(w.message)
-        ]
-        assert len(snapshot_warnings) == 0
-
-        cursor1.close()
-        cursor2.close()
-
-    def test_snapshot_warning_not_emitted_for_streaming_query_cursor(self, mock_connection_factory):
-        """Verify that warning is not emitted for streaming query cursors."""
-        mock_connection = mock_connection_factory(None, None)
-
-        # Streaming query cursor should not emit warning
-        with warnings.catch_warnings(record=True) as warning_list:
-            warnings.simplefilter("always")
-            cursor = mock_connection.cursor(mode=ExecutionMode.STREAMING_QUERY)
-
-        # Filter to only UserWarnings about snapshot
-        snapshot_warnings = [
-            w for w in warning_list
-            if issubclass(w.category, UserWarning)
-            and "Snapshot queries" in str(w.message)
-        ]
-        assert len(snapshot_warnings) == 0
-
-        # Flag should still be False
-        assert mock_connection._snapshot_warning_issued is False
-
-        cursor.close()
-
-
 @pytest.mark.unit
 class TestComputePoolIdParameter:
     """Test the compute_pool_id parameter for Cursor.execute() and related methods."""

confluent_sql-0.4.2/tests/unit/test_retry_unit.py

@@ -0,0 +1,155 @@
+import logging
+from unittest.mock import Mock
+
+import httpx
+import pytest
+
+from confluent_sql import retry
+from confluent_sql.retry import (
+    DEFAULT_RETRYABLE_EXCEPTIONS,
+    DEFAULT_RETRYABLE_STATUS_CODES,
+    call_with_retries,
+)
+
+
+@pytest.fixture()
+def no_sleep(mocker):
+    """Patch away real sleeping so retry tests run instantly, while still letting call counts and
+    sleep durations be asserted."""
+    return mocker.patch.object(retry.time, "sleep")
+
+
+@pytest.fixture()
+def no_jitter(mocker):
+    """Pin jitter to 1.0 so sleep durations are deterministic."""
+    return mocker.patch.object(retry.random, "uniform", return_value=1.0)
+
+
+@pytest.mark.unit
+class TestCallWithRetries:
+    def test_succeeds_without_retrying(self, no_sleep):
+        func = Mock(return_value="ok")
+
+        result = call_with_retries(func, "a", b="c")
+
+        assert result == "ok"
+        func.assert_called_once_with("a", b="c")
+        no_sleep.assert_not_called()
+
+    def test_retries_and_eventually_succeeds(self, no_sleep, no_jitter):
+        func = Mock(
+            side_effect=[
+                httpx.ReadError("boom"),
+                httpx.ReadError("boom again"),
+                "ok",
+            ]
+        )
+
+        result = call_with_retries(func, "a", b="c")
+
+        assert result == "ok"
+        assert func.call_count == 3
+        for call in func.call_args_list:
+            assert call.args == ("a",)
+            assert call.kwargs == {"b": "c"}
+
+    def test_exhausts_retries_and_reraises_original_exception(self, no_sleep, no_jitter):
+        original = httpx.ReadError("boom")
+        func = Mock(side_effect=[original, httpx.ReadError("2"), httpx.ReadError("3"), original])
+
+        with pytest.raises(httpx.ReadError) as exc_info:
+            call_with_retries(func, max_retries=3)
+
+        assert exc_info.value is original
+        assert func.call_count == 4
+
+    def test_logs_one_info_record_per_retry_naming_attempt_number_and_exception_message(
+        self, no_sleep, no_jitter, caplog
+    ):
+        func = Mock(
+            side_effect=[
+                httpx.ReadError("Connection reset by peer"),
+                httpx.RemoteProtocolError("Server disconnected without sending a response"),
+                "ok",
+            ]
+        )
+
+        with caplog.at_level(logging.INFO, logger=retry.logger.name):
+            call_with_retries(func, max_retries=3)
+
+        info_records = [r for r in caplog.records if r.levelno == logging.INFO]
+        assert len(info_records) == 2
+        assert "attempt 1/3" in info_records[0].message
+        assert '"Connection reset by peer"' in info_records[0].message
+        assert "attempt 2/3" in info_records[1].message
+        assert '"Server disconnected without sending a response"' in info_records[1].message
+
+    def test_non_retryable_exception_propagates_without_retry(self, no_sleep):
+        func = Mock(side_effect=ValueError("not retryable"))
+
+        with pytest.raises(ValueError, match="not retryable"):
+            call_with_retries(func)
+
+        func.assert_called_once()
+        no_sleep.assert_not_called()
+
+    def test_max_retries_zero_means_single_call_and_immediate_reraise(self, no_sleep):
+        func = Mock(side_effect=httpx.ReadError("boom"))
+
+        with pytest.raises(httpx.ReadError):
+            call_with_retries(func, max_retries=0)
+
+        func.assert_called_once()
+        no_sleep.assert_not_called()
+
+    def test_custom_exceptions_tuple_overrides_default_set(self, no_sleep, no_jitter):
+        func = Mock(side_effect=[ValueError("custom"), "ok"])
+
+        result = call_with_retries(func, exceptions=(ValueError,))
+
+        assert result == "ok"
+        assert func.call_count == 2
+
+    def test_backoff_grows_and_is_jittered(self, mocker, no_sleep):
+        uniform = mocker.patch.object(retry.random, "uniform", side_effect=[1.0, 0.75, 1.25])
+        func = Mock(
+            side_effect=[
+                httpx.ReadError("1"),
+                httpx.ReadError("2"),
+                httpx.ReadError("3"),
+                "ok",
+            ]
+        )
+
+        call_with_retries(func, max_retries=3)
+
+        slept = [call.args[0] for call in no_sleep.call_args_list]
+        assert len(slept) == 3
+        # Each successive base delay grows; jitter draws (1.0, 0.75, 1.25) scale it further.
+        assert slept[0] < slept[1] < slept[2]
+        assert uniform.call_count == 3
+
+    def test_default_retryable_exceptions(self):
+        assert httpx.NetworkError in DEFAULT_RETRYABLE_EXCEPTIONS
+        assert httpx.RemoteProtocolError in DEFAULT_RETRYABLE_EXCEPTIONS
+        assert httpx.TimeoutException not in DEFAULT_RETRYABLE_EXCEPTIONS
+
+    def test_default_exceptions_do_not_retry_timeout(self, no_sleep):
+        """Tuple membership alone (test_default_retryable_exceptions above) doesn't prove
+        httpx.TimeoutException is never retried -- it would still be caught if it were a
+        subclass of one of the default exceptions. Assert the actual behavior instead: a timeout
+        propagates on the first call, with no retry and no sleep."""
+        func = Mock(side_effect=httpx.TimeoutException("timed out"))
+
+        with pytest.raises(httpx.TimeoutException):
+            call_with_retries(func)
+
+        func.assert_called_once()
+        no_sleep.assert_not_called()
+
+    def test_default_retryable_status_codes(self):
+        assert frozenset({429, 500, 502, 503, 504}) == DEFAULT_RETRYABLE_STATUS_CODES
+        assert 408 not in DEFAULT_RETRYABLE_STATUS_CODES
+        assert 200 not in DEFAULT_RETRYABLE_STATUS_CODES
+        assert 404 not in DEFAULT_RETRYABLE_STATUS_CODES
+        assert 400 not in DEFAULT_RETRYABLE_STATUS_CODES