Add async SQLAlchemy dialects for native asyncio support

[laughingman7743]

Summary

Closes #673.

Add async SQLAlchemy dialects enabling create_async_engine usage with PyAthena for frameworks like FastAPI.

Connection string	Dialect	Cursor
awsathena+aiorest://	AthenaAioRestDialect	AioCursor
awsathena+aiopandas://	AthenaAioPandasDialect	AioPandasCursor
awsathena+aioarrow://	AthenaAioArrowDialect	AioArrowCursor
awsathena+aiopolars://	AthenaAioPolarsDialect	AioPolarsCursor
awsathena+aios3fs://	AthenaAioS3FSDialect	AioS3FSCursor

Changes

• Core adapter layer (pyathena/aio/sqlalchemy/base.py):
  • AsyncAdapt_pyathena_cursor — wraps async cursors with sync DBAPI interface, eagerly buffers results in deque during execute() (same pattern as asyncpg/aiosqlite/asyncmy)
  • AsyncAdapt_pyathena_connection — wraps AioConnection as AdaptedConnection
  • AsyncAdapt_pyathena_dbapi — fake DBAPI module with connect() and exception hierarchy
  • AthenaAioDialect — base async dialect (is_async=True, AsyncAdaptedQueuePool)
• Variant dialects: aiorest, aiopandas, aioarrow, aiopolars, aios3fs — each sets cursor_class and extracts cursor-specific URL parameters
• Entry points registered in pyproject.toml + aiosqlalchemy optional dependency (sqlalchemy[asyncio]>=2.0.0)
• Tests: basic query parametrized across all 5 async drivers, Unicode, table reflection, schema inspection, column metadata
• Documentation: async usage, connection strings, dialect table, and run_sync() reflection examples integrated into docs/sqlalchemy.md
• Dependency: greenlet upgraded 3.1.1 → 3.3.2 (fixes Python 3.14 build failure)

Key design decisions

• Cursor-class-agnostic adapter: The DBAPI adapter wraps whatever async cursor AioConnection.cursor() returns, so variant dialects only need to set cursor_class in create_connect_args()
• Eager result buffering: SQLAlchemy calls fetch methods outside the greenlet context, so execute() eagerly fetches all rows into a deque buffer — this is the standard pattern used by asyncpg, aiosqlite, and asyncmy
• Reflection compatibility: get_driver_connection() returns the adapted connection itself (not the raw AioConnection), so reflection methods work through the adapted cursor's sync wrappers
• Naming convention: Adapter classes follow SQLAlchemy's AsyncAdapt_{driver}_{role} naming (e.g. AsyncAdapt_asyncpg_dbapi)

Related

• Fix mypy errors with SQLAlchemy 2.0.46+ type signature changes #680 — SQLAlchemy 2.0.46+ upgrade blocked by mypy compatibility issue (tracked separately)

Test plan

• make fmt && make chk passes (lint + mypy)
• Async SQLAlchemy tests pass locally (11/11 green)
• CI passes on Python 3.10–3.14
• Per-driver parametrized test_basic_query for all 5 async drivers
• Schema reflection works via run_sync() in async context

🤖 Generated with Claude Code