Add future=True to create_engine/Session; unify select()

Several weeks of using the future_select() construct
has led to the proposal there be just one select() construct
again which features the new join() method, and otherwise accepts
both the 1.x and 2.x argument styles.   This would make
migration simpler and reduce confusion.

However, confusion may be increased by the fact that select().join()
is different  Current thinking is we may be better off
with a few hard behavioral changes to old and relatively unknown APIs
rather than trying to play both sides within two extremely similar
but subtly different APIs.  At the moment, the .join() thing seems
to be the only behavioral change that occurs without the user
taking any explicit steps.   Session.execute() will still
behave the old way as we are adding a future flag.

This change also adds the "future" flag to Session() and
session.execute(), so that interpretation of the incoming statement,
as well as that the new style result is returned, does not
occur for existing applications unless they add the use
of this flag.

The change in general is moving the "removed in 2.0" system
further along where we want the test suite to fully pass
even if the SQLALCHEMY_WARN_20 flag is set.

Get many tests to pass when SQLALCHEMY_WARN_20 is set; this
should be ongoing after this patch merges.

Improve the RemovedIn20 warning; these are all deprecated
"since" 1.4, so ensure that's what the messages read.
Make sure the inforamtion link is on all warnings.
Add deprecation warnings for parameters present and
add warnings to all FromClause.select() types of methods.

Fixes: #5379
Fixes: #5284
Change-Id: I765a0b912b3dcd0e995426427d8bb7997cbffd51
References: #5159

1 files changed, 48 insertions, 58 deletions

diff --git a/test/dialect/oracle/test_compiler.py b/test/dialect/oracle/test_compiler.py
index f73eb96c0..21a3b04ba 100644
--- a/test/dialect/oracle/test_compiler.py
+++ b/test/dialect/oracle/test_compiler.py
@@ -67,8 +67,8 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
     def test_subquery(self):
         t = table("sometable", column("col1"), column("col2"))
-        s = select([t]).subquery()
-        s = select([s.c.col1, s.c.col2])
+        s = select(t).subquery()
+        s = select(s.c.col1, s.c.col2)
 
         self.assert_compile(
             s,
@@ -107,7 +107,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         )
 
         included_parts = (
-            select([part.c.sub_part, part.c.part, part.c.quantity])
+            select(part.c.sub_part, part.c.part, part.c.quantity)
             .where(part.c.part == "p1")
             .cte(name="included_parts", recursive=True)
             .suffix_with(
@@ -121,19 +121,15 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         parts_alias = part.alias("p")
         included_parts = included_parts.union_all(
             select(
-                [
-                    parts_alias.c.sub_part,
-                    parts_alias.c.part,
-                    parts_alias.c.quantity,
-                ]
+                parts_alias.c.sub_part,
+                parts_alias.c.part,
+                parts_alias.c.quantity,
             ).where(parts_alias.c.part == incl_alias.c.sub_part)
         )
 
         q = select(
-            [
-                included_parts.c.sub_part,
-                func.sum(included_parts.c.quantity).label("total_quantity"),
-            ]
+            included_parts.c.sub_part,
+            func.sum(included_parts.c.quantity).label("total_quantity"),
         ).group_by(included_parts.c.sub_part)
 
         self.assert_compile(
@@ -153,10 +149,10 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
     def test_limit_one(self):
         t = table("sometable", column("col1"), column("col2"))
-        s = select([t])
+        s = select(t)
         c = s.compile(dialect=oracle.OracleDialect())
         assert t.c.col1 in set(c._create_result_map()["col1"][1])
-        s = select([t]).limit(10).offset(20)
+        s = select(t).limit(10).offset(20)
         self.assert_compile(
             s,
             "SELECT anon_1.col1, anon_1.col2 FROM "
@@ -175,8 +171,8 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
     def test_limit_one_firstrows(self):
         t = table("sometable", column("col1"), column("col2"))
-        s = select([t])
-        s = select([t]).limit(10).offset(20)
+        s = select(t)
+        s = select(t).limit(10).offset(20)
         self.assert_compile(
             s,
             "SELECT anon_1.col1, anon_1.col2 FROM "
@@ -193,9 +189,9 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
     def test_limit_two(self):
         t = table("sometable", column("col1"), column("col2"))
-        s = select([t]).limit(10).offset(20).subquery()
+        s = select(t).limit(10).offset(20).subquery()
 
-        s2 = select([s.c.col1, s.c.col2])
+        s2 = select(s.c.col1, s.c.col2)
         self.assert_compile(
             s2,
             "SELECT anon_1.col1, anon_1.col2 FROM "
@@ -229,7 +225,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
     def test_limit_three(self):
         t = table("sometable", column("col1"), column("col2"))
 
-        s = select([t]).limit(10).offset(20).order_by(t.c.col2)
+        s = select(t).limit(10).offset(20).order_by(t.c.col2)
         self.assert_compile(
             s,
             "SELECT anon_1.col1, anon_1.col2 FROM "
@@ -249,7 +245,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
     def test_limit_four(self):
         t = table("sometable", column("col1"), column("col2"))
 
-        s = select([t]).with_for_update().limit(10).order_by(t.c.col2)
+        s = select(t).with_for_update().limit(10).order_by(t.c.col2)
         self.assert_compile(
             s,
             "SELECT anon_1.col1, anon_1.col2 FROM (SELECT "
@@ -263,7 +259,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
     def test_limit_four_firstrows(self):
         t = table("sometable", column("col1"), column("col2"))
 
-        s = select([t]).with_for_update().limit(10).order_by(t.c.col2)
+        s = select(t).with_for_update().limit(10).order_by(t.c.col2)
         self.assert_compile(
             s,
             "SELECT /*+ FIRST_ROWS([POSTCOMPILE_ora_frow_1]) */ "
@@ -279,13 +275,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
     def test_limit_five(self):
         t = table("sometable", column("col1"), column("col2"))
 
-        s = (
-            select([t])
-            .with_for_update()
-            .limit(10)
-            .offset(20)
-            .order_by(t.c.col2)
-        )
+        s = select(t).with_for_update().limit(10).offset(20).order_by(t.c.col2)
         self.assert_compile(
             s,
             "SELECT anon_1.col1, anon_1.col2 FROM "
@@ -304,7 +294,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         t = table("sometable", column("col1"), column("col2"))
 
         s = (
-            select([t])
+            select(t)
             .limit(10)
             .offset(literal(10) + literal(20))
             .order_by(t.c.col2)
@@ -330,7 +320,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
         col = literal_column("SUM(ABC)").label("SUM(ABC)")
         tbl = table("my_table")
-        query = select([col]).select_from(tbl).order_by(col).limit(100)
+        query = select(col).select_from(tbl).order_by(col).limit(100)
 
         self.assert_compile(
             query,
@@ -342,7 +332,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
         col = literal_column("SUM(ABC)").label(quoted_name("SUM(ABC)", True))
         tbl = table("my_table")
-        query = select([col]).select_from(tbl).order_by(col).limit(100)
+        query = select(col).select_from(tbl).order_by(col).limit(100)
 
         self.assert_compile(
             query,
@@ -354,7 +344,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
         col = literal_column("SUM(ABC)").label("SUM(ABC)_")
         tbl = table("my_table")
-        query = select([col]).select_from(tbl).order_by(col).limit(100)
+        query = select(col).select_from(tbl).order_by(col).limit(100)
 
         self.assert_compile(
             query,
@@ -366,7 +356,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
         col = literal_column("SUM(ABC)").label(quoted_name("SUM(ABC)_", True))
         tbl = table("my_table")
-        query = select([col]).select_from(tbl).order_by(col).limit(100)
+        query = select(col).select_from(tbl).order_by(col).limit(100)
 
         self.assert_compile(
             query,
@@ -460,7 +450,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         table1 = table("mytable", column("myid"), column("name"))
 
         self.assert_compile(
-            select([table1.c.myid, table1.c.name])
+            select(table1.c.myid, table1.c.name)
             .where(table1.c.myid == 7)
             .with_for_update(nowait=True, of=table1.c.name)
             .limit(10),
@@ -476,7 +466,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         table1 = table("mytable", column("myid"), column("name"))
 
         self.assert_compile(
-            select([table1.c.myid])
+            select(table1.c.myid)
             .where(table1.c.myid == 7)
             .with_for_update(nowait=True, of=table1.c.name)
             .limit(10),
@@ -491,7 +481,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         table1 = table("mytable", column("myid"), column("name"))
 
         self.assert_compile(
-            select([table1.c.myid, table1.c.name])
+            select(table1.c.myid, table1.c.name)
             .where(table1.c.myid == 7)
             .with_for_update(nowait=True, of=table1.c.name)
             .limit(10)
@@ -511,7 +501,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         table1 = table("mytable", column("myid"), column("name"))
 
         self.assert_compile(
-            select([table1.c.myid])
+            select(table1.c.myid)
             .where(table1.c.myid == 7)
             .with_for_update(nowait=True, of=table1.c.name)
             .limit(10)
@@ -530,7 +520,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         table1 = table("mytable", column("myid"), column("foo"), column("bar"))
 
         self.assert_compile(
-            select([table1.c.myid, table1.c.bar])
+            select(table1.c.myid, table1.c.bar)
             .where(table1.c.myid == 7)
             .with_for_update(nowait=True, of=[table1.c.foo, table1.c.bar])
             .limit(10)
@@ -551,7 +541,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         class MyType(TypeDecorator):
             impl = Integer
 
-        stmt = select([type_coerce(column("x"), MyType).label("foo")]).limit(1)
+        stmt = select(type_coerce(column("x"), MyType).label("foo")).limit(1)
         dialect = oracle.dialect()
         compiled = stmt.compile(dialect=dialect)
         assert isinstance(compiled._create_result_map()["foo"][-1], MyType)
@@ -565,7 +555,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             dialect = oracle.OracleDialect(use_binds_for_limits=False)
 
         self.assert_compile(
-            select([t]).limit(10),
+            select(t).limit(10),
             "SELECT anon_1.col1, anon_1.col2 FROM "
             "(SELECT sometable.col1 AS col1, "
             "sometable.col2 AS col2 FROM sometable) anon_1 "
@@ -582,7 +572,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             dialect = oracle.OracleDialect(use_binds_for_limits=False)
 
         self.assert_compile(
-            select([t]).offset(10),
+            select(t).offset(10),
             "SELECT anon_1.col1, anon_1.col2 FROM (SELECT "
             "anon_2.col1 AS col1, anon_2.col2 AS col2, ROWNUM AS ora_rn "
             "FROM (SELECT sometable.col1 AS col1, sometable.col2 AS col2 "
@@ -600,7 +590,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             dialect = oracle.OracleDialect(use_binds_for_limits=False)
 
         self.assert_compile(
-            select([t]).limit(10).offset(10),
+            select(t).limit(10).offset(10),
             "SELECT anon_1.col1, anon_1.col2 FROM (SELECT "
             "anon_2.col1 AS col1, anon_2.col2 AS col2, ROWNUM AS ora_rn "
             "FROM (SELECT sometable.col1 AS col1, sometable.col2 AS col2 "
@@ -619,7 +609,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             dialect = oracle.OracleDialect(use_binds_for_limits=True)
 
         self.assert_compile(
-            select([t]).limit(10),
+            select(t).limit(10),
             "SELECT anon_1.col1, anon_1.col2 FROM "
             "(SELECT sometable.col1 AS col1, "
             "sometable.col2 AS col2 FROM sometable) anon_1 WHERE ROWNUM "
@@ -636,7 +626,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             dialect = oracle.OracleDialect(use_binds_for_limits=True)
 
         self.assert_compile(
-            select([t]).offset(10),
+            select(t).offset(10),
             "SELECT anon_1.col1, anon_1.col2 FROM "
             "(SELECT anon_2.col1 AS col1, anon_2.col2 AS col2, "
             "ROWNUM AS ora_rn "
@@ -655,7 +645,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             dialect = oracle.OracleDialect(use_binds_for_limits=True)
 
         self.assert_compile(
-            select([t]).limit(10).offset(10),
+            select(t).limit(10).offset(10),
             "SELECT anon_1.col1, anon_1.col2 FROM "
             "(SELECT anon_2.col1 AS col1, anon_2.col2 AS col2, "
             "ROWNUM AS ora_rn "
@@ -694,7 +684,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
 
         anon = a_table.alias()
         self.assert_compile(
-            select([other_table, anon])
+            select(other_table, anon)
             .select_from(other_table.outerjoin(anon))
             .apply_labels(),
             "SELECT other_thirty_characters_table_.id "
@@ -712,7 +702,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             dialect=dialect,
         )
         self.assert_compile(
-            select([other_table, anon])
+            select(other_table, anon)
             .select_from(other_table.outerjoin(anon))
             .apply_labels(),
             "SELECT other_thirty_characters_table_.id "
@@ -872,13 +862,13 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         table1, table2, table3 = self._test_outer_join_fixture()
 
         subq = (
-            select([table1])
+            select(table1)
             .select_from(
                 table1.outerjoin(table2, table1.c.myid == table2.c.otherid)
             )
             .alias()
         )
-        q = select([table3]).select_from(
+        q = select(table3).select_from(
             table3.outerjoin(subq, table3.c.userid == subq.c.myid)
         )
 
@@ -911,7 +901,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
     def test_outer_join_seven(self):
         table1, table2, table3 = self._test_outer_join_fixture()
 
-        q = select([table1.c.name]).where(table1.c.name == "foo")
+        q = select(table1.c.name).where(table1.c.name == "foo")
         self.assert_compile(
             q,
             "SELECT mytable.name FROM mytable WHERE " "mytable.name = :name_1",
@@ -921,11 +911,11 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
     def test_outer_join_eight(self):
         table1, table2, table3 = self._test_outer_join_fixture()
         subq = (
-            select([table3.c.otherstuff])
+            select(table3.c.otherstuff)
             .where(table3.c.otherstuff == table1.c.name)
             .label("bar")
         )
-        q = select([table1.c.name, subq])
+        q = select(table1.c.name, subq)
         self.assert_compile(
             q,
             "SELECT mytable.name, (SELECT "
@@ -949,7 +939,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             column("othername", String),
         )
 
-        stmt = select([table1]).select_from(
+        stmt = select(table1).select_from(
             table1.outerjoin(
                 table2,
                 and_(
@@ -968,7 +958,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             dialect=oracle.dialect(use_ansi=False),
         )
 
-        stmt = select([table1]).select_from(
+        stmt = select(table1).select_from(
             table1.outerjoin(
                 table2,
                 and_(
@@ -995,7 +985,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         j = a.join(b.join(c, b.c.b == c.c.c), a.c.a == b.c.b)
 
         self.assert_compile(
-            select([j]),
+            select(j),
             "SELECT a.a, b.b, c.c FROM a, b, c "
             "WHERE a.a = b.b AND b.b = c.c",
             dialect=oracle.OracleDialect(use_ansi=False),
@@ -1004,7 +994,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         j = a.outerjoin(b.join(c, b.c.b == c.c.c), a.c.a == b.c.b)
 
         self.assert_compile(
-            select([j]),
+            select(j),
             "SELECT a.a, b.b, c.c FROM a, b, c "
             "WHERE a.a = b.b(+) AND b.b = c.c",
             dialect=oracle.OracleDialect(use_ansi=False),
@@ -1013,7 +1003,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         j = a.join(b.outerjoin(c, b.c.b == c.c.c), a.c.a == b.c.b)
 
         self.assert_compile(
-            select([j]),
+            select(j),
             "SELECT a.a, b.b, c.c FROM a, b, c "
             "WHERE a.a = b.b AND b.b = c.c(+)",
             dialect=oracle.OracleDialect(use_ansi=False),
@@ -1030,7 +1020,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
         )
         at_alias = address_types.alias()
         s = (
-            select([at_alias, addresses])
+            select(at_alias, addresses)
             .select_from(
                 addresses.outerjoin(
                     at_alias, addresses.c.address_type_id == at_alias.c.id