add doc and changelog

diff --git a/doc/build/changelog/unreleased_14/6583.rst b/doc/build/changelog/unreleased_14/6583.rst
new file mode 100644 (file)
index 0000000..1c7af9a
--- /dev/null
+++ b/doc/build/changelog/unreleased_14/6583.rst
@@ -0,0 +1,9 @@
+.. change::
+    :tags: usecase, asyncio
+    :tickets: 6583
+
+    Implement a new :class:`_asyncio.async_scoped_session` to address some incompatible method interface
+    between :class:`.scoped_session` and :class:`_asyncio.AsyncSession`, in which some
+    method (e.g. remove) should be used with the async keyword async/await. Additionally, In order to avoid code
+    redundancy, a :class:`_ScopedSessionMixin` is created and inherited in both :class:`.scoped_session`
+    and :class:`_asyncio.async_scoped_session`.

diff --git a/doc/build/orm/contextual.rst b/doc/build/orm/contextual.rst
index fd55846220a32a130d7914327730aeb757e501ad..aebcfc3ff307b507d5f7dff1a287decb1206fe13 100644 (file)
--- a/doc/build/orm/contextual.rst
+++ b/doc/build/orm/contextual.rst
@@ -252,7 +252,8 @@ Contextual Session API
 ----------------------
 
 .. autoclass:: sqlalchemy.orm.scoping.scoped_session
-   :members:
+    :members:
+    :inherited-members:
 
 .. autoclass:: sqlalchemy.util.ScopedRegistry
     :members:

diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst
index 92471d459ea374985b324c5c3914b159448fcfc4..856c1e80636a5d8ea60df8a7228f114b5c5e9e00 100644 (file)
--- a/doc/build/orm/extensions/asyncio.rst
+++ b/doc/build/orm/extensions/asyncio.rst
@@ -417,6 +417,27 @@ from using any connection more than once::
 
 .. currentmodule:: sqlalchemy.ext.asyncio
 
+Using asyncio scoped session
+----------------------------
+
+The usage of :class:`_asyncio.async_scoped_session` is mostly similar to :class:`.scoped_session`.
+However, since there's no "thread-local" concept in the asyncio context, the "scopefunc" paramater
+must be provided during initialization. Additionally, :class:`_asyncio.async_scoped_session` also
+include **proxy behavior** like :class:`.scoped_session`, which means it can be treated as a
+:class:`_asyncio.AsyncSession` directly::
+
+    from asyncio import current_task
+
+    from sqlalchemy.orm import sessionmaker
+    from sqlalchemy.ext.asyncio import async_scoped_session
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    async_session_factory = sessionmaker(some_async_engine, class_=_AsyncSession)
+    AsyncSession = async_scoped_session(async_session_factory, scopefunc=current_task)
+
+    some_async_session = AsyncSession()
+
+
 Engine API Documentation
 -------------------------
 
@@ -456,6 +477,10 @@ ORM Session API Documentation
 
 .. autofunction:: async_session
 
+.. autoclass:: async_scoped_session
+   :members:
+   :inherited-members:
+
 .. autoclass:: AsyncSession
    :members: