Expose query stats through a cursor callback

[hashhar]

Description

Add an optional stats_callback to Connection.cursor() that is invoked with a copy of the query stats every time the client processes a response from the coordinator: once right after the query is submitted (so the query id and initial state are available while the query is still running) and again on every subsequent poll.

This mirrors the progress monitor exposed by the Trino JDBC driver and lets callers log or monitor a query instead of only being able to inspect it after all rows have been fetched.

Non-technical explanation

Expose query stats through a cursor callback. Fixes #578 .

Release notes

( ) This is not user-visible or docs only and no release notes are required.
(x) Release notes are required, please propose a release note for me.
( ) Release notes are required, with the following suggested text:

* Fix some things. ({issue}`issuenumber`)

[hashhar]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@trino/client.py`:
- Around line 1026-1030: Update _report_stats to pass a deep copy of self._stats
to _stats_callback, preventing mutations to nested dictionaries and lists from
affecting internal query state. Add the copy module import if needed, while
preserving the existing callback guard.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5dbd763b-ae94-4537-84e3-823a5b1795f3

📥 Commits

Reviewing files that changed from the base of the PR and between 7b74702 and a1d5e12.

📒 Files selected for processing (4)

• README.md
• tests/integration/test_dbapi_integration.py
• trino/client.py
• trino/dbapi.py

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use a deep copy to prevent mutation of nested query state.

The dictionary self._stats contains deeply nested JSON structures (such as rootStage and operatorSummaries) returned by the Trino coordinator. A shallow dict() copy only protects the top-level keys; if the callback mutates a nested dictionary or list, it will modify the client's internal query state.

To fully enforce the isolation contract promised in the documentation and comments, use a deep copy.

🛡️ Proposed fix to use deepcopy

Make sure to add import copy at the top of the file if it is not already imported.

     def _report_stats(self) -> None:
         if self._stats_callback is not None:
-            # Pass a copy so the callback cannot mutate internal query state.
-            self._stats_callback(dict(self._stats))
+            # Pass a deep copy so the callback cannot mutate internal query state.
+            import copy
+            self._stats_callback(copy.deepcopy(self._stats))

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	def _report_stats(self) -> None:
	if self._stats_callback is not None:
	# Pass a copy so the callback cannot mutate internal query state.
	self._stats_callback(dict(self._stats))
	def _report_stats(self) -> None:
	if self._stats_callback is not None:
	# Pass a deep copy so the callback cannot mutate internal query state.
	import copy
	self._stats_callback(copy.deepcopy(self._stats))

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@trino/client.py` around lines 1026 - 1030, Update _report_stats to pass a
deep copy of self._stats to _stats_callback, preventing mutations to nested
dictionaries and lists from affecting internal query state. Add the copy module
import if needed, while preserving the existing callback guard.