pep484 ORM / SQL result support

after some experimentation it seems mypy is more amenable
to the generic types being fully integrated rather than
having separate spin-off types.   so key structures
like Result, Row, Select become generic.  For DML
Insert, Update, Delete, these are spun into type-specific
subclasses ReturningInsert, ReturningUpdate, ReturningDelete,
which is fine since the "row-ness" of these constructs
doesn't happen until returning() is called in any case.

a Tuple based model is then integrated so that these
objects can carry along information about their return
types.  Overloads at the .execute() level carry through
the Tuple from the invoked object to the result.

To suit the issue of AliasedClass generating attributes
that are dynamic, experimented with a custom subclass
AsAliased, but then just settled on having aliased()
lie to the type checker and return `Type[_O]`, essentially.
will need some type-related accessors for with_polymorphic()
also.

Additionally, identified an issue in Update when used
"mysql style" against a join(), it basically doesn't work
if asked to UPDATE two tables on the same column name.
added an error message to the specific condition where
it happens with a very non-specific error message that we
hit a thing we can't do right now, suggest multi-table
update as a possible cause.

Change-Id: I5eff7eefe1d6166ee74160b2785c5e6a81fa8b95

1 files changed, 10 insertions, 47 deletions

diff --git a/lib/sqlalchemy/sql/roles.py b/lib/sqlalchemy/sql/roles.py
index 231c70a5b..09d4b35ad 100644
--- a/lib/sqlalchemy/sql/roles.py
+++ b/lib/sqlalchemy/sql/roles.py
@@ -8,8 +8,6 @@ from __future__ import annotations
 
 from typing import Any
 from typing import Generic
-from typing import Iterable
-from typing import List
 from typing import Optional
 from typing import TYPE_CHECKING
 from typing import TypeVar
@@ -19,12 +17,7 @@ from ..util.typing import Literal
 
 if TYPE_CHECKING:
     from ._typing import _PropagateAttrsType
-    from .base import _EntityNamespace
-    from .base import ColumnCollection
-    from .base import ReadOnlyColumnCollection
-    from .elements import ColumnClause
     from .elements import Label
-    from .elements import NamedColumn
     from .selectable import _SelectIterable
     from .selectable import FromClause
     from .selectable import Subquery
@@ -108,13 +101,21 @@ class TruncatedLabelRole(StringRole, SQLRole):
 
 class ColumnsClauseRole(AllowsLambdaRole, UsesInspection, ColumnListRole):
     __slots__ = ()
-    _role_name = "Column expression or FROM clause"
+    _role_name = (
+        "Column expression, FROM clause, or other columns clause element"
+    )
 
     @property
     def _select_iterable(self) -> _SelectIterable:
         raise NotImplementedError()
 
 
+class TypedColumnsClauseRole(Generic[_T], SQLRole):
+    """element-typed form of ColumnsClauseRole"""
+
+    __slots__ = ()
+
+
 class LimitOffsetRole(SQLRole):
     __slots__ = ()
     _role_name = "LIMIT / OFFSET expression"
@@ -161,7 +162,7 @@ class WhereHavingRole(OnClauseRole):
     _role_name = "SQL expression for WHERE/HAVING role"
 
 
-class ExpressionElementRole(Generic[_T], SQLRole):
+class ExpressionElementRole(TypedColumnsClauseRole[_T]):
     # note when using generics for ExpressionElementRole,
     # the generic type needs to be in
     # sqlalchemy.sql.coercions._impl_lookup mapping also.
@@ -212,39 +213,11 @@ class FromClauseRole(ColumnsClauseRole, JoinTargetRole):
 
     named_with_column: bool
 
-    if TYPE_CHECKING:
-
-        @util.ro_non_memoized_property
-        def c(self) -> ReadOnlyColumnCollection[str, ColumnClause[Any]]:
-            ...
-
-        @util.ro_non_memoized_property
-        def columns(self) -> ReadOnlyColumnCollection[str, ColumnClause[Any]]:
-            ...
-
-        @util.ro_non_memoized_property
-        def entity_namespace(self) -> _EntityNamespace:
-            ...
-
-        @util.ro_non_memoized_property
-        def _hide_froms(self) -> Iterable[FromClause]:
-            ...
-
-        @util.ro_non_memoized_property
-        def _from_objects(self) -> List[FromClause]:
-            ...
-
 
 class StrictFromClauseRole(FromClauseRole):
     __slots__ = ()
     # does not allow text() or select() objects
 
-    if TYPE_CHECKING:
-
-        @util.ro_non_memoized_property
-        def description(self) -> str:
-            ...
-
 
 class AnonymizedFromClauseRole(StrictFromClauseRole):
     __slots__ = ()
@@ -317,16 +290,6 @@ class DMLTableRole(FromClauseRole):
     __slots__ = ()
     _role_name = "subject table for an INSERT, UPDATE or DELETE"
 
-    if TYPE_CHECKING:
-
-        @util.ro_non_memoized_property
-        def primary_key(self) -> Iterable[NamedColumn[Any]]:
-            ...
-
-        @util.ro_non_memoized_property
-        def columns(self) -> ReadOnlyColumnCollection[str, ColumnClause[Any]]:
-            ...
-
 
 class DMLColumnRole(SQLRole):
     __slots__ = ()