Stop throwing an error in an attempt to stop an already failed statement

[James Robinson (jlrobins)]

... stopping already terminal state statements result in a no-op.

Closes #203. More details there in the issue.

[Copilot]

🟢 Approval recommended

The behavior change is narrowly scoped, matches the documented API semantics, and is covered by both unit and integration regression tests.

Pull request overview

This PR fixes Connection.stop_statement(wait_for_stopped=True) so stopping a statement that is already in a terminal phase (specifically FAILED before the stop was requested) is treated as a successful no-op rather than raising OperationalError, aligning the bare-name path with the existing Statement-object short-circuit behavior.

Changes:

• Reorders the terminal-phase vs. failed-phase checks in _wait_for_statement_stopped so an already-terminal FAILED statement returns successfully without polling.
• Adds unit and integration regression tests covering the “already FAILED before stop” scenario and reinforces the “already STOPPED is a no-op” behavior for both name/object paths.
• Updates docstrings and the changelog to document the corrected behavior.

File summaries

File	Description
src/confluent_sql/connection.py	Adjusts _wait_for_statement_stopped to short-circuit on terminal phases (including already-FAILED) before raising on mid-wait transitions to FAILED; expands docstrings to reflect idempotent server behavior.
tests/unit/test_connection_unit.py	Adds a unit regression test ensuring no polling occurs when the stop PATCH response is already FAILED.
tests/integration/test_connection.py	Adds an integration regression test for stopping a statement that fails on its own (SELECT 1/0) and reinforces no-op stopping behavior for already-stopped statements by name.
CHANGELOG.md	Documents the behavioral fix for #203 in the Unreleased “Fixed” section.

Review details

Suppressed comments (1)

src/confluent_sql/connection.py:1363

• The timeout OperationalError message says the statement did not reach STOPPED, but this helper now treats any terminal phase as success; the message should reflect waiting for a terminal phase to avoid misleading callers when a statement completes/gets deleted etc.

        if statement.phase.is_terminal:
            return statement

        for _ in sleep_with_backoff(timeout):
            statement = self.get_statement(statement.name)

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.