Deprecate the SEA backend; steer users to the kernel path

[vikrantpuppala]

Summary

The SEA backend (use_sea=True) has feature gaps — notably it does not support positional (?) parameter binding. The connector emits SEA parameters without the API-required ordinal field, so cur.execute("... WHERE col = ?", ("value",)) fails with HTTP 400 against RT/Lakehouse warehouses (which require use_sea=True and refuse Thrift).

Rather than partially patch SEA, this PR marks it deprecated and steers users to the supported kernel backend (use_kernel=True + the [kernel] extra) — a SEA-native client that already handles positional and named parameter binding correctly.

Changes

• Runtime warning: a one-time logger.warning in SeaDatabricksClient.__init__ (fires once per SEA session, not per query) pointing users to use_kernel=True + the [kernel] extra.
• Docs: connect() docstring now marks use_sea deprecated/incomplete, and the stale use_kernel docstring is refreshed (it ships on PyPI via the [kernel] extra and supports parameter binding — the old text wrongly said neither).
• Examples / contributor docs: the examples/experimental/ SEA harness and the CONTRIBUTING backend table are flagged as deprecated.

What this does / doesn't do

• Does not change SEA's runtime behavior — SEA stays functional. RT/Lakehouse warehouses refuse Thrift, so use_sea cannot simply be rerouted to Thrift without breaking the exact warehouses it targets.
• Does not change packaging — pyarrow and databricks-sql-kernel remain optional extras (the kernel wheel is a platform-specific PyO3 binary; forcing it on every install would break unsupported platforms).

Verification

• 23/23 tests/unit/test_sea_backend.py pass, including a new test_initialization_warns_backend_incomplete.
• Confirmed the kernel path handles positional ? params correctly — ran the kernel parameterized e2e tests live against a real warehouse: 7/7 passed (positional, named, NULL, decimal, timestamp, scientific-notation).

This pull request and its description were written by Isaac.

[peco-review-bot]

Verdict: 1 Low

Looks good — a minimal, well-tested logger.warning steering SEA users toward the kernel backend. Verified the guidance is accurate: use_kernel=True, the databricks-sql-connector dist name, and the [kernel] extra all match the codebase/pyproject.toml, and the new unit test correctly asserts the warning content. One low note on the blanket "should not be used in production" wording given RT/Lakehouse warehouses require SEA.

[peco-review-bot]

Verdict: 1 Low

Looks good — a one-time construction warning plus a matching unit test. Verified use_kernel=True and the [kernel] extra referenced in the message are real. One low: the message recommends the kernel path unconditionally, but the kernel wheel needs Python >= 3.10, so the advice misfires on 3.8/3.9.

[peco-review-bot]

Verdict: 1 Low

Looks good — a low-risk deprecation PR (runtime warning + docstring/doc flags) whose one behavior change is covered by a new unit test. One low-severity note on deprecation-message consistency and the choice of logger.warning vs DeprecationWarning.

[peco-review-bot]

Verdict: 1 Low

Looks good — a low-risk deprecation/docs PR. The runtime warning is correctly placed in SeaDatabricksClient.__init__ (once per session as described), SEA runtime behavior is unchanged, and the new unit test genuinely exercises the warning. One low note on the deprecation mechanism (logger.warning vs DeprecationWarning) and per-session log volume.