From 0e8ef87dc824dcd83dca01641441afc453c8e07a Mon Sep 17 00:00:00 2001 From: jason3gb Date: Wed, 16 Jun 2021 22:16:16 +0800 Subject: [PATCH] add doc and changelog --- doc/build/changelog/unreleased_14/6583.rst | 9 ++++++++ doc/build/orm/contextual.rst | 3 ++- doc/build/orm/extensions/asyncio.rst | 25 ++++++++++++++++++++++ 3 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 doc/build/changelog/unreleased_14/6583.rst diff --git a/doc/build/changelog/unreleased_14/6583.rst b/doc/build/changelog/unreleased_14/6583.rst new file mode 100644 index 0000000000..1c7af9ab84 --- /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 fd55846220..aebcfc3ff3 100644 --- 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 92471d459e..856c1e8063 100644 --- 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: -- 2.47.3