Add async_engine_from_config()

Added :func:`_asyncio.async_engine_config` function to create
an async engine from a configuration dict.  This otherwise
behaves the same as :func:`_sa.engine_from_config`.

Fixes: #7301
Closes: #7302
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/7302
Pull-request-sha: c7c758833b6c37b7509b8c5bed4f26ac0ccc0395

Change-Id: I64feadf95b5015c24fe0fa0dbae6755b72d1713e

diff --git a/doc/build/changelog/unreleased_14/7301.rst b/doc/build/changelog/unreleased_14/7301.rst
new file mode 100644 (file)
index 0000000..a8a71af
--- /dev/null
+++ b/doc/build/changelog/unreleased_14/7301.rst
@@ -0,0 +1,7 @@
+.. change::
+    :tags: usecase, asyncio
+    :tickets: 7425
+
+    Added :func:`_asyncio.async_engine_config` function to create
+    an async engine from a configuration dict.  This otherwise
+    behaves the same as :func:`_sa.engine_from_config`.

diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index 91c7c53e1e9031c8e98523a8261521fc9d2dddda..a7d2fb16be793581028684695affedcc6b228b76 100644 (file)
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -732,6 +732,8 @@ Engine API Documentation
 
 .. autofunction:: create_async_engine
 
+.. autofunction:: async_engine_from_config
+
 .. autoclass:: AsyncEngine
    :members:
 

diff --git a/lib/sqlalchemy/ext/asyncio/__init__.py b/lib/sqlalchemy/ext/asyncio/__init__.py
index ac3b905c6159c2e5039f67daf3448b97442310ab..031039713758149f5d9bd11b76889dafd2fd4e75 100644 (file)
--- a/lib/sqlalchemy/ext/asyncio/__init__.py
+++ b/lib/sqlalchemy/ext/asyncio/__init__.py
@@ -5,6 +5,7 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: https://www.opensource.org/licenses/mit-license.php
 
+from .engine import async_engine_from_config
 from .engine import AsyncConnection
 from .engine import AsyncEngine
 from .engine import AsyncTransaction

diff --git a/lib/sqlalchemy/ext/asyncio/engine.py b/lib/sqlalchemy/ext/asyncio/engine.py
index 67d944b9ce608f0ce49de2389772b2244523975e..476d5515c319419d02d5fa4f598087f9a1837ef1 100644 (file)
--- a/lib/sqlalchemy/ext/asyncio/engine.py
+++ b/lib/sqlalchemy/ext/asyncio/engine.py
@@ -42,6 +42,29 @@ def create_async_engine(*arg, **kw):
     return AsyncEngine(sync_engine)
 
 
+def async_engine_from_config(configuration, prefix="sqlalchemy.", **kwargs):
+    """Create a new AsyncEngine instance using a configuration dictionary.
+
+    This function is analogous to the :func:`_sa.engine_from_config` function
+    in SQLAlchemy Core, except that the requested dialect must be an
+    asyncio-compatible dialect such as :ref:`dialect-postgresql-asyncpg`.
+    The argument signature of the function is identical to that
+    of :func:`_sa.engine_from_config`.
+
+    .. versionadded:: 1.4.29
+
+    """
+    options = {
+        key[len(prefix) :]: value
+        for key, value in configuration.items()
+        if key.startswith(prefix)
+    }
+    options["_coerce_config"] = True
+    options.update(kwargs)
+    url = options.pop("url")
+    return create_async_engine(url, **options)
+
+
 class AsyncConnectable:
     __slots__ = "_slots_dispatch", "__weakref__"
 

diff --git a/test/ext/asyncio/test_engine_py3k.py b/test/ext/asyncio/test_engine_py3k.py
index c65a51bf72b059f755a94922bd3e921942decf02..7e680bd0ec0fa9c422500419e7e6700150511e61 100644 (file)
--- a/test/ext/asyncio/test_engine_py3k.py
+++ b/test/ext/asyncio/test_engine_py3k.py
@@ -14,6 +14,7 @@ from sqlalchemy import Table
 from sqlalchemy import testing
 from sqlalchemy import text
 from sqlalchemy import union_all
+from sqlalchemy.ext.asyncio import async_engine_from_config
 from sqlalchemy.ext.asyncio import create_async_engine
 from sqlalchemy.ext.asyncio import engine as _async_engine
 from sqlalchemy.ext.asyncio import exc as asyncio_exc
@@ -588,6 +589,16 @@ class AsyncEngineTest(EngineFixture):
             server_side_cursors=True,
         )
 
+    def test_async_engine_from_config(self):
+        config = {
+            "sqlalchemy.url": str(testing.db.url),
+            "sqlalchemy.echo": "true",
+        }
+        engine = async_engine_from_config(config)
+        assert engine.url == testing.db.url
+        assert engine.echo is True
+        assert engine.dialect.is_async is True
+
 
 class AsyncEventTest(EngineFixture):
     """The engine events all run in their normal synchronous context.