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

6 files changed, 48 insertions, 23 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 1b07acab5..1ec307297 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -2603,13 +2603,13 @@ class RootTransaction(Transaction):
     accessible via the :attr:`_engine.Connection.get_transaction` method of
     :class:`_engine.Connection`.
 
-    In :term:`2.0 style` use, the :class:`_future.Connection` also employs
+    In :term:`2.0 style` use, the :class:`_engine.Connection` also employs
     "autobegin" behavior that will create a new
     :class:`_engine.RootTransaction` whenever a connection in a
     non-transactional state is used to emit commands on the DBAPI connection.
     The scope of the :class:`_engine.RootTransaction` in 2.0 style
-    use can be controlled using the :meth:`_future.Connection.commit` and
-    :meth:`_future.Connection.rollback` methods.
+    use can be controlled using the :meth:`_engine.Connection.commit` and
+    :meth:`_engine.Connection.rollback` methods.
 
 
     """
@@ -2865,7 +2865,7 @@ class Engine(
 
     This is the **SQLAlchemy 1.x version** of :class:`_engine.Engine`.  For
     the :term:`2.0 style` version, which includes  some API differences,
-    see :class:`_future.Engine`.
+    see :class:`_engine.Engine`.
 
     An :class:`_engine.Engine` object is instantiated publicly using the
     :func:`~sqlalchemy.create_engine` function.
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
 
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index ce7caa3ee..9577b4d26 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -280,7 +280,7 @@ class ORMExecuteState(util.MemoizedSlots):
 
     For an ORM selection as would
     be retrieved from :class:`_orm.Query`, this is an instance of
-    :class:`_future.select` that was generated from the ORM query.
+    :class:`_sql.select` that was generated from the ORM query.
     """
 
     parameters: Optional[_CoreAnyExecuteParams]
diff --git a/lib/sqlalchemy/sql/_selectable_constructors.py b/lib/sqlalchemy/sql/_selectable_constructors.py
index b661d6f47..a0dbb5fb5 100644
--- a/lib/sqlalchemy/sql/_selectable_constructors.py
+++ b/lib/sqlalchemy/sql/_selectable_constructors.py
@@ -456,7 +456,7 @@ def select(*entities: _ColumnsClauseArgument[Any], **__kw: Any) -> Select[Any]:
     .. versionadded:: 1.4 - The :func:`_sql.select` function now accepts
        column arguments positionally.   The top-level :func:`_sql.select`
        function will automatically use the 1.x or 2.x style API based on
-       the incoming arguments; using :func:`_future.select` from the
+       the incoming arguments; using :func:`_sql.select` from the
        ``sqlalchemy.future`` module will enforce that only the 2.x style
        constructor is used.
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 8de93c2b4..bdc884d7b 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -5068,7 +5068,7 @@ class Select(
     def filter(
         self: SelfSelect, *criteria: _ColumnExpressionArgument[bool]
     ) -> SelfSelect:
-        """A synonym for the :meth:`_future.Select.where` method."""
+        """A synonym for the :meth:`_sql.Select.where` method."""
 
         return self.where(*criteria)