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

2 files changed, 41 insertions, 16 deletions

diff --git a/lib/sqlalchemy/ext/asyncio/engine.py b/lib/sqlalchemy/ext/asyncio/engine.py
index 4d0c872b3..19ef4d3a1 100644
--- a/lib/sqlalchemy/ext/asyncio/engine.py
+++ b/lib/sqlalchemy/ext/asyncio/engine.py
@@ -352,7 +352,7 @@ class AsyncConnection(
         This returns this :class:`_asyncio.AsyncConnection` object with
         the new options added.
 
-        See :meth:`_future.Connection.execution_options` for full details
+        See :meth:`_engine.Connection.execution_options` for full details
         on this method.
 
         """
@@ -369,9 +369,9 @@ class AsyncConnection(
         If no transaction was started, the method has no effect, assuming
         the connection is in a non-invalidated state.
 
-        A transaction is begun on a :class:`_future.Connection` automatically
+        A transaction is begun on a :class:`_engine.Connection` automatically
         whenever a statement is first executed, or when the
-        :meth:`_future.Connection.begin` method is called.
+        :meth:`_engine.Connection.begin` method is called.
 
         """
         await greenlet_spawn(self._proxied.commit)
@@ -384,9 +384,9 @@ class AsyncConnection(
         transaction was started and the connection is in an invalidated state,
         the transaction is cleared using this method.
 
-        A transaction is begun on a :class:`_future.Connection` automatically
+        A transaction is begun on a :class:`_engine.Connection` automatically
         whenever a statement is first executed, or when the
-        :meth:`_future.Connection.begin` method is called.
+        :meth:`_engine.Connection.begin` method is called.
 
 
         """
@@ -519,7 +519,7 @@ class AsyncConnection(
         :param execution_options: optional dictionary of execution options,
          which will be associated with the statement execution.  This
          dictionary can provide a subset of the options that are accepted
-         by :meth:`_future.Connection.execution_options`.
+         by :meth:`_engine.Connection.execution_options`.
 
         :return: a :class:`_engine.Result` object.
 
@@ -564,7 +564,7 @@ class AsyncConnection(
 
         This method is shorthand for invoking the
         :meth:`_engine.Result.scalar` method after invoking the
-        :meth:`_future.Connection.execute` method.  Parameters are equivalent.
+        :meth:`_engine.Connection.execute` method.  Parameters are equivalent.
 
         :return: a scalar Python value representing the first column of the
          first row returned.
@@ -606,7 +606,7 @@ class AsyncConnection(
 
         This method is shorthand for invoking the
         :meth:`_engine.Result.scalars` method after invoking the
-        :meth:`_future.Connection.execute` method.  Parameters are equivalent.
+        :meth:`_engine.Connection.execute` method.  Parameters are equivalent.
 
         :return: a :class:`_engine.ScalarResult` object.
 
@@ -650,7 +650,7 @@ class AsyncConnection(
 
         This method is shorthand for invoking the
         :meth:`_engine.AsyncResult.scalars` method after invoking the
-        :meth:`_future.Connection.stream` method.  Parameters are equivalent.
+        :meth:`_engine.Connection.stream` method.  Parameters are equivalent.
 
         :return: an :class:`_asyncio.AsyncScalarResult` object.
 
@@ -931,7 +931,7 @@ class AsyncEngine(ProxyComparable[Engine], AsyncConnectable):
         :class:`_asyncio.AsyncConnection` objects with the given execution
         options.
 
-        Proxied from :meth:`_future.Engine.execution_options`.  See that
+        Proxied from :meth:`_engine.Engine.execution_options`.  See that
         method for details.
 
         """
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