Document every public API in pyathena/ and check docstrings with ruff

AGENTS.md

@@ -134,4 +134,5 @@ Versions are derived from git tags via `hatch-vcs` — never edit `pyathena/_ver
 
 ### Google-style Docstrings
 
-Use Google-style docstrings for public methods. See existing code for examples.
+Follow the [docstring rules](docs/contributing.md#write-docstrings), which `just lint` checks with ruff's pydocstyle rules for `pyathena/`.
+Mark overrides with `pyathena.util.override` instead of repeating the base method's docstring.

docs/contributing.md

@@ -71,6 +71,23 @@ External-fork pull requests must not be run in the project's AWS integration CI.
 Do not submit an untested change expecting a maintainer to approve an AWS CI run to validate it.
 Checks that need no AWS access may still run, but their success does not establish integration coverage.
 
+## Write docstrings
+
+Code under `pyathena/` uses [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
+`just lint` checks them with ruff's pydocstyle rules.
+
+- Modules, packages, public classes, and public functions and methods have a docstring.
+  Describe arguments, return values, and raised exceptions in `Args:`, `Returns:`, and `Raises:` sections.
+- `__init__` describes the constructor arguments in its `Args:` section.
+- A property getter has a one-line docstring; its setter needs none.
+- Magic methods such as `__enter__` and `__iter__` need no docstring.
+- A method that overrides a base class method is decorated with `override` from `pyathena.util`.
+  It needs a docstring only when its behavior differs from the base method; otherwise the API reference shows the base method's docstring.
+  mypy reports a missing decorator, except on an unannotated property.
+- Overrides of fsspec methods are not decorated, because fsspec has no type information, so they need a docstring.
+- New or changed private functions and methods use the same style.
+  ruff does not require them to have a docstring, but checks the docstrings they have.
+
 ## Open a pull request
 
 Open a draft pull request with the repository's template completed.

docs/usage.md

@@ -320,6 +320,7 @@ Result columns from a passthrough query come back with the source system's types
 PyAthena provides a callback mechanism that allows you to get immediate access to the query ID
 as soon as the `start_query_execution` API call is made, before waiting for query completion.
 This is useful for monitoring, logging, or cancelling long-running queries from another thread.
+When `cache_size` finds a reusable query, no new query starts, and the callback receives the reused query's ID.
 
 The `on_start_query_execution` callback can be configured at both the connection level and
 the execute level. When both are set, both callbacks will be invoked.

pyathena/__init__.py

@@ -1,3 +1,5 @@
+"""DB API 2.0 interface to Amazon Athena: ``connect()``, ``aio_connect()``, and type objects."""
+
 from __future__ import annotations
 
 import datetime
@@ -30,7 +32,7 @@
 
 
 class DBAPITypeObject(frozenset[str]):
-    """Type Objects and Constructors
+    """A DB API type object that compares equal to each of its Athena type names.
 
     https://www.python.org/dev/peps/pep-0249/#type-objects-and-constructors
     """
@@ -89,6 +91,8 @@ def connect(*args, **kwargs) -> Connection[Any]:
     SQL queries.
 
     Args:
+        *args: Positional arguments passed to the Connection constructor, in the
+            order of its parameters (``s3_staging_dir``, ``region_name``, ...).
         s3_staging_dir: S3 location to store query results. Required if not
             using workgroups or if the workgroup doesn't have a result location.
             Pass an empty string to explicitly disable S3 staging and skip
@@ -144,6 +148,8 @@ async def aio_connect(*args, **kwargs) -> AioConnection:
     and API calls, keeping the event loop free.
 
     Args:
+        *args: Forwarded to ``AioConnection.create()``, which accepts keyword
+            arguments only.
         **kwargs: Arguments forwarded to ``AioConnection.create()``.
             See :func:`connect` for the full list of supported arguments.
 

pyathena/aio/__init__.py

@@ -0,0 +1,8 @@
+# Copyright 2026 The PyAthena authors
+#
+# Licensed under the MIT License.
+# See LICENSE or https://opensource.org/licenses/MIT.
+#
+# SPDX-License-Identifier: MIT
+
+"""Native asyncio connections and cursors for Amazon Athena."""

pyathena/aio/arrow/__init__.py

@@ -0,0 +1,8 @@
+# Copyright 2026 The PyAthena authors
+#
+# Licensed under the MIT License.
+# See LICENSE or https://opensource.org/licenses/MIT.
+#
+# SPDX-License-Identifier: MIT
+
+"""Native asyncio cursor that returns Athena query results as Apache Arrow tables."""

pyathena/aio/arrow/cursor.py

@@ -1,3 +1,5 @@
+"""Native asyncio cursor that returns Athena query results as Apache Arrow tables."""
+
 from __future__ import annotations
 
 import asyncio
@@ -54,6 +56,28 @@ def __init__(
         request_timeout: float | None = None,
         **kwargs,
     ) -> None:
+        """Initialize an AioArrowCursor.
+
+        Args:
+            s3_staging_dir: S3 location for query results.
+            schema_name: Default schema name.
+            catalog_name: Default catalog name.
+            work_group: Athena workgroup name.
+            poll_interval: Query status polling interval in seconds.
+            encryption_option: S3 encryption option for query results.
+            kms_key: KMS key for encrypting query results.
+            kill_on_interrupt: Cancel the query when the task is cancelled while
+                ``execute()`` starts or waits for the query.
+            unload: Whether to wrap queries in ``UNLOAD`` and read the Parquet output.
+            result_reuse_enable: Whether to enable Athena query result reuse.
+            result_reuse_minutes: Maximum age of a reused query result in minutes.
+            connect_timeout: Connection timeout in seconds of the pyarrow S3 filesystem
+                that reads the results. If None, the pyarrow default is used.
+            request_timeout: Request timeout in seconds of the pyarrow S3 filesystem
+                that reads the results. If None, the pyarrow default is used.
+            **kwargs: Other cursor arguments, such as ``connection`` and ``arraysize``,
+                passed to the parent ``__init__``.
+        """
         super().__init__(
             s3_staging_dir=s3_staging_dir,
             schema_name=schema_name,
@@ -111,7 +135,9 @@ async def execute(
             result_reuse_enable: Enable Athena result reuse for this query.
             result_reuse_minutes: Minutes to reuse cached results.
             paramstyle: Parameter style ('qmark' or 'pyformat').
-            on_start_query_execution: Callback called when query starts.
+            on_start_query_execution: Callback invoked with the query ID before ``execute()``
+                waits for the query: after the ``StartQueryExecution`` call, or after a
+                reusable query ID is found through ``cache_size``.
             result_set_type_hints: Optional dictionary mapping column names to
                 Athena DDL type signatures for precise type conversion within
                 complex types.

pyathena/aio/common.py

@@ -1,3 +1,5 @@
+"""Asyncio base cursor and the fetch mixin shared by the asyncio SQL cursors."""
+
 from __future__ import annotations
 
 import asyncio

pyathena/aio/connection.py

@@ -5,6 +5,8 @@
 #
 # SPDX-License-Identifier: MIT
 
+"""Asyncio-aware connection to Amazon Athena."""
+
 from __future__ import annotations
 
 import asyncio
@@ -31,6 +33,12 @@ class AioConnection(Connection[AioCursor]):
     """
 
     def __init__(self, **kwargs: Any) -> None:
+        """Initialize the connection with ``AioCursor`` as the default cursor class.
+
+        Args:
+            **kwargs: Arguments forwarded to ``Connection.__init__``. If they do not
+                include ``cursor_class``, it is set to ``AioCursor``.
+        """
         if "cursor_class" not in kwargs:
             kwargs["cursor_class"] = AioCursor
         super().__init__(**kwargs)

pyathena/aio/cursor.py

@@ -5,6 +5,8 @@
 #
 # SPDX-License-Identifier: MIT
 
+"""Native asyncio cursors that return rows as tuples or dictionaries."""
+
 from __future__ import annotations
 
 import logging
@@ -50,6 +52,24 @@ def __init__(
         result_reuse_minutes: int = CursorIterator.DEFAULT_RESULT_REUSE_MINUTES,
         **kwargs,
     ) -> None:
+        """Initialize an AioCursor.
+
+        Args:
+            s3_staging_dir: S3 location for query results.
+            schema_name: Default schema name.
+            catalog_name: Default catalog name.
+            work_group: Athena workgroup name.
+            poll_interval: Query status polling interval in seconds.
+            encryption_option: S3 encryption option (SSE_S3, SSE_KMS, CSE_KMS).
+            kms_key: KMS key for encryption.
+            kill_on_interrupt: Cancel the query when the task is cancelled while
+                ``execute()`` starts or waits for the query.
+            result_reuse_enable: Enable Athena query result reuse.
+            result_reuse_minutes: Maximum age in minutes of a reused result.
+            **kwargs: Arguments forwarded to ``WithResultSet.__init__`` and
+                ``AioBaseCursor.__init__``, such as ``arraysize``, ``connection``,
+                ``converter``, ``formatter``, and ``retry_config``.
+        """
         super().__init__(
             s3_staging_dir=s3_staging_dir,
             schema_name=schema_name,
@@ -104,12 +124,14 @@ async def execute(
             parameters: Query parameters (optional).
             work_group: Athena workgroup to use (optional).
             s3_staging_dir: S3 location for query results (optional).
-            cache_size: Query result cache size (optional).
+            cache_size: Number of queries to check for result caching (optional).
             cache_expiration_time: Cache expiration time in seconds (optional).
             result_reuse_enable: Enable result reuse (optional).
             result_reuse_minutes: Result reuse duration in minutes (optional).
             paramstyle: Parameter style to use (optional).
-            on_start_query_execution: Callback called when query starts.
+            on_start_query_execution: Callback invoked with the query ID before ``execute()``
+                waits for the query: after the ``StartQueryExecution`` call, or after a
+                reusable query ID is found through ``cache_size``.
             result_set_type_hints: Optional dictionary mapping column names to
                 Athena DDL type signatures for precise type conversion within
                 complex types.
@@ -225,6 +247,13 @@ class AioDictCursor(AioCursor):
     """
 
     def __init__(self, **kwargs) -> None:
+        """Initialize an AioDictCursor.
+
+        Args:
+            **kwargs: Arguments forwarded to ``AioCursor.__init__``. If they include
+                ``dict_type``, it is also assigned to the class attribute
+                ``AthenaAioDictResultSet.dict_type``, the type used to build each row.
+        """
         super().__init__(**kwargs)
         self._result_set_class = AthenaAioDictResultSet
         if "dict_type" in kwargs:

pyathena/aio/pandas/__init__.py

@@ -0,0 +1,8 @@
+# Copyright 2026 The PyAthena authors
+#
+# Licensed under the MIT License.
+# See LICENSE or https://opensource.org/licenses/MIT.
+#
+# SPDX-License-Identifier: MIT
+
+"""Native asyncio cursor that returns Athena query results as pandas DataFrames."""

pyathena/aio/pandas/cursor.py

@@ -1,3 +1,5 @@
+"""Native asyncio cursor that returns Athena query results as pandas DataFrames."""
+
 from __future__ import annotations
 
 import asyncio
@@ -63,6 +65,32 @@ def __init__(
         auto_optimize_chunksize: bool = False,
         **kwargs,
     ) -> None:
+        """Initialize an AioPandasCursor.
+
+        Args:
+            s3_staging_dir: S3 location for query results.
+            schema_name: Default schema name.
+            catalog_name: Default catalog name.
+            work_group: Athena workgroup name.
+            poll_interval: Query status polling interval in seconds.
+            encryption_option: S3 encryption option for query results.
+            kms_key: KMS key for encrypting query results.
+            kill_on_interrupt: Cancel the query when the task is cancelled while
+                ``execute()`` starts or waits for the query.
+            unload: Whether to wrap queries in ``UNLOAD`` and read the Parquet output.
+            engine: Parsing engine (``auto``, ``c``, ``python``, or ``pyarrow``).
+            chunksize: Number of rows per DataFrame chunk when reading CSV results. If set,
+                it takes precedence over ``auto_optimize_chunksize``.
+            block_size: Default block size of the S3 filesystem that reads the results.
+            cache_type: Default cache type of the S3 filesystem that reads the results.
+            max_workers: Maximum number of workers of the S3 filesystem.
+            result_reuse_enable: Whether to enable Athena query result reuse.
+            result_reuse_minutes: Maximum age of a reused query result in minutes.
+            auto_optimize_chunksize: Whether to choose a chunk size from the size of the
+                CSV result file when ``chunksize`` is None.
+            **kwargs: Other cursor arguments, such as ``connection`` and ``arraysize``,
+                passed to the parent ``__init__``.
+        """
         super().__init__(
             s3_staging_dir=s3_staging_dir,
             schema_name=schema_name,
@@ -130,7 +158,9 @@ async def execute(
             keep_default_na: Whether to keep default pandas NA values.
             na_values: Additional values to treat as NA.
             quoting: CSV quoting behavior (pandas csv.QUOTE_* constants).
-            on_start_query_execution: Callback called when query starts.
+            on_start_query_execution: Callback invoked with the query ID before ``execute()``
+                waits for the query: after the ``StartQueryExecution`` call, or after a
+                reusable query ID is found through ``cache_size``.
             result_set_type_hints: Optional dictionary mapping column names to
                 Athena DDL type signatures for precise type conversion within
                 complex types.

pyathena/aio/polars/__init__.py

@@ -0,0 +1,8 @@
+# Copyright 2026 The PyAthena authors
+#
+# Licensed under the MIT License.
+# See LICENSE or https://opensource.org/licenses/MIT.
+#
+# SPDX-License-Identifier: MIT
+
+"""Native asyncio cursor that returns Athena query results as Polars DataFrames."""

pyathena/aio/polars/cursor.py

@@ -1,3 +1,5 @@
+"""Native asyncio cursor that returns Athena query results as Polars DataFrames."""
+
 from __future__ import annotations
 
 import asyncio
@@ -58,6 +60,29 @@ def __init__(
         chunksize: int | None = None,
         **kwargs,
     ) -> None:
+        """Initialize an AioPolarsCursor.
+
+        Args:
+            s3_staging_dir: S3 location for query results.
+            schema_name: Default schema name.
+            catalog_name: Default catalog name.
+            work_group: Athena workgroup name.
+            poll_interval: Query status polling interval in seconds.
+            encryption_option: S3 encryption option for query results.
+            kms_key: KMS key for encrypting query results.
+            kill_on_interrupt: Cancel the query when the task is cancelled while
+                ``execute()`` starts or waits for the query.
+            unload: Whether to wrap queries in ``UNLOAD`` and read the Parquet output.
+            result_reuse_enable: Whether to enable Athena query result reuse.
+            result_reuse_minutes: Maximum age of a reused query result in minutes.
+            block_size: Default block size of the S3 filesystem that reads the results.
+            cache_type: Default cache type of the S3 filesystem that reads the results.
+            max_workers: Maximum number of workers of the S3 filesystem.
+            chunksize: Number of rows per chunk. If set, result files in S3 are read
+                lazily in chunks of this size.
+            **kwargs: Other cursor arguments, such as ``connection`` and ``arraysize``,
+                passed to the parent ``__init__``.
+        """
         super().__init__(
             s3_staging_dir=s3_staging_dir,
             schema_name=schema_name,
@@ -117,7 +142,9 @@ async def execute(
             result_reuse_enable: Enable Athena result reuse for this query.
             result_reuse_minutes: Minutes to reuse cached results.
             paramstyle: Parameter style ('qmark' or 'pyformat').
-            on_start_query_execution: Callback called when query starts.
+            on_start_query_execution: Callback invoked with the query ID before ``execute()``
+                waits for the query: after the ``StartQueryExecution`` call, or after a
+                reusable query ID is found through ``cache_size``.
             result_set_type_hints: Optional dictionary mapping column names to
                 Athena DDL type signatures for precise type conversion within
                 complex types.

pyathena/aio/result_set.py

@@ -1,3 +1,5 @@
+"""Asyncio result sets that fetch Athena query results with ``GetQueryResults``."""
+
 from __future__ import annotations
 
 import logging
@@ -39,6 +41,21 @@ def __init__(
         retry_config: RetryConfig,
         result_set_type_hints: dict[str | int, str] | None = None,
     ) -> None:
+        """Initialize the result set without fetching rows; ``create()`` fetches the first page.
+
+        Args:
+            connection: The connection that ran the query.
+            converter: The converter for result values.
+            query_execution: The query execution whose results to read.
+            arraysize: The number of rows per ``GetQueryResults`` page and the default
+                ``fetchmany()`` size.
+            retry_config: The retry configuration for API calls.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
+
+        Raises:
+            ProgrammingError: If ``query_execution`` is not given.
+        """
         super().__init__(
             connection=connection,
             converter=converter,

pyathena/aio/s3fs/__init__.py

@@ -0,0 +1,8 @@
+# Copyright 2026 The PyAthena authors
+#
+# Licensed under the MIT License.
+# See LICENSE or https://opensource.org/licenses/MIT.
+#
+# SPDX-License-Identifier: MIT
+
+"""Native asyncio cursor that reads Athena CSV query results through ``AioS3FileSystem``."""