databricks-sql-connector 4.2.5__tar.gz → 4.2.7__tar.gz

{databricks_sql_connector-4.2.5 → databricks_sql_connector-4.2.7}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Release History
 
+# 4.2.7 (2026-06-02)
+- Extract SPOG org-id from cluster http_path for non-Thrift requests (databricks/databricks-sql-python#817 by @msrathore-db)
+- Remove empty chunks in CloudFetch concatenation (databricks/databricks-sql-python#814 by @jprakash-db)
+- Add `_retry_server_directed_only` mode for Retry-After header compliance (databricks/databricks-sql-python#756 by @sd-db)
+- Bump thrift to 0.23.0 (databricks/databricks-sql-python#796 by @leoromanovsky)
+- Allow pandas 3.x in dependency constraints (databricks/databricks-sql-python#768 by @moomindani)
+- Telemetry: unwrap TokenFederationProvider to report inner auth mechanism/flow (databricks/databricks-sql-python#781 by @samikshya-db)
+
+# 4.2.6 (2026-04-22)
+- Add SPOG routing support for account-level vanity URLs (databricks/databricks-sql-python#767 by @msrathore-db)
+- Fix dependency_manager: handle PEP 440 ~= compatible release syntax (databricks/databricks-sql-python#776 by @vikrantpuppala)
+- Bump thrift to fix deprecation warning (databricks/databricks-sql-python#733 by @Korijn)
+- Add AI coding agent detection to User-Agent header (databricks/databricks-sql-python#740 by @vikrantpuppala)
+- Add statement-level query_tags support for SEA backend (databricks/databricks-sql-python#754 by @sreekanth-db)
+- Update PyArrow concatenation of tables to use promote_options as default (databricks/databricks-sql-python#751 by @jprakash-db)
+- Fix float inference to use DoubleParameter (64-bit) instead of FloatParameter (databricks/databricks-sql-python#742 by @Shubhambhusate)
+- Allow specifying query_tags as a dict upon connection creation (databricks/databricks-sql-python#749 by @jiabin-hu)
+- Add query_tags parameter support for execute methods (databricks/databricks-sql-python#736 by @jiabin-hu)
+
 # 4.2.5 (2026-02-09)
 - Fix feature-flag endpoint retries in gov region (databricks/databricks-sql-python#735 by @samikshya-db)
 - Improve telemetry lifecycle management (databricks/databricks-sql-python#734 by @msrathore-db)

{databricks_sql_connector-4.2.5 → databricks_sql_connector-4.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-sql-connector
-Version: 4.2.5
+Version: 4.2.7
 Summary: Databricks SQL Connector for Python
 License: Apache-2.0
 License-File: LICENSE
@@ -21,8 +21,8 @@ Requires-Dist: lz4 (>=4.0.2,<5.0.0) ; python_version >= "3.8" and python_version
 Requires-Dist: lz4 (>=4.4.5,<5.0.0) ; python_version >= "3.14"
 Requires-Dist: oauthlib (>=3.1.0,<4.0.0)
 Requires-Dist: openpyxl (>=3.0.10,<4.0.0)
-Requires-Dist: pandas (>=1.2.5,<2.4.0) ; python_version >= "3.8" and python_version < "3.13"
-Requires-Dist: pandas (>=2.2.3,<2.4.0) ; python_version >= "3.13"
+Requires-Dist: pandas (>=1.2.5,<4.0.0) ; python_version >= "3.8" and python_version < "3.13"
+Requires-Dist: pandas (>=2.2.3,<4.0.0) ; python_version >= "3.13"
 Requires-Dist: pyarrow (>=14.0.1) ; (python_version >= "3.8" and python_version < "3.13") and (extra == "pyarrow")
 Requires-Dist: pyarrow (>=18.0.0) ; (python_version == "3.13") and (extra == "pyarrow")
 Requires-Dist: pyarrow (>=22.0.0) ; (python_version >= "3.14") and (extra == "pyarrow")
@@ -30,7 +30,7 @@ Requires-Dist: pybreaker (>=1.0.0,<2.0.0)
 Requires-Dist: pyjwt (>=2.0.0,<3.0.0)
 Requires-Dist: python-dateutil (>=2.8.0,<3.0.0)
 Requires-Dist: requests (>=2.18.1,<3.0.0)
-Requires-Dist: thrift (>=0.16.0,<0.21.0)
+Requires-Dist: thrift (>=0.22.0,<0.24.0)
 Requires-Dist: urllib3 (>=1.26)
 Project-URL: Bug Tracker, https://github.com/databricks/databricks-sql-python/issues
 Project-URL: Homepage, https://github.com/databricks/databricks-sql-python

{databricks_sql_connector-4.2.5 → databricks_sql_connector-4.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "databricks-sql-connector"
-version = "4.2.5"
+version = "4.2.7"
 description = "Databricks SQL Connector for Python"
 authors = ["Databricks <databricks-sql-connector-maintainers@databricks.com>"]
 license = "Apache-2.0"
@@ -10,10 +10,10 @@ include = ["CHANGELOG.md"]
 
 [tool.poetry.dependencies]
 python = "^3.8.0"
-thrift = ">=0.16.0,<0.21.0"
+thrift = ">=0.22.0,<0.24.0"
 pandas = [
-    { version = ">=1.2.5,<2.4.0", python = ">=3.8,<3.13" },
-    { version = ">=2.2.3,<2.4.0", python = ">=3.13" }
+    { version = ">=1.2.5,<4.0.0", python = ">=3.8,<3.13" },
+    { version = ">=2.2.3,<4.0.0", python = ">=3.13" }
 ]
 lz4 = [
     { version = "^4.0.2", python = ">=3.8,<3.14" },
@@ -36,6 +36,20 @@ requests-kerberos = {version = "^0.15.0", optional = true}
 
 [tool.poetry.extras]
 pyarrow = ["pyarrow"]
+# `[kernel]` extra is intentionally not declared here yet.
+# `databricks-sql-kernel` is built from the databricks-sql-kernel
+# repo and not yet published to PyPI; declaring it as a poetry dep
+# breaks `poetry lock` for every CI job. Once the wheel is on PyPI
+# the extra will be added back here:
+#
+#     databricks-sql-kernel = {version = "^0.1.0", optional = true}
+#     [tool.poetry.extras]
+#     kernel = ["databricks-sql-kernel"]
+#
+# Until then, the wheel is not on PyPI and the only supported
+# install path is local dev:
+#     cd databricks-sql-kernel/pyo3 && maturin develop --release
+# (into the same venv as databricks-sql-connector).
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.1.2"

{databricks_sql_connector-4.2.5 → databricks_sql_connector-4.2.7}/src/databricks/sql/__init__.py

@@ -71,7 +71,7 @@ DATETIME = DBAPITypeObject("timestamp")
 DATE = DBAPITypeObject("date")
 ROWID = DBAPITypeObject()
 
-__version__ = "4.2.5"
+__version__ = "4.2.7"
 USER_AGENT_NAME = "PyDatabricksSqlConnector"
 
 # These two functions are pyhive legacy

{databricks_sql_connector-4.2.5 → databricks_sql_connector-4.2.7}/src/databricks/sql/auth/common.py

@@ -47,6 +47,7 @@ class ClientContext:
         retry_stop_after_attempts_duration: Optional[float] = None,
         retry_delay_default: Optional[float] = None,
         retry_dangerous_codes: Optional[List[int]] = None,
+        respect_server_retry_after_header: Optional[bool] = None,
         proxy_auth_method: Optional[str] = None,
         pool_connections: Optional[int] = None,
         pool_maxsize: Optional[int] = None,
@@ -80,6 +81,7 @@ class ClientContext:
         )
         self.retry_delay_default = retry_delay_default or 5.0
         self.retry_dangerous_codes = retry_dangerous_codes or []
+        self.respect_server_retry_after_header = bool(respect_server_retry_after_header)
         self.proxy_auth_method = proxy_auth_method
         self.pool_connections = pool_connections or 10
         self.pool_maxsize = pool_maxsize or 20

{databricks_sql_connector-4.2.5 → databricks_sql_connector-4.2.7}/src/databricks/sql/auth/retry.py

@@ -94,6 +94,7 @@ class DatabricksRetryPolicy(Retry):
         stop_after_attempts_duration: float,
         delay_default: float,
         force_dangerous_codes: List[int],
+        respect_server_retry_after_header: bool = False,
         urllib3_kwargs: dict = {},
     ):
         # These values do not change from one command to the next
@@ -103,6 +104,7 @@ class DatabricksRetryPolicy(Retry):
         self.stop_after_attempts_duration = stop_after_attempts_duration
         self._delay_default = delay_default
         self.force_dangerous_codes = force_dangerous_codes
+        self.respect_server_retry_after_header = respect_server_retry_after_header
 
         # the urllib3 kwargs are a mix of configuration (some of which we override)
         # and counters like `total` or `connect` which may change between successive retries
@@ -202,6 +204,7 @@ class DatabricksRetryPolicy(Retry):
             stop_after_attempts_duration=self.stop_after_attempts_duration,
             delay_default=self.delay_default,
             force_dangerous_codes=self.force_dangerous_codes,
+            respect_server_retry_after_header=self.respect_server_retry_after_header,
             urllib3_kwargs={},
         )
 
@@ -323,7 +326,9 @@ class DatabricksRetryPolicy(Retry):
 
         return proposed_backoff
 
-    def should_retry(self, method: str, status_code: int) -> Tuple[bool, str]:
+    def should_retry(
+        self, method: str, status_code: int, has_retry_after: bool = False
+    ) -> Tuple[bool, str]:
         """This method encapsulates the connector's approach to retries.
 
         We always retry a request unless one of these conditions is met:
@@ -388,6 +393,15 @@ class DatabricksRetryPolicy(Retry):
         if not self._is_method_retryable(method):
             return False, "Only POST requests are retried"
 
+        # When respect_server_retry_after_header is enabled, only retry when the
+        # server explicitly signals it's safe via a Retry-After header. This prevents
+        # duplicate side effects for non-idempotent operations.
+        if self.respect_server_retry_after_header and not has_retry_after:
+            return (
+                False,
+                "respect_server_retry_after_header mode: no Retry-After header present",
+            )
+
         # Request failed, was an ExecuteStatement and the command may have reached the server
         if (
             self.command_type == CommandType.EXECUTE_STATEMENT
@@ -430,7 +444,7 @@ class DatabricksRetryPolicy(Retry):
         Logs a debug message if the request will be retried
         """
 
-        should_retry, msg = self.should_retry(method, status_code)
+        should_retry, msg = self.should_retry(method, status_code, has_retry_after)
 
         if should_retry:
             logger.debug(msg)

{databricks_sql_connector-4.2.5 → databricks_sql_connector-4.2.7}/src/databricks/sql/backend/databricks_client.py

@@ -83,6 +83,7 @@ class DatabricksClient(ABC):
         async_op: bool,
         enforce_embedded_schema_correctness: bool,
         row_limit: Optional[int] = None,
+        query_tags: Optional[Dict[str, Optional[str]]] = None,
     ) -> Union[ResultSet, None]:
         """
         Executes a SQL command or query within the specified session.
@@ -102,6 +103,7 @@ class DatabricksClient(ABC):
             async_op: Whether to execute the command asynchronously
             enforce_embedded_schema_correctness: Whether to enforce schema correctness
             row_limit: Maximum number of rows in the response.
+            query_tags: Optional dictionary of query tags to apply for this query only.
 
         Returns:
             If async_op is False, returns a ResultSet object containing the

databricks_sql_connector-4.2.7/src/databricks/sql/backend/kernel/__init__.py

@@ -0,0 +1,25 @@
+"""Backend that delegates to the Databricks SQL Kernel (Rust) via PyO3.
+
+Routed when ``use_kernel=True`` is passed to ``databricks.sql.connect``.
+The module's identity is "delegates to the kernel" — not the wire
+protocol the kernel happens to use today (SEA REST). The kernel may
+switch its default transport (SEA REST → SEA gRPC → …) without
+renaming this module.
+
+This ``__init__`` deliberately does **not** re-export
+``KernelDatabricksClient`` from ``.client``. Importing ``.client``
+loads the ``databricks_sql_kernel`` PyO3 extension at module-import
+time; doing that eagerly here would make ``import
+databricks.sql.backend.kernel.type_mapping`` (used by tests / by
+``KernelResultSet`` consumers) require the kernel wheel even when
+the caller never plans to open a kernel-backed session. Callers
+that need the client import it directly:
+
+    from databricks.sql.backend.kernel.client import KernelDatabricksClient
+
+``session.py::_create_backend`` already does this lazy import under
+the ``use_kernel=True`` branch.
+
+See ``docs/designs/pysql-kernel-integration.md`` in
+``databricks-sql-kernel`` for the full integration design.
+"""

databricks_sql_connector-4.2.7/src/databricks/sql/backend/kernel/_errors.py

@@ -0,0 +1,134 @@
+"""Shared error-mapping primitives for the kernel backend.
+
+The PyO3 boundary can produce two flavours of exception:
+
+- ``databricks_sql_kernel.KernelError`` — the kernel's own
+  structured error type. Carries ``code`` / ``message`` /
+  ``sql_state`` / ``query_id`` / ``http_status`` / ``retryable`` /
+  ``vendor_code`` / ``error_code`` as attributes; mapped to a PEP
+  249 exception class via ``_CODE_TO_EXCEPTION`` with the
+  attributes forwarded onto the re-raised exception so callers can
+  branch on ``err.code`` / ``err.sql_state`` without reaching
+  through ``__cause__``.
+- Anything else — ``TypeError`` / ``OverflowError`` /
+  ``ValueError`` from PyO3 argument conversion, or arbitrary
+  extension-internal Python errors. These would otherwise propagate
+  raw to connector callers, breaking the DB-API contract that says
+  "only PEP 249 exception types cross the boundary". Wrapped in
+  ``OperationalError`` here.
+
+These primitives live in their own module so both ``client.py``
+(which orchestrates PyO3 calls) and ``result_set.py`` (which calls
+``fetch_next_batch`` on the same kernel handles) can share them
+without ``result_set.py`` importing from ``client.py``.
+
+Usage at every PyO3 call site is a plain try/except:
+
+    try:
+        stmt.execute()
+    except Exception as exc:
+        raise wrap_kernel_exception("execute_command", exc) from exc
+
+The helper returns the mapped exception; callers raise it. Plain
+``try/except`` is preferred over a context manager: the control
+flow is visible at the call site, the helper is a pure function
+(trivial to test), and tracebacks don't carry an extra
+``__exit__`` frame.
+"""
+
+from __future__ import annotations
+
+from databricks.sql.exc import (
+    DatabaseError,
+    Error,
+    OperationalError,
+    ProgrammingError,
+    ServerOperationError,
+)
+
+try:
+    import databricks_sql_kernel as _kernel  # type: ignore[import-not-found]
+except ImportError as exc:  # pragma: no cover - same hint as client.py
+    raise ImportError(
+        "use_kernel=True requires the databricks-sql-kernel extension, which "
+        "is not yet published on PyPI. Build and install it locally from the "
+        "databricks-sql-kernel repo:\n"
+        "  cd databricks-sql-kernel/pyo3 && maturin develop --release\n"
+        "(into the same venv as databricks-sql-connector)."
+    ) from exc
+
+
+# Map a kernel `code` slug to the PEP 249 exception class that best
+# captures it. The match isn't a perfect 1:1 — PEP 249 has a
+# narrower taxonomy than the kernel — so several kernel codes
+# collapse onto the same Python exception. This table is the only
+# place that mapping lives.
+_CODE_TO_EXCEPTION = {
+    "InvalidArgument": ProgrammingError,
+    "Unauthenticated": OperationalError,
+    "PermissionDenied": OperationalError,
+    "NotFound": ProgrammingError,
+    "ResourceExhausted": OperationalError,
+    "Unavailable": OperationalError,
+    "Timeout": OperationalError,
+    "Cancelled": OperationalError,
+    "DataLoss": DatabaseError,
+    "Internal": DatabaseError,
+    "InvalidStatementHandle": ProgrammingError,
+    "NetworkError": OperationalError,
+    # `SqlError` is a server-side query failure (syntax error, missing
+    # object, etc.) — exactly what the Thrift backend surfaces as
+    # `ServerOperationError`. Match Thrift's contract so user code that
+    # catches `ServerOperationError` (a subclass of `DatabaseError`)
+    # works equivalently with `use_kernel=True`.
+    "SqlError": ServerOperationError,
+    "Unknown": DatabaseError,
+}
+
+
+def reraise_kernel_error(exc: "_kernel.KernelError") -> "Error":
+    """Convert a ``databricks_sql_kernel.KernelError`` to a PEP 249
+    exception with the kernel's structured attributes forwarded onto
+    the new instance.
+
+    The returned exception is raised by callers with ``raise ... from
+    exc``; the ``from`` clause is what sets ``__cause__``, so we don't
+    touch it here.
+    """
+    code = getattr(exc, "code", "Unknown")
+    cls = _CODE_TO_EXCEPTION.get(code, DatabaseError)
+    new = cls(getattr(exc, "message", str(exc)))
+    for attr in (
+        "code",
+        "sql_state",
+        "error_code",
+        "vendor_code",
+        "http_status",
+        "retryable",
+        "query_id",
+    ):
+        setattr(new, attr, getattr(exc, attr, None))
+    return new
+
+
+def wrap_kernel_exception(what: str, exc: BaseException) -> "Error":
+    """Map any exception from a PyO3 call site to a PEP 249 exception.
+
+    - ``KernelError`` → mapped class with structured attrs forwarded.
+    - Already-PEP-249 ``Error`` (e.g. raised by an inner caller that
+      already mapped) → passed through unchanged.
+    - Anything else (``TypeError`` / ``ValueError`` / etc. from PyO3
+      argument conversion, extension-internal errors) → wrapped in
+      ``OperationalError``.
+
+    Returned, not raised — the caller decides whether to ``raise``
+    or ``raise ... from exc``. ``what`` is a short tag (the calling
+    method name) used only in the ``OperationalError`` message.
+    """
+    if isinstance(exc, _kernel.KernelError):
+        return reraise_kernel_error(exc)
+    if isinstance(exc, Error):
+        return exc
+    return OperationalError(
+        f"Unexpected error from databricks_sql_kernel during {what}: {exc!r}"
+    )

databricks_sql_connector-4.2.7/src/databricks/sql/backend/kernel/auth_bridge.py

@@ -0,0 +1,268 @@
+"""Translate the connector's auth configuration into
+``databricks_sql_kernel`` ``Session`` auth kwargs.
+
+Three auth shapes are supported on the kernel path:
+
+- **PAT** — extracted from the built ``AuthProvider`` (works for
+  ``AccessTokenAuthProvider``, including the ``TokenFederationProvider``
+  wrapper that ``get_python_sql_connector_auth_provider`` always
+  applies). Maps to the kernel's ``auth_type='pat'``.
+- **OAuth M2M** — when the caller passes ``oauth_client_id`` +
+  ``oauth_client_secret``, the *raw* credentials are forwarded to the
+  kernel's ``auth_type='oauth-m2m'`` and the kernel owns the full
+  token lifecycle (acquire + refresh via workspace OIDC
+  client-credentials). We forward the raw pair rather than reusing the
+  connector's own OAuth provider because the kernel re-mints tokens
+  itself and the client secret is not recoverable from a built
+  provider.
+- **OAuth U2M** — for ``auth_type`` ``databricks-oauth`` /
+  ``azure-oauth`` (the browser authorization-code flow), the optional
+  ``oauth_client_id`` / ``oauth_redirect_port`` are forwarded to the
+  kernel's ``auth_type='oauth-u2m'`` and the kernel runs the browser
+  flow itself.
+
+A user-supplied custom ``credentials_provider`` is **rejected** on the
+kernel path with ``NotSupportedError``: it's an opaque token source
+with no extractable raw credentials, so the kernel can't own the
+lifecycle. Such callers should pass ``oauth_client_id`` /
+``oauth_client_secret`` (M2M) instead. Anything else non-PAT also
+raises ``NotSupportedError`` so the failure surfaces at session-open
+with a clear message rather than deep inside the kernel.
+
+The M2M / U2M decisions are driven by the *raw* connect() kwargs
+(``auth_options``), not a built ``AuthProvider``. On the kernel path
+the connector deliberately does **not** build its own OAuth provider
+(that would eagerly run the U2M browser flow / M2M token exchange at
+connect() time, before the kernel is consulted), so ``auth_provider``
+is either a minimal PAT provider or ``None`` and the OAuth credentials
+are available only from the raw kwargs.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Dict, Optional
+
+from databricks.sql.auth.authenticators import AccessTokenAuthProvider, AuthProvider
+from databricks.sql.auth.token_federation import TokenFederationProvider
+from databricks.sql.exc import NotSupportedError, ProgrammingError
+
+logger = logging.getLogger(__name__)
+
+
+# RFC 6750 §2.1 defines the Authorization scheme as case-insensitive.
+# The connector's auth providers all emit ``Bearer `` exactly today,
+# but we match leniently in case a federation proxy or future provider
+# normalises the casing differently — failing closed here would surface
+# as a confusing ``ProgrammingError`` from the bridge.
+_BEARER_PREFIX_LEN = len("Bearer ")
+
+# Defense-in-depth: reject tokens containing ASCII control characters
+# or whitespace. CR/LF/NUL in a token would let a misbehaving HTTP
+# stack split or terminate the Authorization header line, opening a
+# header-injection sink. Space (0x20) is included so leading-/
+# embedded-whitespace tokens (e.g. ``"Bearer  doubled-space-token"``,
+# tab-prefixed token) get rejected too — RFC 6750 §2.1 forbids
+# whitespace within the credential token itself.
+_TOKEN_REJECT_RE = re.compile(r"[\x00-\x20\x7f]")
+
+
+def _is_pat(auth_provider: Optional[AuthProvider]) -> bool:
+    """Return True iff this provider ultimately wraps an
+    ``AccessTokenAuthProvider``.
+
+    ``get_python_sql_connector_auth_provider`` always wraps the
+    base provider in a ``TokenFederationProvider``, so an
+    ``isinstance`` check against ``AccessTokenAuthProvider`` alone
+    never matches in practice. We peek through the federation
+    wrapper to find the real type.
+    """
+    if isinstance(auth_provider, AccessTokenAuthProvider):
+        return True
+    if isinstance(auth_provider, TokenFederationProvider) and isinstance(
+        auth_provider.external_provider, AccessTokenAuthProvider
+    ):
+        return True
+    return False
+
+
+def _extract_bearer_token(auth_provider: Optional[AuthProvider]) -> Optional[str]:
+    """Pull the current bearer token out of an ``AuthProvider``.
+
+    The connector's ``AuthProvider.add_headers`` mutates a header
+    dict and writes the ``Authorization: Bearer <token>`` value.
+    Going through that public surface keeps us insulated from
+    provider-specific internals.
+
+    Returns ``None`` if there is no provider, the provider did not
+    write an Authorization header, or it wrote a non-Bearer scheme —
+    none of which is representable in the kernel's PAT auth surface.
+    """
+    if auth_provider is None:
+        return None
+    headers: Dict[str, str] = {}
+    auth_provider.add_headers(headers)
+    auth = headers.get("Authorization")
+    if not auth:
+        return None
+    if not auth[:_BEARER_PREFIX_LEN].lower() == "bearer ":
+        return None
+    token = auth[_BEARER_PREFIX_LEN:]
+    if _TOKEN_REJECT_RE.search(token):
+        raise ProgrammingError(
+            "Bearer token contains ASCII control characters or whitespace; "
+            "refusing to forward it to the kernel auth bridge."
+        )
+    return token
+
+
+def kernel_auth_kwargs(
+    auth_provider: Optional[AuthProvider],
+    auth_options: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Build the kwargs passed to ``databricks_sql_kernel.Session(...)``.
+
+    ``auth_options`` carries the raw connect() kwargs relevant to auth
+    (``auth_type``, ``oauth_client_id``, ``oauth_client_secret``,
+    ``oauth_redirect_port``, ``credentials_provider``). They drive the
+    OAuth decisions because the OAuth secret is consumed during
+    ``AuthProvider`` construction and can't be read back off the built
+    provider.
+
+    Resolution order:
+
+    0. **Ambiguity guards** — reject conflicting auth signals *before*
+       resolving, so an ambiguous request fails loudly at session-open
+       rather than silently picking one flow (and failing later as a
+       confusing 401 against the wrong principal):
+       - a custom ``credentials_provider`` *and* M2M kwargs together;
+       - a U2M ``auth_type`` (``databricks-oauth`` / ``azure-oauth``)
+         *and* ``oauth_client_secret`` together.
+    1. **OAuth M2M** — ``oauth_client_id`` + ``oauth_client_secret``
+       both present → forward raw creds to the kernel's ``oauth-m2m``.
+    2. **PAT** — the built provider is (or wraps) an
+       ``AccessTokenAuthProvider`` → extract the bearer token.
+    3. **OAuth U2M** — ``auth_type`` is ``databricks-oauth`` /
+       ``azure-oauth`` → forward optional ``oauth_client_id`` /
+       ``oauth_redirect_port`` to the kernel's ``oauth-u2m``.
+    4. **Custom credentials_provider** → ``NotSupportedError`` (opaque
+       token source; no raw creds for the kernel to own).
+    5. Anything else → ``NotSupportedError``.
+
+    M2M is checked before PAT so that a workload passing both an
+    access token *and* M2M creds resolves to the (refreshing) M2M path
+    rather than a static token. (Token + M2M is not treated as
+    ambiguous: a PAT is often present as ambient config the caller
+    didn't intend as the primary credential, whereas an explicit
+    ``oauth_client_secret`` is unambiguous M2M intent.)
+    """
+    opts = auth_options or {}
+
+    client_id = opts.get("oauth_client_id")
+    client_secret = opts.get("oauth_client_secret")
+    auth_type = opts.get("auth_type")
+    has_m2m = bool(client_id and client_secret)
+
+    # 0. Ambiguity guards — fail before any flow is chosen.
+    if client_secret and opts.get("credentials_provider") is not None:
+        raise NotSupportedError(
+            "Ambiguous auth on use_kernel=True: both a custom "
+            "credentials_provider and oauth_client_secret were provided. "
+            "Pass exactly one — oauth_client_id + oauth_client_secret for "
+            "kernel-managed M2M, or use the Thrift backend (default) for "
+            "credentials_provider."
+        )
+    if client_secret and auth_type in ("databricks-oauth", "azure-oauth"):
+        raise NotSupportedError(
+            f"Ambiguous auth on use_kernel=True: auth_type={auth_type!r} selects "
+            "the U2M browser flow, but oauth_client_secret was also provided "
+            "(machine-to-machine). Drop oauth_client_secret for U2M, or drop "
+            "auth_type for M2M."
+        )
+
+    # 1. OAuth M2M — raw client-credentials pair forwarded to the kernel.
+    if has_m2m:
+        kwargs: Dict[str, Any] = {
+            "auth_type": "oauth-m2m",
+            "client_id": client_id,
+            "client_secret": client_secret,
+        }
+        scopes = _normalize_scopes(opts.get("oauth_scopes"))
+        if scopes is not None:
+            kwargs["oauth_scopes"] = scopes
+        return kwargs
+
+    # 2. PAT (including TokenFederationProvider-wrapped PAT).
+    if _is_pat(auth_provider):
+        token = _extract_bearer_token(auth_provider)
+        if not token:
+            raise ProgrammingError(
+                "PAT auth provider did not produce a Bearer Authorization "
+                "header; cannot route through the kernel's PAT path"
+            )
+        return {"auth_type": "pat", "access_token": token}
+
+    # 3. OAuth U2M — browser authorization-code flow; the kernel runs it.
+    if auth_type in ("databricks-oauth", "azure-oauth"):
+        kwargs = {"auth_type": "oauth-u2m"}
+        if client_id:
+            kwargs["client_id"] = client_id
+        redirect_port = opts.get("oauth_redirect_port")
+        if redirect_port is not None:
+            kwargs["redirect_port"] = int(redirect_port)
+        scopes = _normalize_scopes(opts.get("oauth_scopes"))
+        if scopes is not None:
+            kwargs["oauth_scopes"] = scopes
+        return kwargs
+
+    # 4. Custom credentials_provider — the connector's primary M2M path
+    #    on Thrift/SEA, but unusable on the kernel: it's an opaque token
+    #    source with no extractable client_id/secret, so the kernel
+    #    can't own the token lifecycle. Point the caller at the raw
+    #    M2M kwargs instead.
+    if opts.get("credentials_provider") is not None:
+        raise NotSupportedError(
+            "use_kernel=True does not support a custom credentials_provider. "
+            "For OAuth machine-to-machine auth, pass oauth_client_id and "
+            "oauth_client_secret so the kernel can manage the token lifecycle "
+            "directly; or use the Thrift backend (default) with "
+            "credentials_provider."
+        )
+
+    # 5. Everything else (including no usable credentials at all —
+    #    ``auth_provider`` is None on the kernel path when no access
+    #    token was supplied and no OAuth kwargs resolved above).
+    provider_desc = (
+        type(auth_provider).__name__ if auth_provider is not None else "no credentials"
+    )
+    raise NotSupportedError(
+        f"use_kernel=True requires PAT (access_token), OAuth M2M "
+        f"(oauth_client_id + oauth_client_secret), or OAuth U2M "
+        f"(auth_type='databricks-oauth' / 'azure-oauth'), but got "
+        f"{provider_desc} with auth_type={auth_type!r}. Use the Thrift "
+        "backend (default) for other auth flows."
+    )
+
+
+def _normalize_scopes(scopes: Any) -> Optional[list]:
+    """Normalise an ``oauth_scopes`` value to a list of strings, or
+    ``None`` to let the kernel apply its defaults.
+
+    Accepts a list/tuple of strings or a single space-delimited string
+    (the shape ``DatabricksOAuthProvider`` stores internally)."""
+    if scopes is None:
+        return None
+    if isinstance(scopes, str):
+        parts = scopes.split()
+        return parts or None
+    if isinstance(scopes, (list, tuple)):
+        parts = [str(s) for s in scopes if s]
+        return parts or None
+    # Anything else (int, dict, bool, …) is a caller error. Fail loudly
+    # rather than silently dropping the scopes to None and surprising
+    # the user with default scopes.
+    raise ProgrammingError(
+        f"oauth_scopes must be a list/tuple of strings or a space-delimited "
+        f"string, got {type(scopes).__name__}."
+    )