ai: apply changes for #925 (1 review thread)

Addresses:
  - #3877431848 at src/databricks/sql/backend/kernel/client.py:180

Signed-off-by: peco-engineer-bot[bot] <peco-engineer-bot[bot]@users.noreply.github.com>

Author: peco-engineer-bot[bot]

src/databricks/sql/backend/kernel/client.py

@@ -22,6 +22,7 @@
 
 from __future__ import annotations
 
+import inspect
 import logging
 import threading
 import uuid
@@ -173,10 +174,39 @@ def _is_staging_statement(operation: str) -> bool:
     return verb in _STAGING_VERBS
 
 
+def _kernel_session_accepts_kwarg(name: str) -> bool:
+    """True iff the installed ``databricks_sql_kernel.Session`` constructor
+    declares keyword ``name``.
+
+    The kernel ``Session`` is a PyO3 class with a **fixed** signature (no
+    ``**kwargs`` catch-all), so forwarding a kwarg it doesn't declare raises
+    ``TypeError`` at construction. The phase-7 identity/telemetry kwargs
+    (``driver_name`` etc.) only exist on wheels newer than the pinned
+    ``^0.2.0`` (whose ``Session`` accepts none of them), so we must gate them
+    on what the actually-installed wheel supports rather than pass them
+    unconditionally. Falls open (returns ``True``) only when the signature
+    can't be introspected, so a future non-introspectable binding still gets
+    the kwargs.
+    """
+    try:
+        params = inspect.signature(_kernel.Session).parameters
+    except (TypeError, ValueError):
+        return True
+    if any(p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()):
+        return True
+    return name in params
+
+
 def _kernel_telemetry_kwargs(options: Dict[str, Any]) -> Dict[str, Any]:
-    """Build phase-7 telemetry/system kwargs for ``databricks_sql_kernel.Session``."""
+    """Build phase-7 telemetry/system kwargs for ``databricks_sql_kernel.Session``.
+
+    Only kwargs the installed ``Session`` constructor actually accepts are
+    returned; on the pinned ``^0.2.0`` wheel (which predates phase 7) this is
+    empty, so ``open_session`` doesn't break with ``TypeError`` on a wheel
+    that doesn't yet know these kwargs.
+    """
     system = TelemetryHelper.get_driver_system_configuration()
-    out: Dict[str, Any] = {
+    candidates: Dict[str, Any] = {
         "driver_name": system.driver_name,
         "driver_version": system.driver_version,
         "runtime_name": system.runtime_name,
@@ -193,14 +223,18 @@ def _kernel_telemetry_kwargs(options: Dict[str, Any]) -> Dict[str, Any]:
         "process_name": None,
     }
     if options.get("enable_telemetry") is not None:
-        out["telemetry_enabled"] = bool(options["enable_telemetry"])
+        candidates["telemetry_enabled"] = bool(options["enable_telemetry"])
     if options.get("telemetry_batch_size") is not None:
-        out["telemetry_batch_size"] = options["telemetry_batch_size"]
+        candidates["telemetry_batch_size"] = options["telemetry_batch_size"]
     if options.get("telemetry_circuit_breaker_enabled") is not None:
-        out["telemetry_circuit_breaker_enabled"] = options[
+        candidates["telemetry_circuit_breaker_enabled"] = options[
             "telemetry_circuit_breaker_enabled"
         ]
-    return out
+    return {
+        name: value
+        for name, value in candidates.items()
+        if _kernel_session_accepts_kwarg(name)
+    }
 
 
 # ─── Client ─────────────────────────────────────────────────────────────────

tests/unit/_scratch_kernel_kwargs_probe.py

@@ -428,6 +428,97 @@ def fake_session(**kw):
     assert captured["telemetry_circuit_breaker_enabled"] is False
 
 
+def test_open_session_omits_phase_7_kwargs_kernel_does_not_accept(monkeypatch):
+    """Phase-7 identity/telemetry kwargs must NOT be forwarded to a kernel
+    ``Session`` whose (fixed, no-``**kwargs``) constructor doesn't declare
+    them.
+
+    The real ``databricks_sql_kernel.Session`` is a PyO3 class with a fixed
+    signature; the pinned ``^0.2.0`` wheel predates phase 7 and accepts none
+    of these kwargs, so forwarding them unconditionally raises ``TypeError``
+    and breaks every ``use_kernel=True`` connection. The other tests here use
+    a ``**kwargs`` MagicMock that silently swallows the kwargs and hides the
+    break; this one uses a fixed-signature fake mirroring the real 0.2.0
+    surface to prove the client gates on what the installed Session supports.
+    """
+    captured = {}
+
+    # Fixed signature mirroring the pinned 0.2.0 kernel Session: it accepts
+    # the base connection/tls/retry kwargs but NONE of the phase-7 identity
+    # or telemetry kwargs, and has no **kwargs catch-all.
+    def fake_session_v0_2_0(
+        host,
+        http_path,
+        *,
+        auth_type=None,
+        access_token=None,
+        client_id=None,
+        client_secret=None,
+        oauth_scopes=None,
+        token_url=None,
+        redirect_port=None,
+        oauth_callback_timeout_secs=None,
+        tls_ca_cert=None,
+        tls_skip_verify=False,
+        tls_skip_hostname_verify=False,
+        tls_client_cert=None,
+        tls_client_key=None,
+        retry_min_wait_secs=None,
+        retry_max_wait_secs=None,
+        retry_max_attempts=None,
+        retry_overall_timeout_secs=None,
+        http_headers=None,
+        catalog=None,
+        schema=None,
+        session_conf=None,
+        complex_types_as_json=False,
+        intervals_as_string=False,
+        request_timeout_secs=None,
+    ):
+        captured["host"] = host
+        sess = MagicMock()
+        sess.session_id = "sess-id"
+        return sess
+
+    monkeypatch.setattr(kernel_client._kernel, "Session", fake_session_v0_2_0)
+    monkeypatch.setattr(
+        kernel_client.TelemetryHelper,
+        "get_driver_system_configuration",
+        lambda: types.SimpleNamespace(
+            driver_name="Databricks SQL Python Connector",
+            driver_version="1.2.3",
+            runtime_name="Python 3.12.0",
+            runtime_version="3.12.0",
+            runtime_vendor="CPython",
+            os_name="Linux",
+            os_version="6.1",
+            os_arch="x86_64",
+            client_app_name=None,
+            locale_name="en_US",
+            char_set_encoding="utf-8",
+        ),
+    )
+
+    # The kwargs the client builds must be filtered to what fake_session
+    # accepts, so open_session succeeds instead of raising TypeError.
+    kwargs = kernel_client._kernel_telemetry_kwargs(
+        {"enable_telemetry": True, "telemetry_batch_size": 17}
+    )
+    assert kwargs == {}, f"expected no phase-7 kwargs on 0.2.0 Session, got {kwargs}"
+
+    c = kernel_client.KernelDatabricksClient(
+        server_hostname="example.cloud.databricks.com",
+        http_path="/sql/1.0/warehouses/abc",
+        auth_provider=AccessTokenAuthProvider("dapi-test"),
+        ssl_options=None,
+        telemetry_options={"enable_telemetry": True, "telemetry_batch_size": 17},
+    )
+    # Would raise TypeError: unexpected keyword argument if the client
+    # forwarded phase-7 kwargs the fixed-signature Session doesn't declare.
+    c.open_session(session_configuration=None, catalog=None, schema=None)
+    assert captured["host"] == "example.cloud.databricks.com"
+
+
 def test_execute_command_forwards_parameters_to_bind_param():
     """``execute_command(parameters=[...])`` routes each parameter
     through ``bind_tspark_params`` onto the kernel statement before