the future is here

the autodoc for the "future" Engine / Connection were removed,
so all these links weren't working.   Replace all _future
for these with _engine.  There was just one _future pointing
to select, changed that separately.

Change-Id: Ib28270d8da8616b533953204e22eabee9388d620

1 files changed, 31 insertions, 6 deletions

diff --git a/lib/sqlalchemy/ext/asyncio/scoping.py b/lib/sqlalchemy/ext/asyncio/scoping.py
index 8d31dd07d..a2fec1c24 100644
--- a/lib/sqlalchemy/ext/asyncio/scoping.py
+++ b/lib/sqlalchemy/ext/asyncio/scoping.py
@@ -301,7 +301,7 @@ class async_scoped_session(Generic[_AS]):
         return self._proxied.__iter__()
 
     def add(self, instance: object, _warn: bool = True) -> None:
-        r"""Place an object in the ``Session``.
+        r"""Place an object into this :class:`_orm.Session`.
 
         .. container:: class_bases
 
@@ -313,11 +313,26 @@ class async_scoped_session(Generic[_AS]):
             Proxied for the :class:`_orm.Session` class on
             behalf of the :class:`_asyncio.AsyncSession` class.
 
-        Its state will be persisted to the database on the next flush
-        operation.
+        Objects that are in the :term:`transient` state when passed to the
+        :meth:`_orm.Session.add` method will move to the
+        :term:`pending` state, until the next flush, at which point they
+        will move to the :term:`persistent` state.
 
-        Repeated calls to ``add()`` will be ignored. The opposite of ``add()``
-        is ``expunge()``.
+        Objects that are in the :term:`detached` state when passed to the
+        :meth:`_orm.Session.add` method will move to the :term:`persistent`
+        state directly.
+
+        If the transaction used by the :class:`_orm.Session` is rolled back,
+        objects which were transient when they were passed to
+        :meth:`_orm.Session.add` will be moved back to the
+        :term:`transient` state, and will no longer be present within this
+        :class:`_orm.Session`.
+
+        .. seealso::
+
+            :meth:`_orm.Session.add_all`
+
+            :ref:`session_adding` - at :ref:`session_basics`
 
 
 
@@ -326,7 +341,7 @@ class async_scoped_session(Generic[_AS]):
         return self._proxied.add(instance, _warn=_warn)
 
     def add_all(self, instances: Iterable[object]) -> None:
-        r"""Add the given collection of instances to this ``Session``.
+        r"""Add the given collection of instances to this :class:`_orm.Session`.
 
         .. container:: class_bases
 
@@ -338,6 +353,16 @@ class async_scoped_session(Generic[_AS]):
             Proxied for the :class:`_orm.Session` class on
             behalf of the :class:`_asyncio.AsyncSession` class.
 
+        See the documentation for :meth:`_orm.Session.add` for a general
+        behavioral description.
+
+        .. seealso::
+
+            :meth:`_orm.Session.add`
+
+            :ref:`session_adding` - at :ref:`session_basics`
+
+
 
         """  # noqa: E501