confluent-sql 0.5.2__tar.gz → 0.5.3__tar.gz

{confluent_sql-0.5.2 → confluent_sql-0.5.3}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this dbapi driver will be documented in this file.
 
+## 0.5.3, 2026-08-27
+
+### Fixed
+
+- `Statement.from_response()` no longer raises `OperationalError` for a `PENDING` statement with no `status.traits`, which can possibly happen. (#194)
+
 ## 0.5.2, 2026-08-26
 
 ### Fixed

{confluent_sql-0.5.2 → confluent_sql-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: confluent-sql
-Version: 0.5.2
+Version: 0.5.3
 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

{confluent_sql-0.5.2 → confluent_sql-0.5.3}/pyproject.toml

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

{confluent_sql-0.5.2 → confluent_sql-0.5.3}/src/confluent_sql/cursor.py

@@ -259,8 +259,9 @@ class Cursor:
 
         if self._statement.is_failed:
             raise OperationalError(
-                f"Statement submission failed: {self._statement.status.get('detail', '')}"
-            )  # pragma: no cover
+                f"Statement '{self._statement.name}' submission failed:"
+                f" {self._statement.status.get('detail', '')}"
+            )
 
         # ... and wait for it to be "ready" (either in a terminal state or running) based on
         # execution mode and statement type.

{confluent_sql-0.5.2 → confluent_sql-0.5.3}/src/confluent_sql/statement.py

@@ -243,6 +243,12 @@ class Statement:
         if self.phase.is_terminal:
             return True
 
+        # Traits aren't sent on the initial PENDING response (see #194) -- without them, the
+        # trait-dependent checks below (is_pure_ddl, is_bounded, is_append_only) can't run yet,
+        # and a non-terminal statement with no traits can't be ready to fetch results anyway.
+        if self.traits is None:
+            return False
+
         if execution_mode.is_streaming:
             # In streaming mode, readiness depends on statement type.
             if self.is_pure_ddl:
@@ -513,8 +519,9 @@ class Statement:
                 else None
             )
 
-            # Defensive check: non-failed statements should have traits
-            if traits is None and phase != Phase.FAILED:
+            # Defensive check: non-failed, non-pending statements should have traits. FAILED
+            # statements never get traits, and PENDING may or may not have traits. (see #194).
+            if traits is None and phase not in (Phase.FAILED, Phase.PENDING):
                 raise OperationalError(
                     f"Received statement '{name}' in phase {phase} without traits. "
                     "This is unexpected and likely indicates a server API change or bug."

{confluent_sql-0.5.2 → confluent_sql-0.5.3}/tests/unit/test_cursor_unit.py

@@ -13,7 +13,7 @@ from confluent_sql.exceptions import (
 )
 from confluent_sql.execution_mode import ExecutionMode
 from confluent_sql.result_readers import ChangelogEventReader, ChangeloggedRow, FetchMetrics
-from confluent_sql.statement import ChangelogRow, Op, Statement
+from confluent_sql.statement import ChangelogRow, Op, Phase, Statement
 from tests.unit.conftest import (
     CursorWithStatementFactory,
     MockConnectionFactory,
@@ -94,6 +94,33 @@ class TestExecute:
         # non-append-only statements.
         assert isinstance(mock_connection_cursor._result_reader, ChangelogEventReader)
 
+    def test_execute_raises_with_actual_statement_name_on_immediate_submission_failure(
+        self,
+        mock_connection_cursor: Cursor,
+        statement_response_factory: StatementResponseFactory,
+    ):
+        """Prove that when the *submission* response (not a later poll) already reports FAILED,
+        the raised OperationalError names the statement per the parsed response -- not the
+        caller's statement_name argument, which is None on the common path where the caller lets
+        the server generate a name. Regression test for the bug Copilot's review of #195 caught:
+        interpolating the (usually None) statement_name parameter instead of
+        self._statement.name."""
+        failed_submission = statement_response_factory(
+            phase="FAILED",
+            status_detail="Invalid SQL syntax",
+            name="dbapi-server-generated-name",
+        )
+        mock_connection_cursor._connection._execute_statement.return_value = (  # type: ignore
+            failed_submission
+        )
+
+        with pytest.raises(
+            OperationalError,
+            match=r"Statement 'dbapi-server-generated-name' submission failed: Invalid SQL syntax",
+        ):
+            # statement_name intentionally omitted, as most callers do -- the server assigns one.
+            mock_connection_cursor.execute("SELECT 1 AS col")
+
     def test_execute_calls_raise_if_statement_is_broken_for_failed_statement(
         self,
         mock_connection_cursor: Cursor,
@@ -253,6 +280,53 @@ class TestExecute:
 
         backoff.assert_called_once_with(30, started_at=0.0)
 
+    def test_becomes_ready_after_pending_without_traits_then_running_with_traits(
+        self,
+        mock_connection_cursor: Cursor,
+        statement_response_factory: StatementResponseFactory,
+        mocker,
+    ):
+        """End-to-end lifecycle for #194: a statement is submitted PENDING with no traits (the
+        documented shape of Confluent Cloud's initial response), stays PENDING with no traits for
+        two more polls, then transitions to RUNNING with traits -- at which point execute() must
+        return instead of raising or timing out."""
+        pending_no_traits = statement_response_factory(phase="PENDING")
+        pending_no_traits["status"]["traits"] = None
+
+        running_with_traits = statement_response_factory(
+            sql_statement="SELECT * FROM source_table",
+            sql_kind="SELECT",
+            phase="RUNNING",
+            is_bounded=True,
+            is_append_only=True,
+        )
+
+        mock_connection_cursor._execution_mode = ExecutionMode.STREAMING_QUERY
+
+        # The initial submission (POST) response.
+        mock_connection_cursor._connection._execute_statement.return_value = (  # type: ignore
+            pending_no_traits
+        )
+        # Subsequent polls (GET): two more PENDING-without-traits observations, then RUNNING
+        # with traits on the third.
+        mock_connection_cursor._connection._get_statement.side_effect = (  # type: ignore
+            [pending_no_traits, pending_no_traits, running_with_traits]
+        )
+
+        mocker.patch("time.sleep", return_value=None)
+        start_time = 1000000.0
+        time_mock = mocker.patch(
+            "time.monotonic", side_effect=lambda: start_time + time_mock.call_count
+        )
+
+        mock_connection_cursor.execute("SELECT * FROM source_table")
+
+        assert mock_connection_cursor._connection._get_statement.call_count == 3  # type: ignore
+        assert mock_connection_cursor._statement is not None
+        assert mock_connection_cursor._statement.phase is Phase.RUNNING
+        assert mock_connection_cursor._statement.traits is not None
+        assert mock_connection_cursor._statement.can_fetch_results(ExecutionMode.STREAMING_QUERY)
+
     @pytest.mark.parametrize(
         "streaming_mode",
         [ExecutionMode.STREAMING_QUERY, ExecutionMode.STREAMING_DDL],

{confluent_sql-0.5.2 → confluent_sql-0.5.3}/tests/unit/test_statement_unit.py

@@ -617,6 +617,22 @@ class TestStatementFromResponse:
         ):
             Statement.from_response(mock_connection, response)
 
+    def test_allows_pending_statement_without_traits(
+        self, mock_connection: Connection, statement_response_factory: StatementResponseFactory
+    ):
+        """Test that from_response accepts a PENDING statement without traits.
+
+        Confluent Cloud's documented initial response to a statement submission is a PENDING
+        phase with no status.traits at all -- see #194. Traits only become available once the
+        statement has been polled at least once.
+        """
+        response = statement_response_factory(phase="PENDING")
+        response["status"]["traits"] = None
+
+        statement = Statement.from_response(mock_connection, response)
+        assert statement.traits is None
+        assert statement.phase == Phase.PENDING
+
     def test_parses_row_result_schema(
         self, mock_connection: Connection, statement_response_factory: StatementResponseFactory
     ):
@@ -1110,3 +1126,22 @@ class TestStatementCanFetchResults:
         )
         statement = Statement.from_response(mock_connection, statement_json)
         assert statement.can_fetch_results(ExecutionMode.STREAMING_DDL)
+
+    @pytest.mark.parametrize(
+        "execution_mode",
+        [ExecutionMode.SNAPSHOT, ExecutionMode.STREAMING_QUERY, ExecutionMode.STREAMING_DDL],
+    )
+    def test_pending_without_traits_not_ready(
+        self,
+        mock_connection: Connection,
+        statement_response_factory: StatementResponseFactory,
+        execution_mode: ExecutionMode,
+    ):
+        """A freshly-submitted PENDING statement has no traits yet (see #194) -- it must be
+        reported as not-yet-ready rather than raising while probing trait-dependent properties
+        like is_pure_ddl."""
+        response = statement_response_factory(phase="PENDING")
+        response["status"]["traits"] = None
+
+        statement = Statement.from_response(mock_connection, response)
+        assert not statement.can_fetch_results(execution_mode)

{confluent_sql-0.5.2 → confluent_sql-0.5.3}/uv.lock

@@ -36,7 +36,7 @@ wheels = [
 
 [[package]]
 name = "confluent-sql"
-version = "0.5.2"
+version = "0.5.3"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },