pep484: schema API

implement strict typing for schema.py

this module has lots of public API, lots of old decisions
and very hard to follow construction sequences in many
cases, and is also where we get a lot of new feature requests,
so strict typing should help keep things clean.

among improvements here, fixed the pool .info getters
and also figured out how to get ColumnCollection and
related to be covariant so that we may set them up
as returning Column or ColumnClause without any conflicts.

DDL was affected, noting that superclasses of DDLElement
(_DDLCompiles, added recently) can now be passed into
"ddl_if" callables; reorganized ddl into ExecutableDDLElement
as a new name for DDLElement and _DDLCompiles renamed to
BaseDDLElement.

setting up strict also located an API use case that
is completely broken, which is connection.execute(some_default)
returns a scalar value.   This case has been deprecated
and new paths have been set up so that connection.scalar()
may be used.  This likely wasn't possible in previous
versions because scalar() would assume a CursorResult.

The scalar() change also impacts Session as we have explicit
support (since someone had reported it as a regression)
for session.execute(Sequence()) to work.  They will get the
same deprecation message (which omits the word "Connection",
just uses ".execute()" and ".scalar()") and they can then
use Session.scalar() as well.  Getting this to type
correctly while still supporting ORM use cases required
some refactoring, and I also set up a keyword only delimeter
for Session.execute() and related as execution_options /
bind_arguments should always be keyword only, applied these
changes to AsyncSession as well.

Additionally simpify Table __init__ now that we are Python
3 only, we can have positional plus explicit kwargs finally.
Simplify Column.__init__ as well again taking advantage
of kw only arguments.

Fill in most/all __init__ methods in sqltypes.py as
the constructor for types is most of the API.   should
likely do this for dialect-specific types as well.

Apply _InfoType for all info attributes as should have been
done originally and update descriptor decorators.

Change-Id: I3f9f8ff3f1c8858471ff4545ac83d68c88107527

1 files changed, 47 insertions, 42 deletions

diff --git a/lib/sqlalchemy/pool/base.py b/lib/sqlalchemy/pool/base.py
index e22848fd2..934423e2f 100644
--- a/lib/sqlalchemy/pool/base.py
+++ b/lib/sqlalchemy/pool/base.py
@@ -44,6 +44,7 @@ if TYPE_CHECKING:
     from ..event import _DispatchCommon
     from ..event import _ListenerFnType
     from ..event import dispatcher
+    from ..sql._typing import _InfoType
 
 
 class ResetStyle(Enum):
@@ -461,51 +462,55 @@ class ManagesConnection:
 
     """
 
-    info: Dict[str, Any]
-    """Info dictionary associated with the underlying DBAPI connection
-    referred to by this :class:`.ManagesConnection` instance, allowing
-    user-defined data to be associated with the connection.
+    @util.ro_memoized_property
+    def info(self) -> _InfoType:
+        """Info dictionary associated with the underlying DBAPI connection
+        referred to by this :class:`.ManagesConnection` instance, allowing
+        user-defined data to be associated with the connection.
 
-    The data in this dictionary is persistent for the lifespan
-    of the DBAPI connection itself, including across pool checkins
-    and checkouts.  When the connection is invalidated
-    and replaced with a new one, this dictionary is cleared.
+        The data in this dictionary is persistent for the lifespan
+        of the DBAPI connection itself, including across pool checkins
+        and checkouts.  When the connection is invalidated
+        and replaced with a new one, this dictionary is cleared.
 
-    For a :class:`.PoolProxiedConnection` instance that's not associated
-    with a :class:`.ConnectionPoolEntry`, such as if it were detached, the
-    attribute returns a dictionary that is local to that
-    :class:`.ConnectionPoolEntry`. Therefore the
-    :attr:`.ManagesConnection.info` attribute will always provide a Python
-    dictionary.
+        For a :class:`.PoolProxiedConnection` instance that's not associated
+        with a :class:`.ConnectionPoolEntry`, such as if it were detached, the
+        attribute returns a dictionary that is local to that
+        :class:`.ConnectionPoolEntry`. Therefore the
+        :attr:`.ManagesConnection.info` attribute will always provide a Python
+        dictionary.
 
-    .. seealso::
+        .. seealso::
 
-        :attr:`.ManagesConnection.record_info`
+            :attr:`.ManagesConnection.record_info`
 
 
-    """
+        """
+        raise NotImplementedError()
 
-    record_info: Optional[Dict[str, Any]]
-    """Persistent info dictionary associated with this
-    :class:`.ManagesConnection`.
+    @util.ro_memoized_property
+    def record_info(self) -> Optional[_InfoType]:
+        """Persistent info dictionary associated with this
+        :class:`.ManagesConnection`.
 
-    Unlike the :attr:`.ManagesConnection.info` dictionary, the lifespan
-    of this dictionary is that of the :class:`.ConnectionPoolEntry`
-    which owns it; therefore this dictionary will persist across
-    reconnects and connection invalidation for a particular entry
-    in the connection pool.
+        Unlike the :attr:`.ManagesConnection.info` dictionary, the lifespan
+        of this dictionary is that of the :class:`.ConnectionPoolEntry`
+        which owns it; therefore this dictionary will persist across
+        reconnects and connection invalidation for a particular entry
+        in the connection pool.
 
-    For a :class:`.PoolProxiedConnection` instance that's not associated
-    with a :class:`.ConnectionPoolEntry`, such as if it were detached, the
-    attribute returns None. Contrast to the :attr:`.ManagesConnection.info`
-    dictionary which is never None.
+        For a :class:`.PoolProxiedConnection` instance that's not associated
+        with a :class:`.ConnectionPoolEntry`, such as if it were detached, the
+        attribute returns None. Contrast to the :attr:`.ManagesConnection.info`
+        dictionary which is never None.
 
 
-    .. seealso::
+        .. seealso::
 
-        :attr:`.ManagesConnection.info`
+            :attr:`.ManagesConnection.info`
 
-    """
+        """
+        raise NotImplementedError()
 
     def invalidate(
         self, e: Optional[BaseException] = None, soft: bool = False
@@ -627,12 +632,12 @@ class _ConnectionRecord(ConnectionPoolEntry):
 
     _soft_invalidate_time: float = 0
 
-    @util.memoized_property
-    def info(self) -> Dict[str, Any]:  # type: ignore[override]  # mypy#4125
+    @util.ro_memoized_property
+    def info(self) -> _InfoType:
         return {}
 
-    @util.memoized_property
-    def record_info(self) -> Optional[Dict[str, Any]]:  # type: ignore[override]  # mypy#4125  # noqa: E501
+    @util.ro_memoized_property
+    def record_info(self) -> Optional[_InfoType]:
         return {}
 
     @classmethod
@@ -1080,8 +1085,8 @@ class _AdhocProxiedConnection(PoolProxiedConnection):
     ) -> None:
         self._is_valid = False
 
-    @property
-    def record_info(self) -> Optional[Dict[str, Any]]:  # type: ignore[override]  # mypy#4125  # noqa: E501
+    @util.ro_non_memoized_property
+    def record_info(self) -> Optional[_InfoType]:
         return self._connection_record.record_info
 
     def cursor(self, *args: Any, **kwargs: Any) -> DBAPICursor:
@@ -1314,15 +1319,15 @@ class _ConnectionFairy(PoolProxiedConnection):
     def is_detached(self) -> bool:
         return self._connection_record is None
 
-    @util.memoized_property
-    def info(self) -> Dict[str, Any]:  # type: ignore[override]  # mypy#4125
+    @util.ro_memoized_property
+    def info(self) -> _InfoType:
         if self._connection_record is None:
             return {}
         else:
             return self._connection_record.info
 
-    @property
-    def record_info(self) -> Optional[Dict[str, Any]]:  # type: ignore[override]  # mypy#4125  # noqa: E501
+    @util.ro_non_memoized_property
+    def record_info(self) -> Optional[_InfoType]:
         if self._connection_record is None:
             return None
         else: