Reject unknown cursor keyword arguments for PyAthena 4.0

Author: laughingman7743

docs/cursor.md

@@ -1,5 +1,26 @@
 # Cursor
 
+## Keyword arguments in 4.0.0
+
+Starting in 4.0.0, cursor constructors and `execute()` raise `TypeError` for unknown keyword arguments.
+Earlier versions silently ignored some extra arguments.
+Correct misspelled names and pass backend options to the cursor that supports them:
+
+```python
+cursor = connection.cursor(work_group="analytics")
+cursor.execute("SELECT 1", work_group="analytics")
+```
+
+The validation happens before starting a query or a Spark calculation.
+For native asyncio cursors, `execute()` validates arguments when awaited.
+Pandas and Polars cursors continue to accept their reader options, with names checked against the installed library and the selected CSV, UNLOAD, and chunking mode.
+Invalid values and combinations remain subject to the reader's validation.
+Arrow and S3FS cursors accept their supported result-set options; arbitrary reader options are rejected.
+
+Connection-level `on_start_query_execution` and `on_poll` remain accepted by every cursor constructor.
+The Future-based Async cursors and Spark cursors do not invoke `on_start_query_execution`.
+For reader options, such as pandas `parse_dates`, pass the option to `execute()` rather than the constructor.
+
 (default_cursor)=
 
 ## DefaultCursor

pyathena/_kwargs.py

@@ -0,0 +1,60 @@
+# Copyright 2026 The PyAthena authors
+#
+# Licensed under the MIT License.
+# See LICENSE or https://opensource.org/licenses/MIT.
+#
+# SPDX-License-Identifier: MIT
+
+"""Validation of keyword names forwarded by cursors."""
+
+from collections.abc import Callable, Collection
+from inspect import Parameter, signature
+from typing import Any
+
+
+def keyword_parameters(func: Callable[..., Any]) -> set[str]:
+    """Return the explicitly named parameters that accept keyword arguments.
+
+    Args:
+        func: The callable whose signature to inspect.
+
+    Returns:
+        Its positional-or-keyword and keyword-only parameter names.
+    """
+    return {
+        name
+        for name, parameter in signature(func).parameters.items()
+        if parameter.kind in (Parameter.POSITIONAL_OR_KEYWORD, Parameter.KEYWORD_ONLY)
+    }
+
+
+def constructor_keyword_parameters(cls: type[Any]) -> set[str]:
+    """Return explicit constructor keyword names across a class's MRO.
+
+    Args:
+        cls: The class whose forwarding constructors to inspect.
+
+    Returns:
+        The named constructor parameters, excluding ``self``.
+    """
+    names: set[str] = set()
+    for base in cls.__mro__:
+        if "__init__" in vars(base):
+            names.update(keyword_parameters(vars(base)["__init__"]))
+    return names - {"self"}
+
+
+def validate_kwargs(method: str, kwargs: dict[str, Any], allowed: Collection[str] = ()) -> None:
+    """Reject the first keyword name that a cursor does not support.
+
+    Args:
+        method: The method name included in the error.
+        kwargs: Extra keyword arguments given to the method.
+        allowed: The extra keyword names the method supports.
+
+    Raises:
+        TypeError: If a keyword name is not allowed.
+    """
+    for name in kwargs:
+        if name not in allowed:
+            raise TypeError(f"{method}() got an unexpected keyword argument '{name}'")

pyathena/aio/arrow/cursor.py

@@ -7,6 +7,7 @@
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any, cast
 
+from pyathena._kwargs import validate_kwargs
 from pyathena.aio.common import WithAsyncFetch
 from pyathena.arrow.converter import (
     DefaultArrowTypeConverter,
@@ -143,13 +144,19 @@ async def execute(
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.
-            **kwargs: Additional execution parameters.
+            **kwargs: Result-set overrides: ``block_size``, ``connect_timeout``,
+                and ``request_timeout``. Unknown names raise TypeError.
                 ``block_size`` sets the read block size for this query, and
                 ``connect_timeout`` and ``request_timeout`` override the cursor's values.
 
         Returns:
             Self reference for method chaining.
         """
+        validate_kwargs(
+            f"{type(self).__name__}.execute",
+            kwargs,
+            ("block_size", "connect_timeout", "request_timeout"),
+        )
         self._reset_state()
         options = ExecuteOptions.resolve(
             options,

pyathena/aio/cursor.py

@@ -13,6 +13,7 @@
 from collections.abc import Callable
 from typing import Any, cast
 
+from pyathena._kwargs import validate_kwargs
 from pyathena.aio.common import WithAsyncFetch
 from pyathena.aio.result_set import AthenaAioDictResultSet, AthenaAioResultSet
 from pyathena.common import CursorIterator
@@ -138,11 +139,12 @@ async def execute(
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.
-            **kwargs: Additional execution parameters.
+            **kwargs: Unknown keyword arguments raise TypeError.
 
         Returns:
             Self reference for method chaining.
         """
+        validate_kwargs(f"{type(self).__name__}.execute", kwargs)
         self._reset_state()
         options = ExecuteOptions.resolve(
             options,

pyathena/aio/pandas/cursor.py

@@ -21,7 +21,11 @@
     DefaultPandasTypeConverter,
     DefaultPandasUnloadTypeConverter,
 )
-from pyathena.pandas.result_set import AthenaPandasResultSet, PandasDataFrameIterator
+from pyathena.pandas.result_set import (
+    AthenaPandasResultSet,
+    PandasDataFrameIterator,
+    validate_execute_kwargs,
+)
 from pyathena.util import override
 
 if TYPE_CHECKING:
@@ -176,6 +180,7 @@ async def execute(
         Returns:
             Self reference for method chaining.
         """
+        validate_execute_kwargs(f"{type(self).__name__}.execute", kwargs, self._unload)
         self._reset_state()
         options = ExecuteOptions.resolve(
             options,

pyathena/aio/polars/cursor.py

@@ -17,7 +17,7 @@
     DefaultPolarsTypeConverter,
     DefaultPolarsUnloadTypeConverter,
 )
-from pyathena.polars.result_set import AthenaPolarsResultSet
+from pyathena.polars.result_set import AthenaPolarsResultSet, validate_execute_kwargs
 from pyathena.util import override
 
 if TYPE_CHECKING:
@@ -160,6 +160,12 @@ async def execute(
         Returns:
             Self reference for method chaining.
         """
+        validate_execute_kwargs(
+            f"{type(self).__name__}.execute",
+            kwargs,
+            self._unload,
+            kwargs.get("chunksize", self._chunksize),
+        )
         self._reset_state()
         options = ExecuteOptions.resolve(
             options,

pyathena/aio/s3fs/cursor.py

@@ -14,6 +14,7 @@
 from collections.abc import Callable
 from typing import Any
 
+from pyathena._kwargs import validate_kwargs
 from pyathena.aio.common import WithAsyncFetch
 from pyathena.common import CursorIterator
 from pyathena.error import OperationalError
@@ -146,13 +147,14 @@ async def execute(
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.
-            **kwargs: Additional execution parameters.
+            **kwargs: Supported S3FS result-set overrides. Unknown names raise TypeError.
                 ``block_size`` sets the read block size for this query, and
                 ``csv_reader`` overrides the cursor's value.
 
         Returns:
             Self reference for method chaining.
         """
+        validate_kwargs(f"{type(self).__name__}.execute", kwargs, ("block_size", "csv_reader"))
         self._reset_state()
         options = ExecuteOptions.resolve(
             options,

pyathena/aio/spark/cursor.py

@@ -14,6 +14,7 @@
 import uuid
 from typing import Any, cast
 
+from pyathena._kwargs import validate_kwargs
 from pyathena.aio.util import async_retry_api_call
 from pyathena.error import DatabaseError, NotSupportedError, OperationalError, ProgrammingError
 from pyathena.model import (
@@ -352,11 +353,12 @@ async def execute(
             description: Calculation description.
             client_request_token: Idempotency token.
             work_group: Unused, kept for API compatibility.
-            **kwargs: Additional parameters.
+            **kwargs: Unknown keyword arguments raise TypeError.
 
         Returns:
             Self reference for method chaining.
         """
+        validate_kwargs(f"{type(self).__name__}.execute", kwargs)
         # A failure below must not leave the previous calculation on the cursor.
         self._calculation_id = None
         self._calculation_execution = None

pyathena/aio/sqlalchemy/base.py

@@ -276,6 +276,11 @@ def cursor(self, cursor: Any = None, **kwargs: Any) -> AsyncAdapt_pyathena_curso
         raw_cursor = self._connection.cursor(_ASYNC_CURSOR_CLASSES.get(cursor, cursor), **kwargs)
         return AsyncAdapt_pyathena_cursor(raw_cursor)
 
+    def _internal_cursor(self, cursor: Any) -> AsyncAdapt_pyathena_cursor:
+        """Adapt an API cursor with the default backend's result settings excluded."""
+        raw_cursor = self._connection._internal_cursor(_ASYNC_CURSOR_CLASSES.get(cursor, cursor))
+        return AsyncAdapt_pyathena_cursor(raw_cursor)
+
     def close(self) -> None:
         """Close the wrapped connection."""
         self._connection.close()

pyathena/arrow/async_cursor.py

@@ -8,6 +8,7 @@
 from typing import Any, cast
 
 from pyathena import ProgrammingError
+from pyathena._kwargs import validate_kwargs
 from pyathena.arrow.converter import (
     DefaultArrowTypeConverter,
     DefaultArrowUnloadTypeConverter,
@@ -211,13 +212,19 @@ def execute(
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.
-            **kwargs: Additional execution parameters.
+            **kwargs: Result-set overrides: ``block_size``, ``connect_timeout``,
+                and ``request_timeout``. Unknown names raise TypeError.
                 ``block_size`` sets the read block size for this query, and
                 ``connect_timeout`` and ``request_timeout`` override the cursor's values.
 
         Returns:
             Tuple of (query_id, future) where future resolves to AthenaArrowResultSet.
         """
+        validate_kwargs(
+            f"{type(self).__name__}.execute",
+            kwargs,
+            ("block_size", "connect_timeout", "request_timeout"),
+        )
         options = ExecuteOptions.resolve(
             options,
             work_group=work_group,