pep-484: the pep-484ening, SQL part three

hitting DML which is causing us to open up the
ColumnCollection structure a bit, as we do put anonymous
column expressions with None here.  However, we still want
Table /TableClause to have named column collections that
don't return None, so parametrize the "key" in this
collection also.

* rename some "immutable" elements to "readonly".  we change
  the contents of immutablecolumncollection underneath, so it's
  not "immutable"

Change-Id: I2593995a4e5c6eae874bed5bf76117198be8ae97

1 files changed, 49 insertions, 16 deletions

diff --git a/lib/sqlalchemy/sql/_typing.py b/lib/sqlalchemy/sql/_typing.py
index b50a7bf6a..a5da87802 100644
--- a/lib/sqlalchemy/sql/_typing.py
+++ b/lib/sqlalchemy/sql/_typing.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from typing import Any
+from typing import Iterable
 from typing import Type
 from typing import TYPE_CHECKING
 from typing import TypeVar
@@ -10,9 +11,17 @@ from . import roles
 from .. import util
 from ..inspection import Inspectable
 from ..util.typing import Literal
+from ..util.typing import Protocol
 
 if TYPE_CHECKING:
+    from .elements import ClauseElement
+    from .elements import ColumnClause
+    from .elements import ColumnElement
     from .elements import quoted_name
+    from .elements import SQLCoreOperations
+    from .elements import TextClause
+    from .roles import ColumnsClauseRole
+    from .roles import FromClauseRole
     from .schema import DefaultGenerator
     from .schema import Sequence
     from .selectable import FromClause
@@ -24,31 +33,61 @@ if TYPE_CHECKING:
 
 _T = TypeVar("_T", bound=Any)
 
-_ColumnsClauseElement = Union[
+
+class _HasClauseElement(Protocol):
+    """indicates a class that has a __clause_element__() method"""
+
+    def __clause_element__(self) -> ColumnsClauseRole:
+        ...
+
+
+# convention:
+# XYZArgument - something that the end user is passing to a public API method
+# XYZElement - the internal representation that we use for the thing.
+# the coercions system is responsible for converting from XYZArgument to
+# XYZElement.
+
+_ColumnsClauseArgument = Union[
     Literal["*", 1],
     roles.ColumnsClauseRole,
     Type[Any],
-    Inspectable[roles.HasColumnElementClauseElement],
+    Inspectable[_HasClauseElement],
+    _HasClauseElement,
 ]
-_FromClauseElement = Union[
-    roles.FromClauseRole, Type[Any], Inspectable[roles.HasFromClauseElement]
+
+_SelectIterable = Iterable[Union["ColumnElement[Any]", "TextClause"]]
+
+_FromClauseArgument = Union[
+    roles.FromClauseRole,
+    Type[Any],
+    Inspectable[_HasClauseElement],
+    _HasClauseElement,
 ]
 
-_ColumnExpression = Union[
-    roles.ExpressionElementRole[_T],
-    Inspectable[roles.HasColumnElementClauseElement],
+_ColumnExpressionArgument = Union[
+    "ColumnElement[_T]", _HasClauseElement, roles.ExpressionElementRole[_T]
 ]
 
+_DMLColumnArgument = Union[str, "ColumnClause[Any]", _HasClauseElement]
+
 _PropagateAttrsType = util.immutabledict[str, Any]
 
 _TypeEngineArgument = Union[Type["TypeEngine[_T]"], "TypeEngine[_T]"]
 
 
-def is_named_from_clause(t: FromClause) -> TypeGuard[NamedFromClause]:
+def is_named_from_clause(t: FromClauseRole) -> TypeGuard[NamedFromClause]:
     return t.named_with_column
 
 
-def has_schema_attr(t: FromClause) -> TypeGuard[TableClause]:
+def is_column_element(c: ClauseElement) -> TypeGuard[ColumnElement[Any]]:
+    return c._is_column_element
+
+
+def is_text_clause(c: ClauseElement) -> TypeGuard[TextClause]:
+    return c._is_text_clause
+
+
+def has_schema_attr(t: FromClauseRole) -> TypeGuard[TableClause]:
     return hasattr(t, "schema")
 
 
@@ -60,11 +99,5 @@ def is_tuple_type(t: TypeEngine[Any]) -> TypeGuard[TupleType]:
     return t._is_tuple_type
 
 
-def is_has_clause_element(s: object) -> TypeGuard[roles.HasClauseElement]:
-    return hasattr(s, "__clause_element__")
-
-
-def is_has_column_element_clause_element(
-    s: object,
-) -> TypeGuard[roles.HasColumnElementClauseElement]:
+def is_has_clause_element(s: object) -> TypeGuard[_HasClauseElement]:
     return hasattr(s, "__clause_element__")