Correct docstrings that contradict the implementation

pyathena/aio/arrow/cursor.py

@@ -138,9 +138,8 @@ async def execute(
             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.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.

pyathena/aio/common.py

@@ -815,7 +815,8 @@ async def fetchmany(
         blocking the event loop.
 
         Args:
-            size: Maximum number of rows to fetch. Defaults to arraysize.
+            size: Maximum number of rows to fetch. If None or not positive,
+                ``arraysize`` is used.
 
         Returns:
             List of tuples representing the fetched rows.

pyathena/aio/cursor.py

@@ -32,7 +32,7 @@ class AioCursor(WithAsyncFetch):
     calls, keeping the event loop free.
 
     Example:
-        >>> async with AioConnection.create(...) as conn:
+        >>> async with await AioConnection.create(...) as conn:
         ...     async with conn.cursor() as cursor:
         ...         await cursor.execute("SELECT * FROM my_table")
         ...         rows = await cursor.fetchall()
@@ -133,9 +133,8 @@ async def execute(
             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.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.
@@ -188,7 +187,8 @@ async def fetchone(
         """Fetch the next row of a query result set.
 
         Returns:
-            A tuple representing the next row, or None if no more rows.
+            The next row (a tuple, or a dict for ``AioDictCursor``), or None if
+            no more rows.
 
         Raises:
             ProgrammingError: If called before executing a query that
@@ -204,10 +204,11 @@ async def fetchmany(self, size: int | None = None) -> list[Any | dict[Any, Any |
         """Fetch multiple rows from a query result set.
 
         Args:
-            size: Maximum number of rows to fetch. If None, uses arraysize.
+            size: Maximum number of rows to fetch. If None or not positive,
+                ``arraysize`` is used.
 
         Returns:
-            List of tuples representing the fetched rows.
+            The fetched rows.
 
         Raises:
             ProgrammingError: If called before executing a query that
@@ -225,7 +226,7 @@ async def fetchall(
         """Fetch all remaining rows from a query result set.
 
         Returns:
-            List of tuples representing all remaining rows in the result set.
+            The remaining rows.
 
         Raises:
             ProgrammingError: If called before executing a query that
@@ -241,7 +242,7 @@ class AioDictCursor(AioCursor):
     """Native asyncio cursor that returns rows as dictionaries.
 
     Example:
-        >>> async with AioConnection.create(...) as conn:
+        >>> async with await AioConnection.create(...) as conn:
         ...     cursor = conn.cursor(AioDictCursor)
         ...     await cursor.execute("SELECT id, name FROM users")
         ...     row = await cursor.fetchone()

pyathena/aio/pandas/cursor.py

@@ -161,9 +161,8 @@ async def execute(
             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.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.

pyathena/aio/polars/cursor.py

@@ -145,9 +145,8 @@ async def execute(
             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.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.

pyathena/aio/result_set.py

@@ -87,8 +87,8 @@ async def create(
             query_execution: Query execution metadata.
             arraysize: Number of rows to fetch per request.
             retry_config: Retry configuration for API calls.
-            result_set_type_hints: Optional dictionary mapping column names to
-                Athena DDL type signatures for precise type conversion.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             **kwargs: Additional arguments passed to the constructor of ``cls``,
                 such as ``dict_type`` for ``AthenaAioDictResultSet``.
 
@@ -179,7 +179,8 @@ async def fetchone(  # type: ignore[override]
         page is exhausted and more pages are available.
 
         Returns:
-            A tuple representing the next row, or None if no more rows.
+            The next row (a tuple, or a dict for ``AthenaAioDictResultSet``), or
+            None if no more rows.
         """
         if not self._rows and self._next_token:
             await self._async_fetch()
@@ -197,11 +198,11 @@ async def fetchmany(  # type: ignore[override]
         """Fetch multiple rows from the result set.
 
         Args:
-            size: Maximum number of rows to fetch. If None, uses arraysize.
+            size: Maximum number of rows to fetch. If None or not positive,
+                ``arraysize`` is used.
 
         Returns:
-            List of row tuples. May contain fewer rows than requested if
-            fewer are available.
+            The rows, fewer than ``size`` when the result is exhausted.
         """
         if not size or size <= 0:
             size = self._arraysize
@@ -221,7 +222,7 @@ async def fetchall(  # type: ignore[override]
         """Fetch all remaining rows from the result set.
 
         Returns:
-            List of all remaining row tuples.
+            The remaining rows.
         """
         rows = []
         while True:

pyathena/aio/s3fs/cursor.py

@@ -141,9 +141,8 @@ async def execute(
             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.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.

pyathena/arrow/async_cursor.py

@@ -206,9 +206,8 @@ 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').
-            result_set_type_hints: Optional dictionary mapping column names to
-                Athena DDL type signatures for precise type conversion within
-                complex types.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.

pyathena/arrow/cursor.py

@@ -45,13 +45,13 @@ class ArrowCursor(WithFetch):
         >>> from pyathena.arrow.cursor import ArrowCursor
         >>> cursor = connection.cursor(ArrowCursor)
         >>> cursor.execute("SELECT * FROM large_table")
-        >>> table = cursor.fetchall()  # Returns pyarrow.Table
+        >>> table = cursor.as_arrow()  # Returns pyarrow.Table
         >>> df = table.to_pandas()  # Convert to pandas if needed
 
         # High-performance UNLOAD for large datasets
         >>> cursor = connection.cursor(ArrowCursor, unload=True)
         >>> cursor.execute("SELECT * FROM huge_table")
-        >>> table = cursor.fetchall()  # Faster Parquet-based result
+        >>> table = cursor.as_arrow()  # Faster Parquet-based result
     """
 
     def __init__(
@@ -164,9 +164,8 @@ def execute(
             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.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.

pyathena/arrow/result_set.py

@@ -50,7 +50,7 @@ class AthenaArrowResultSet(AthenaResultSet):
         >>> cursor.execute("SELECT * FROM large_table")
         >>>
         >>> # Get Arrow Table
-        >>> table = cursor.fetchall()
+        >>> table = cursor.as_arrow()
         >>>
         >>> # Convert to pandas if needed
         >>> df = table.to_pandas()

pyathena/async_cursor.py

@@ -29,18 +29,16 @@ class AsyncCursor(BaseCursor):
     provides methods to check query status and retrieve results when ready.
 
     Attributes:
-        description: Sequence of column descriptions for the last query.
-        rowcount: Number of rows affected by the last query (-1 for SELECT queries).
-        arraysize: Default number of rows to fetch with fetchmany().
-        max_workers: Maximum number of worker threads for concurrent execution.
+        arraysize: Default number of rows that fetchmany() returns on the result
+            sets this cursor creates.
 
     Example:
         >>> cursor = connection.cursor(AsyncCursor)
         >>>
         >>> # Execute multiple queries concurrently
-        >>> future1 = cursor.execute("SELECT COUNT(*) FROM table1")
-        >>> future2 = cursor.execute("SELECT COUNT(*) FROM table2")
-        >>> future3 = cursor.execute("SELECT COUNT(*) FROM table3")
+        >>> query_id1, future1 = cursor.execute("SELECT COUNT(*) FROM table1")
+        >>> query_id2, future2 = cursor.execute("SELECT COUNT(*) FROM table2")
+        >>> query_id3, future3 = cursor.execute("SELECT COUNT(*) FROM table3")
         >>>
         >>> # Check if queries are done and get results
         >>> if future1.done():
@@ -50,8 +48,10 @@ class AsyncCursor(BaseCursor):
         >>> results = [f.result().fetchall() for f in [future1, future2, future3]]
 
     Note:
-        Each execute() call returns a Future object that can be used to
-        check completion status and retrieve results.
+        Each execute() call returns a ``(query_id, future)`` tuple. The future
+        resolves to the result set, which provides the column descriptions and
+        the fetch methods. ``description(query_id)`` also returns the column
+        descriptions as a Future.
     """
 
     def __init__(
@@ -235,9 +235,8 @@ def execute(
             result_reuse_enable: Enable result reuse for identical queries (optional).
             result_reuse_minutes: Result reuse duration in minutes (optional).
             paramstyle: Parameter style to use (optional).
-            result_set_type_hints: Optional dictionary mapping column names to
-                Athena DDL type signatures for precise type conversion within
-                complex types.
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual
                 keyword arguments take precedence over ``options`` fields.
@@ -331,9 +330,9 @@ class AsyncDictCursor(AsyncCursor):
 
     Example:
         >>> cursor = connection.cursor(AsyncDictCursor)
-        >>> future = cursor.execute("SELECT id, name, email FROM users")
-        >>> result_cursor = future.result()
-        >>> row = result_cursor.fetchone()
+        >>> query_id, future = cursor.execute("SELECT id, name, email FROM users")
+        >>> result_set = future.result()
+        >>> row = result_set.fetchone()
         >>> print(f"User: {row['name']} ({row['email']})")
     """
 

pyathena/converter.py

@@ -501,7 +501,6 @@ class Converter(metaclass=ABCMeta):
 
     Attributes:
         mappings: Dictionary mapping Athena type names to conversion functions.
-        default: Default conversion function for unmapped types.
         types: Optional dictionary mapping type names to Python type objects.
     """
 

pyathena/cursor.py

@@ -33,7 +33,7 @@ class Cursor(WithFetch):
 
     Example:
         >>> cursor = connection.cursor()
-        >>> cursor.execute("SELECT name, age FROM users WHERE age > %s", (18,))
+        >>> cursor.execute("SELECT name, age FROM users WHERE age > %(age)s", {"age": 18})
         >>> while True:
         ...     row = cursor.fetchone()
         ...     if not row:
@@ -141,9 +141,9 @@ def execute(
                 Function signature: (query_id: str) -> None
                 This allows early access to query_id for
                 monitoring/cancellation.
-            result_set_type_hints: Optional dictionary mapping column names to
-                Athena DDL type signatures for precise type conversion within
-                complex types. For example:
+            result_set_type_hints: Athena type signatures for complex-type columns,
+                keyed by column name (case-insensitive) or zero-based column index.
+                For example:
                 ``{"tags": "array(varchar)", "metadata": "map(varchar, integer)"}``
             options: Shared execution options as an
                 :class:`~pyathena.options.ExecuteOptions` instance. Individual

pyathena/filesystem/s3.py

@@ -66,10 +66,6 @@ class S3FileSystem(AbstractFileSystem):
       (e.g., ``404`` -> ``FileNotFoundError``, ``403`` -> ``PermissionError``)
 
     Attributes:
-        session: The boto3 session used for S3 operations.
-        client: The S3 client for direct API calls.
-        config: Boto3 configuration for the client.
-        retry_config: Configuration for retry behavior on failed operations.
         allow_bucket_creation: Whether mkdir/makedirs may create buckets.
             Defaults to False.
         allow_bucket_deletion: Whether rmdir may delete buckets.

pyathena/filesystem/s3_async.py

@@ -46,8 +46,8 @@ class AioS3FileSystem(AsyncFileSystem):
     This avoids diamond inheritance issues and keeps all boto3 logic in one place.
 
     File handles created by ``_open`` use ``S3AioExecutor`` so that parallel
-    operations (range reads, multipart uploads) are dispatched via the event loop
-    instead of spawning additional threads.
+    operations (range reads, multipart uploads) are dispatched through the event
+    loop with ``asyncio.to_thread`` instead of a ``ThreadPoolExecutor`` per file.
 
     Attributes:
         _sync_fs: The internal synchronous S3FileSystem instance.
@@ -59,8 +59,9 @@ class AioS3FileSystem(AsyncFileSystem):
         >>> # Use in async context
         >>> files = await fs._ls('s3://my-bucket/data/')
         >>>
-        >>> # Sync wrappers also available (auto-generated by fsspec)
-        >>> files = fs.ls('s3://my-bucket/data/')
+        >>> # Sync wrappers (auto-generated by fsspec) need an instance created
+        >>> # without asynchronous=True; they block the caller until done
+        >>> files = AioS3FileSystem().ls('s3://my-bucket/data/')
     """
 
     # https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html
@@ -587,5 +588,6 @@ class AioS3File(S3File):
     ``isinstance`` checks and to document the async execution model.
     All parallel operations (range reads, multipart uploads) are dispatched
     through the ``S3Executor`` interface — the ``S3AioExecutor``
-    provided by ``AioS3FileSystem`` uses the event loop instead of threads.
+    provided by ``AioS3FileSystem`` dispatches them through the event loop with
+    ``asyncio.to_thread`` instead of a ``ThreadPoolExecutor`` per file.
     """

pyathena/filesystem/s3_object.py

@@ -63,6 +63,8 @@ class S3StorageClass:
         - DEEP_ARCHIVE: Lowest cost archive storage
         - GLACIER_IR: Archive with faster retrieval than standard Glacier
         - OUTPOSTS: Storage on AWS Outposts
+        - BUCKET: Pseudo storage class PyAthena assigns to bucket entries
+        - DIRECTORY: Pseudo storage class PyAthena assigns to directory entries
 
     See Also:
         AWS S3 storage classes documentation: