Add first-class coroutine PyCoreAsyncCursor to mssql-py-core

[Saurabh Singh (saurabh500)]

Summary

Adds PyCoreAsyncCursor, a genuine asyncio coroutine cursor for mssql-py-core, built on pyo3-async-runtimes future_into_py. This is a correctness/architecture change (a real non-blocking coroutine cursor), not a performance win.

execute / fetchone / fetchmany / fetchall / close each return a Python awaitable. The TDS I/O is driven on the connection's own tokio runtime and the coroutine .awaits the resulting join handle — there is no block_on on the coroutine path. The !Send client is checked out of the shared cell and the guard is dropped before .await, so the Python event loop stays free while a fetch is in flight.

Strictly additive

• The default PyCoreCursor (conn.cursor()) and the opt-in sync PyCoreSyncCursor (conn.sync_cursor()) are byte-identical to their prior form — cursor.rs and sync_cursor.rs are unchanged.
• New: conn.async_cursor() → PyCoreAsyncCursor.
• The async path uses a self-contained with_async_client checkout helper in pyclient.rs; the shared client cell stays std::sync::Mutex (no retype needed).
• Doc-label scrub: fixes the stale "async cursor" comments now that a real coroutine cursor exists.

Changes (py-core only)

• src/async_cursor.rs (new) — PyCoreAsyncCursor coroutine cursor.
• src/pyclient.rs — with_async_client async checkout helper + honest module doc.
• src/connection.rs — Connection.async_cursor().
• src/lib.rs — register PyCoreAsyncCursor.
• Cargo.toml — add pyo3-async-runtimes = { version = "0.29", features = ["tokio-runtime"] }.
• Tests: mock-backed coroutine tests + a CI WAITFOR-based non-blocking proof.

Non-blocking proof

• Static: zero block_on on the async_cursor.rs coroutine path (I/O is spawned on the connection runtime; the coroutine awaits the join handle).
• Local (mock): test_async_cursor_yields_to_event_loop — a concurrent ticker advances while a fetch is awaited (mock answers in µs, so this asserts the weaker "yields at least once").
• CI (live server): test_async_cursor_integration.py — a concurrent 10ms ticker racks up ticks during a server-side WAITFOR DELAY '00:00:02' inside the coroutine's await.

Notes

• Perf-sanity (flag, not block): over the mock (µs-scale I/O) the coroutine path is ~3.7x the default block_on path — this is pure coroutine-plumbing overhead on a zero-latency backend, not representative of real network I/O where the overhead is negligible and concurrency dominates.
• mssql-py-core Cargo.lock is gitignored; the new dep resolves under the --frozen py-core clippy/test leg locally.

Part of the sans-I/O native stack - see cover PR #189 for the stack-level summary and tracked debt.

[Copilot]

Pull request overview

Adds a coroutine-based Python cursor that performs TDS operations without blocking the asyncio event loop.

Changes:

• Adds and registers PyCoreAsyncCursor and Connection.async_cursor().
• Adds asynchronous client checkout and the required runtime dependency.
• Adds mock and live-server coroutine tests and updates cursor terminology.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
mssql-py-core/Cargo.toml	Adds the PyO3 async runtime dependency.
mssql-py-core/src/async_cursor.rs	Implements the coroutine cursor.
mssql-py-core/src/connection.rs	Exposes async_cursor().
mssql-py-core/src/lib.rs	Registers the new Python class.
mssql-py-core/src/pyclient.rs	Adds asynchronous client checkout.
mssql-py-core/tests/rs-only-tests/test_async_cursor_mock.py	Tests coroutine cursor behavior.
mssql-py-core/tests/rs-only-tests/test_sync_async_cursor_mock.py	Corrects default cursor terminology.
mssql-py-core/tests/test_async_cursor_integration.py	Verifies live-server non-blocking behavior.

---

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