refactor(sqlalchemy): adopt SA dialect+driver URL convention

Switch the wrapper's SQLAlchemy dialect registration from a parallel
top-level dialect name (aws_wrapper_postgresql+psycopg, aws_wrapper_mysql+
mysqlconnector, ...) to SA's idiomatic <dialect>+<driver> form, so the
wrapper plugs in as a driver under the stock postgresql/mysql dialects.
This matches the AWS-approved ORM PR aws#1224 convention and removes the
two-conventions-for-one-wrapper inconsistency the merge would otherwise
leave. Done now because the branch is unreleased -- no public URL is broken.

Entry points (3, was 8):
- postgresql.aws_wrapper_psycopg      -> sync AND async
- mysql.aws_wrapper_mysqlconnector    -> sync
- mysql.aws_wrapper_aiomysql          -> async

PostgreSQL serves both sync and async from ONE URL
(postgresql+aws_wrapper_psycopg://): psycopg3 is a single DBAPI that does
both, so AwsWrapperPGPsycopgDialect implements get_async_dialect_cls to
return the async dialect. create_async_engine drives
URL.get_dialect(_is_async=True) -> that hook (verified against SA 2.0.49);
create_engine uses the sync class. Mirrors stock postgresql+psycopg.

MySQL needs two driver names because its sync (mysql-connector-python) and
async (aiomysql) paths are different DBAPIs that cannot share a URL. The
async name drops the redundant _async suffix (aiomysql is async-only),
mirroring stock mysql+aiomysql.

Dialect classes: driver attrs updated (aws_wrapper_psycopg /
aws_wrapper_mysqlconnector / aws_wrapper_aiomysql); PG async keeps the
sync driver name since it is reached via the hook, not a distinct URL.

Updated: unit tests (test_sqlalchemy_dialects, test_aio_sqlalchemy_dialect,
test_aio_aiomysql) -- the async-PG registry-key tests become
get_async_dialect_cls resolution tests; integration helpers + test URLs;
SqlAlchemySupport.md (rewrote the Naming section), IntegrationTests.md,
the *AsyncFailover examples, and dialect/submodule docstrings.

Note: editable installs must `poetry install` to refresh
entry_points.txt after this change (stale metadata otherwise resolves the
old names).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: AhmadMasry

aws_advanced_python_wrapper/aio/aiomysql.py

@@ -16,7 +16,7 @@
 
 Async counterpart of :mod:`aws_advanced_python_wrapper.mysql_connector`.
 Enables SQLAlchemy's ``create_async_engine`` with the custom dialect
-``aws_wrapper_mysql+aiomysql_async`` registered in Task 2-C.
+``mysql+aws_wrapper_aiomysql``.
 
 Module-level attributes are populated via :func:`_dbapi.install`;
 PEP 562 ``__getattr__`` forwards missing attrs to the real

aws_advanced_python_wrapper/aio/psycopg.py

@@ -22,7 +22,7 @@
     from aws_advanced_python_wrapper.aio.psycopg import connect
 
     engine = create_async_engine(
-        "postgresql+psycopg_async://",
+        "postgresql+aws_wrapper_psycopg://",
         async_creator=lambda: connect(
             "host=... user=... dbname=...",
             wrapper_dialect="aurora-pg",

aws_advanced_python_wrapper/sqlalchemy_dialects/__init__.py

@@ -16,6 +16,6 @@
 AWS Advanced Python Wrapper.
 
 Users should prefer the SA dialect registry
-(``create_engine("aws-wrapper-postgresql+psycopg://...")``) over importing
+(``create_engine("postgresql+aws_wrapper_psycopg://...")``) over importing
 these classes directly.
 """

aws_advanced_python_wrapper/sqlalchemy_dialects/mysql.py

@@ -14,9 +14,9 @@
 
 """MySQL SQLAlchemy dialect bound to the AWS Advanced Python Wrapper.
 
-Registered as ``aws-wrapper-mysql`` / ``aws-wrapper-mysql+mysqlconnector``
-via a pyproject entry-point. Subclasses SA's standard
-MySQLDialect_mysqlconnector and only swaps the DBAPI module to
+Registered as ``mysql.aws_wrapper_mysqlconnector`` via a pyproject
+entry-point (URL ``mysql+aws_wrapper_mysqlconnector://``). Subclasses SA's
+standard MySQLDialect_mysqlconnector and only swaps the DBAPI module to
 :mod:`aws_advanced_python_wrapper.mysql_connector`, which routes connect()
 through the wrapper's plugin pipeline.
 """
@@ -36,7 +36,7 @@ class AwsWrapperMySQLConnectorDialect(
         _FailoverSuccessRewrapMixin, MySQLDialect_mysqlconnector):
     """SQLAlchemy dialect that uses the AWS Advanced Python Wrapper as its DBAPI."""
 
-    driver = "mysqlconnector"
+    driver = "aws_wrapper_mysqlconnector"
     supports_statement_cache = True
 
     # See _FailoverSuccessRewrapMixin / sqlalchemy_dialects/pg.py for the

aws_advanced_python_wrapper/sqlalchemy_dialects/mysql_async.py

@@ -14,19 +14,21 @@
 
 """Async MySQL SQLAlchemy dialect bound to the AWS Advanced Python Wrapper.
 
-Registered as ``aws_wrapper_mysql_async`` /
-``aws_wrapper_mysql+aiomysql_async`` via pyproject entry-points.
-Subclasses SA's standard ``MySQLDialect_aiomysql`` and swaps the DBAPI
-to an adapter that routes ``connect()`` through the async plugin pipeline
-while preserving SA's ``AsyncAdapt_aiomysql_connection`` greenlet-bridge
-wrapper that the async engine expects.
+Registered as ``mysql.aws_wrapper_aiomysql`` via a pyproject entry-point
+(URL ``mysql+aws_wrapper_aiomysql://``). aiomysql is an async-only DBAPI, so
+unlike PG this needs a distinct driver name from the sync
+``mysql+aws_wrapper_mysqlconnector`` (the two are different DBAPIs and cannot
+share one URL). Subclasses SA's standard ``MySQLDialect_aiomysql`` and swaps
+the DBAPI to an adapter that routes ``connect()`` through the async plugin
+pipeline while preserving SA's ``AsyncAdapt_aiomysql_connection``
+greenlet-bridge wrapper that the async engine expects.
 
 Example::
 
     from sqlalchemy.ext.asyncio import create_async_engine
 
     engine = create_async_engine(
-        "aws_wrapper_mysql+aiomysql_async://user:pwd@"
+        "mysql+aws_wrapper_aiomysql://user:pwd@"
         "database.cluster-xyz.us-east-1.rds.amazonaws.com:3306/db"
         "?wrapper_dialect=aurora-mysql&wrapper_plugins=failover"
     )
@@ -93,7 +95,7 @@ class AwsWrapperMySQLAiomysqlAsyncDialect(
         _AsyncFailoverSuccessRewrapMixin, MySQLDialect_aiomysql):
     """Async SQLAlchemy dialect that uses the AWS Advanced Python Wrapper as its DBAPI."""
 
-    driver = "aiomysql_async"
+    driver = "aws_wrapper_aiomysql"
     supports_statement_cache = True
     is_async = True
 

aws_advanced_python_wrapper/sqlalchemy_dialects/pg.py

@@ -14,10 +14,13 @@
 
 """PostgreSQL SQLAlchemy dialect bound to the AWS Advanced Python Wrapper.
 
-Registered as ``aws-wrapper-postgresql`` / ``aws-wrapper-postgresql+psycopg``
-via a pyproject entry-point. Subclasses SA's standard PGDialect_psycopg and
-only swaps the DBAPI module to :mod:`aws_advanced_python_wrapper.psycopg`,
-which routes connect() through the wrapper's plugin pipeline.
+Registered as ``postgresql.aws_wrapper_psycopg`` via a pyproject entry-point
+(URL ``postgresql+aws_wrapper_psycopg://``). The same URL serves both sync
+and async: this class implements ``get_async_dialect_cls`` so
+``create_async_engine`` swaps in the async dialect. Subclasses SA's standard
+PGDialect_psycopg and only swaps the DBAPI module to
+:mod:`aws_advanced_python_wrapper.psycopg`, which routes connect() through
+the wrapper's plugin pipeline.
 """
 
 from __future__ import annotations
@@ -50,7 +53,7 @@ class AwsWrapperPGPsycopgDialect(_FailoverSuccessRewrapMixin, PGDialect_psycopg)
     psycopg. Current overrides: ``_type_info_fetch``.
     """
 
-    driver = "psycopg"
+    driver = "aws_wrapper_psycopg"
     supports_statement_cache = True
 
     # See _FailoverSuccessRewrapMixin. SA's classifier checks
@@ -69,6 +72,21 @@ def import_dbapi(cls):
         import aws_advanced_python_wrapper.psycopg as dbapi
         return dbapi
 
+    @classmethod
+    def get_async_dialect_cls(cls, url):
+        # psycopg3 is a single DBAPI that does both sync and async, so a
+        # single ``postgresql+aws_wrapper_psycopg://`` URL serves both. SA
+        # selects async purely by which factory the caller uses:
+        # ``create_async_engine`` resolves the dialect via
+        # ``URL.get_dialect(_is_async=True)`` -> this hook, while
+        # ``create_engine`` uses this (sync) class directly. Mirrors stock
+        # ``PGDialect_psycopg.get_async_dialect_cls``. Lazy import to avoid a
+        # module-load cycle. MySQL cannot do this -- its sync/async paths are
+        # different DBAPIs (mysql-connector-python vs aiomysql).
+        from aws_advanced_python_wrapper.sqlalchemy_dialects.pg_async import \
+            AwsWrapperPGPsycopgAsyncDialect
+        return AwsWrapperPGPsycopgAsyncDialect
+
     def create_connect_args(self, url):
         # SQLAlchemy's `create_engine` intercepts `plugins=` in the URL query
         # to load SA engine plugins, stripping it before the dialect sees it.

aws_advanced_python_wrapper/sqlalchemy_dialects/pg_async.py

@@ -14,19 +14,21 @@
 
 """Async PostgreSQL SQLAlchemy dialect bound to the AWS Advanced Python Wrapper.
 
-Registered as ``aws_wrapper_postgresql_async`` /
-``aws_wrapper_postgresql+psycopg_async`` via pyproject entry-points.
-Subclasses SA's standard ``PGDialectAsync_psycopg`` and swaps the DBAPI to
-an adapter that routes ``connect()`` through the async plugin pipeline
-while preserving SA's ``AsyncAdapt_psycopg_connection`` greenlet-bridge
-wrapper that the async engine expects.
+Reached via the sync dialect's ``get_async_dialect_cls`` hook, not a distinct
+URL: ``create_async_engine("postgresql+aws_wrapper_psycopg://...")`` resolves
+to this class (psycopg3 is a single DBAPI that does both sync and async, so
+one URL serves both -- mirrors stock ``postgresql+psycopg``). Subclasses SA's
+standard ``PGDialectAsync_psycopg`` and swaps the DBAPI to an adapter that
+routes ``connect()`` through the async plugin pipeline while preserving SA's
+``AsyncAdapt_psycopg_connection`` greenlet-bridge wrapper that the async
+engine expects.
 
 Example::
 
     from sqlalchemy.ext.asyncio import create_async_engine
 
     engine = create_async_engine(
-        "aws_wrapper_postgresql+psycopg_async://user:pwd@"
+        "postgresql+aws_wrapper_psycopg://user:pwd@"
         "database.cluster-xyz.us-east-1.rds.amazonaws.com:5432/db"
         "?wrapper_dialect=aurora-pg&wrapper_plugins=failover,host_monitoring_v2"
     )
@@ -130,7 +132,10 @@ class AwsWrapperPGPsycopgAsyncDialect(
     to psycopg. Current overrides: ``_type_info_fetch``.
     """
 
-    driver = "psycopg_async"
+    # Same driver name as the sync dialect: this class is reached via the
+    # sync dialect's ``get_async_dialect_cls`` (not a distinct URL), mirroring
+    # stock psycopg where both sync and async report ``driver = "psycopg"``.
+    driver = "aws_wrapper_psycopg"
     supports_statement_cache = True
 
     # See _AsyncFailoverSuccessRewrapMixin / sqlalchemy_dialects/pg.py.

docs/development-guide/IntegrationTests.md

@@ -66,7 +66,7 @@ unset FILTER  # Done testing the IAM tests, unset FILTER
 
 ## Running async integration tests
 
-The wrapper ships async counterparts to every sync integration test file. Async tests exercise `AsyncAwsWrapperConnection` (raw) and `create_async_engine` with the wrapper's async dialects (`aws_wrapper_postgresql+psycopg_async`, `aws_wrapper_mysql+aiomysql_async`). They are invoked via dedicated Gradle tasks, independent of the sync tasks:
+The wrapper ships async counterparts to every sync integration test file. Async tests exercise `AsyncAwsWrapperConnection` (raw) and `create_async_engine` with the wrapper's dialects (`postgresql+aws_wrapper_psycopg` — shared with sync via `get_async_dialect_cls`; `mysql+aws_wrapper_aiomysql`). They are invoked via dedicated Gradle tasks, independent of the sync tasks:
 
 | Deployment | Engine | Sync task | Async task |
 |---|---|---|---|

docs/examples/MySQLSQLAlchemyAsyncFailover.py

@@ -15,7 +15,7 @@
 """Async SQLAlchemy + AWS Advanced Python Wrapper: failover on Aurora MySQL.
 
 Uses aiomysql as the async MySQL driver. The dialect
-`aws_wrapper_mysql+aiomysql_async` routes create_async_engine through the
+`mysql+aws_wrapper_aiomysql` routes create_async_engine through the
 wrapper's async plugin pipeline.
 
 Wrapper plugins are configured via the `wrapper_plugins` URL alias
@@ -38,7 +38,7 @@
 
 def build_engine():
     return create_async_engine(
-        f"aws_wrapper_mysql+aiomysql_async://{USER}:{PASSWORD}@"
+        f"mysql+aws_wrapper_aiomysql://{USER}:{PASSWORD}@"
         f"{CLUSTER_ENDPOINT}:3306/{DB_NAME}"
         "?wrapper_dialect=aurora-mysql&wrapper_plugins=failover",
     )

docs/examples/PGSQLAlchemyAsyncFailover.py

@@ -14,10 +14,11 @@
 
 """Async SQLAlchemy + AWS Advanced Python Wrapper: failover on Aurora PostgreSQL.
 
-URL-based async engine usage (SP-9). The dialect `aws_wrapper_postgresql+psycopg_async`
-routes `create_async_engine` through `AsyncAwsWrapperConnection`, so all wrapper
-plugins (failover, host_monitoring_v2, etc. -- landing in later sub-projects) are available in
-async apps.
+URL-based async engine usage (SP-9). The `postgresql+aws_wrapper_psycopg` URL is
+shared with the sync engine -- `create_async_engine` selects the async dialect via
+the sync dialect's `get_async_dialect_cls` hook -- routing through
+`AsyncAwsWrapperConnection`, so all wrapper plugins (failover, host_monitoring_v2,
+etc.) are available in async apps.
 
 The wrapper's `plugins` connection property is spelled `wrapper_plugins` in the
 URL query string because SA reserves `plugins=` for its own engine-plugin loader.
@@ -40,7 +41,7 @@
 
 def build_engine():
     return create_async_engine(
-        f"aws_wrapper_postgresql+psycopg_async://{USER}:{PASSWORD}@"
+        f"postgresql+aws_wrapper_psycopg://{USER}:{PASSWORD}@"
         f"{CLUSTER_ENDPOINT}:5432/{DB_NAME}"
         "?wrapper_dialect=aurora-pg&wrapper_plugins=failover,host_monitoring_v2",
     )