Merge "new docs WIP"

7 files changed, 134 insertions, 41 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 6aa2e7b14..e6215540d 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -218,9 +218,9 @@ class Connection(Connectable):
           connection will remain in a real transaction unless the
           "AUTOCOMMIT" isolation level is used.
 
-          .. deprecated:: 1.4  The library-level "autocommit" feature is being
-             removed in favor of database driver "autocommit" which is
-             now widely available.  See the section :ref:`dbapi_autocommit`.
+          .. deprecated:: 1.4  The "autocommit" execution option is deprecated
+             and will be removed in SQLAlchemy 2.0.  See
+             :ref:`migration_20_autocommit` for discussion.
 
         :param compiled_cache: Available on: Connection.
           A dictionary where :class:`.Compiled` objects
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 42987932d..e7bfc25b7 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1017,6 +1017,10 @@ class Query(
         self.load_options += {"_invoke_all_eagers": value}
 
     # TODO: removed in 2.0, use with_parent standalone in filter
+    @util.deprecated_20(
+        ":meth:`_orm.Query.with_parent`",
+        alternative="Use the :func:`_orm.with_parent` standalone construct.",
+    )
     @util.preload_module("sqlalchemy.orm.relationships")
     def with_parent(self, instance, property=None, from_entity=None):  # noqa
         """Add filtering criterion that relates the given instance
@@ -2377,6 +2381,10 @@ class Query(
 
         self._set_select_from(from_obj, False)
 
+    @util.deprecated_20(
+        ":meth:`_orm.Query.select_entity_from`",
+        alternative="Use the :func:`_orm.aliased` construct instead",
+    )
     @_generative
     @_assertions(_no_clauseelement_condition)
     def select_entity_from(self, from_obj):
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 39e63296c..2574e2bbd 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -1914,6 +1914,12 @@ class Session(_SessionClassMethods):
                         "bind is ignored."
                     )
                 else:
+                    util.warn_deprecated_20(
+                        "This Session located a target engine via bound "
+                        "metadata; as this functionality will be removed in "
+                        "SQLAlchemy 2.0, an Engine object should be passed "
+                        "to the Session() constructor directly."
+                    )
                     return clause.bind
 
         if mapper:
@@ -1925,6 +1931,12 @@ class Session(_SessionClassMethods):
                         "bind is ignored."
                     )
                 else:
+                    util.warn_deprecated_20(
+                        "This Session located a target engine via bound "
+                        "metadata; as this functionality will be removed in "
+                        "SQLAlchemy 2.0, an Engine object should be passed "
+                        "to the Session() constructor directly."
+                    )
                     return mapper.persist_selectable.bind
 
         context = []
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index dc3e5f476..59f3fa86b 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -1641,12 +1641,9 @@ class TextClause(
             t = text("EXEC my_procedural_thing()").\
                     execution_options(autocommit=True)
 
-        Note that SQLAlchemy's usual "autocommit" behavior applies to
-        :func:`_expression.text` constructs implicitly - that is,
-        statements which begin
-        with a phrase such as ``INSERT``, ``UPDATE``, ``DELETE``,
-        or a variety of other phrases specific to certain backends, will
-        be eligible for autocommit if no transaction is in progress.
+        .. deprecated:: 1.4  The "autocommit" execution option is deprecated
+           and will be removed in SQLAlchemy 2.0.  See
+           :ref:`migration_20_autocommit` for discussion.
 
         :param text:
           the text of the SQL statement to be created.  Use ``:<param>``
@@ -3401,12 +3398,18 @@ class CollectionAggregate(UnaryExpression):
             # mysql '5 = ANY (SELECT value FROM table)'
             expr = 5 == any_(select(table.c.value))
 
-        .. versionadded:: 1.1
+        The operator is more conveniently available from any
+        :class:`_sql.ColumnElement` object that makes use of the
+        :class:`_types.ARRAY` datatype::
+
+            expr = mytable.c.somearray.any(5)
 
         .. seealso::
 
             :func:`_expression.all_`
 
+            :meth:`_types.ARRAY.any`
+
         """
 
         expr = coercions.expect(roles.ExpressionElementRole, expr)
@@ -3432,12 +3435,18 @@ class CollectionAggregate(UnaryExpression):
             # mysql '5 = ALL (SELECT value FROM table)'
             expr = 5 == all_(select(table.c.value))
 
-        .. versionadded:: 1.1
+        The operator is more conveniently available from any
+        :class:`_sql.ColumnElement` object that makes use of the
+        :class:`_types.ARRAY` datatype::
+
+            expr = mytable.c.somearray.all(5)
 
         .. seealso::
 
             :func:`_expression.any_`
 
+            :meth:`_types.ARRAY.Comparator.all`
+
         """
 
         expr = coercions.expect(roles.ExpressionElementRole, expr)
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index e9654fb1f..496f8d9fb 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -211,11 +211,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         objects that were
         explicitly specified.
 
-        .. versionchanged:: 1.0.0 setting the
-           :paramref:`_schema.Table.autoload_with`
-           parameter implies that :paramref:`_schema.Table.autoload`
-           will default
-           to True.
+        .. deprecated:: 1.4
+
+            The autoload parameter is deprecated and will be removed in
+            version 2.0.  Please use the
+            :paramref:`_schema.Table`autoload_with` parameter, passing an
+            engine or connection.
 
         .. seealso::
 
@@ -251,18 +252,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         :func:`_sa.inspect`
         against one, with which this :class:`_schema.Table`
         object will be reflected.
-        When set to a non-None value, it implies that
-        :paramref:`_schema.Table.autoload` is ``True``.   If left unset, but
-        :paramref:`_schema.Table.autoload` is explicitly set to ``True``,
-        an autoload
-        operation will attempt to proceed by locating an
-        :class:`_engine.Engine` or
-        :class:`_engine.Connection` bound to the underlying
-        :class:`_schema.MetaData` object.
-
-        .. seealso::
-
-            :paramref:`_schema.Table.autoload`
+        When set to a non-None value, the autoload process will take place
+        for this table against the given engine or connection.
 
     :param extend_existing: When ``True``, indicates that if this
         :class:`_schema.Table` is already present in the given
@@ -311,7 +302,6 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
             Table("mytable", metadata,
                         Column('y', Integer),
                         extend_existing=True,
-                        autoload=True,
                         autoload_with=engine
                     )
 
@@ -407,7 +397,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
 
             t = Table(
                 'sometable',
-                autoload=True,
+                autoload_with=engine,
                 listeners=[
                     ('column_reflect', listen_for_reflect)
                 ])
@@ -488,7 +478,13 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
         mustexist=(
             "1.4",
             "Deprecated alias of :paramref:`_schema.Table.must_exist`",
-        )
+        ),
+        autoload=(
+            "2.0",
+            "The autoload parameter is deprecated and will be removed in "
+            "version 2.0.  Please use the "
+            "autoload_with parameter, passing an engine or connection.",
+        ),
     )
     def __new__(cls, *args, **kw):
         if not args:
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index c78b1ec57..9440fc48b 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -4391,13 +4391,41 @@ class Select(
         and apply generatively, returning the newly resulting
         :class:`_expression.Select`.
 
-        .. versionchanged:: 1.4 :meth:`_expression.Select.join` now modifies
-           the FROM list of the :class:`.Select` object in place, rather than
-           implicitly producing a subquery.
+        E.g.::
+
+            stmt = select(user_table).join(address_table, user_table.c.id == address_table.c.user_id)
+
+        The above statement generages SQL similar to::
+
+            SELECT user.id, user.name FROM user JOIN address ON user.id = address.user_id
+
+        .. versionchanged:: 1.4 :meth:`_expression.Select.join` now creates
+           a :class:`_sql.Join` object between a :class:`_sql.FromClause`
+           source that is within the FROM clause of the existing SELECT,
+           and a given target :class:`_sql.FromClause`, and then adds
+           this :class:`_sql.Join` to the FROM clause of the newly generated
+           SELECT statement.    This is completely reworked from the behavior
+           in 1.3, which would instead create a subquery of the entire
+           :class:`_expression.Select` and then join that subquery to the
+           target.
+
+           This is a **backwards incompatible change** as the previous behavior
+           was mostly useless, producing an unnamed subquery rejected by
+           most databases in any case.   The new behavior is modeled after
+           that of the very successful :meth:`_orm.Query.join` method in the
+           ORM, in order to support the functionality of :class:`_orm.Query`
+           being available by using a :class:`_sql.Select` object with an
+           :class:`_orm.Session`.
+
+           See the notes for this change at :ref:`change_select_join`.
+
 
         :param target: target table to join towards
 
-        :param onclause: ON clause of the join.
+        :param onclause: ON clause of the join.  If omitted, an ON clause
+         is generated automatically based on the :class:`_schema.ForeignKey`
+         linkages between the two tables, if one can be unambiguously
+         determined, otherwise an error is raised.
 
         :param isouter: if True, generate LEFT OUTER join.  Same as
          :meth:`_expression.Select.outerjoin`.
@@ -4408,7 +4436,9 @@ class Select(
 
             :meth:`_expression.Select.join_from`
 
-        """
+            :meth:`_expression.Select.outerjoin`
+
+        """  # noqa: E501
         target = coercions.expect(
             roles.JoinTargetRole, target, apply_propagate_attrs=self
         )
@@ -4422,11 +4452,22 @@ class Select(
     def join_from(
         self, from_, target, onclause=None, isouter=False, full=False
     ):
-        r"""Create a SQL JOIN against this :class:`_expresson.Select`
+        r"""Create a SQL JOIN against this :class:`_expression.Select`
         object's criterion
         and apply generatively, returning the newly resulting
         :class:`_expression.Select`.
 
+        E.g.::
+
+            stmt = select(user_table, address_table).join_from(
+                user_table, address_table, user_table.c.id == address_table.c.user_id
+            )
+
+        The above statement generages SQL similar to::
+
+            SELECT user.id, user.name, address.id, address.email, address.user_id
+            FROM user JOIN address ON user.id = address.user_id
+
         .. versionadded:: 1.4
 
         :param from\_: the left side of the join, will be rendered in the
@@ -4446,7 +4487,8 @@ class Select(
 
             :meth:`_expression.Select.join`
 
-        """
+        """  # noqa: E501
+
         # note the order of parsing from vs. target is important here, as we
         # are also deriving the source of the plugin (i.e. the subject mapper
         # in an ORM query) which should favor the "from_" over the "target"
@@ -4470,8 +4512,29 @@ class Select(
         Parameters are the same as that of :meth:`_expression.Select.join`.
 
         .. versionchanged:: 1.4 :meth:`_expression.Select.outerjoin` now
-           modifies the FROM list of the :class:`.Select` object in place,
-           rather than implicitly producing a subquery.
+           creates a :class:`_sql.Join` object between a
+           :class:`_sql.FromClause` source that is within the FROM clause of
+           the existing SELECT, and a given target :class:`_sql.FromClause`,
+           and then adds this :class:`_sql.Join` to the FROM clause of the
+           newly generated SELECT statement.    This is completely reworked
+           from the behavior in 1.3, which would instead create a subquery of
+           the entire
+           :class:`_expression.Select` and then join that subquery to the
+           target.
+
+           This is a **backwards incompatible change** as the previous behavior
+           was mostly useless, producing an unnamed subquery rejected by
+           most databases in any case.   The new behavior is modeled after
+           that of the very successful :meth:`_orm.Query.join` method in the
+           ORM, in order to support the functionality of :class:`_orm.Query`
+           being available by using a :class:`_sql.Select` object with an
+           :class:`_orm.Session`.
+
+           See the notes for this change at :ref:`change_select_join`.
+
+        .. seealso::
+
+            :meth:`_expression.Select.join`
 
         """
         return self.join(target, onclause=onclause, isouter=True, full=full,)
diff --git a/lib/sqlalchemy/testing/warnings.py b/lib/sqlalchemy/testing/warnings.py
index d97447ec8..dbe22bb8d 100644
--- a/lib/sqlalchemy/testing/warnings.py
+++ b/lib/sqlalchemy/testing/warnings.py
@@ -58,6 +58,7 @@ def setup_filters():
         "dictionaries only.",
         r"The Connection.connect\(\) function/method is considered legacy",
         r".*DefaultGenerator.execute\(\)",
+        r"The autoload parameter is deprecated and will be removed ",
         #
         # result sets
         #
@@ -100,10 +101,14 @@ def setup_filters():
         # ORM Query
         #
         r"The Query\.get\(\) function",
-        # r"The Query\.from_self\(\) function",
+        r"The Query\.from_self\(\) function",
+        r"The Query\.with_parent\(\) function",
+        r"The Query\.with_parent\(\) function",
+        r"The Query\.select_entity_from\(\) function",
         #
         # ORM Session
         #
+        r"This Session located a target engine via bound metadata",
         r"The Session.autocommit parameter is deprecated ",
         r".*object is being merged into a Session along the backref "
         "cascade path",