[Enhancement]: Unify Python SDK parameter, result and optional-dependency contracts #30069

Existing issue check

• Checked relevant Python SDK issues; this report concerns the SDK client path.

Environment

Repository main 3e50e1b32d8da61bbbf70c89989fb08b671809de, Python 3.12, SQLAlchemy 1.4/2.x. Initial findings were reproduced offline with synthetic inputs; real-service validation will be linked from the implementation PR.

Priority: P2.

Requirements

Document and converge the different parameter conventions of Client/AsyncClient/Session/analytics; introduce a compatibility path toward driver-bound parameters while preserving callers. Standardize return types, type hints, context lifetime and sync/async API parity. Publish a tested core/analytics/DataFrame optional-dependency matrix rather than treating grammar parsing as runtime support.

Audit advertised Python >=3.8 support against runtime annotations and dependency availability. PyArrow >=18 analytics requires a compatible Python version; this must be explicit. Correct SQLAlchemy 2.1 changes in reserved-field tests without pretending a warning is still an exception.

Design and acceptance tests

Specify migration/deprecation policy, install/import minimal core and each extra in supported Python versions, validate wheel metadata/stubs and run representative sync/async/result APIs. Verify marker-looking strings, named/positional mappings, empty/all-NULL results and dependency-absent diagnostics. Distinguish newly confirmed compatibility bugs from optional API redesign.

Implementation tracking

Design/implementation follow-up remains open. This requirement is not claimed as implemented by the current bug-fix/performance PRs. Related synchronous analytics draft: #30054.

Confirmed dependency-matrix boundary

SQLAlchemy 2.1 declares Requires-Python >=3.11. Python 3.10 must use a compatible earlier series (such as 2.0), rather than an impossible 3.10/2.1 CI cell. The SDK CI PR #30075 now encodes this boundary. Core Python 3.8/3.9 qualification remains an explicit follow-up.