SelectBase no longer a FromClause

As part of the SQLAlchemy 2.0 migration project, a conceptual change has
been made to the role of the :class:`.SelectBase` class hierarchy,
which is the root of all "SELECT" statement constructs, in that they no
longer serve directly as FROM clauses, that is, they no longer subclass
:class:`.FromClause`.  For end users, the change mostly means that any
placement of a :func:`.select` construct in the FROM clause of another
:func:`.select` requires first that it be wrapped in a subquery first,
which historically is through the use of the :meth:`.SelectBase.alias`
method, and is now also available through the use of
:meth:`.SelectBase.subquery`.    This was usually a requirement in any
case since several databases don't accept unnamed SELECT subqueries
in their FROM clause in any case.

See the documentation in this change for lots more detail.

Fixes: #4617
Change-Id: I0f6174ee24b9a1a4529168e52e855e12abd60667

1 files changed, 9 insertions, 1 deletions

diff --git a/lib/sqlalchemy/sql/roles.py b/lib/sqlalchemy/sql/roles.py
index 053bd7146..55c52d401 100644
--- a/lib/sqlalchemy/sql/roles.py
+++ b/lib/sqlalchemy/sql/roles.py
@@ -95,6 +95,8 @@ class InElementRole(SQLRole):
 class FromClauseRole(ColumnsClauseRole):
     _role_name = "FROM expression, such as a Table or alias() object"
 
+    _is_subquery = False
+
     @property
     def _hide_froms(self):
         raise NotImplementedError()
@@ -134,7 +136,7 @@ class StatementRole(CoerceTextStatementRole):
 
 class ReturnsRowsRole(StatementRole):
     _role_name = (
-        "Row returning expression such as a SELECT, or an "
+        "Row returning expression such as a SELECT, a FROM clause, or an "
         "INSERT/UPDATE/DELETE with RETURNING"
     )
 
@@ -142,6 +144,12 @@ class ReturnsRowsRole(StatementRole):
 class SelectStatementRole(ReturnsRowsRole):
     _role_name = "SELECT construct or equivalent text() construct"
 
+    def subquery(self):
+        raise NotImplementedError(
+            "All SelectStatementRole objects should implement a "
+            ".subquery() method."
+        )
+
 
 class HasCTERole(ReturnsRowsRole):
     pass