Initial ORM typing layout

introduces:

1. new mapped_column() helper
2. DeclarativeBase helper
3. declared_attr has been re-typed
4. rework of Mapped[] to return InstrumentedAtribute for
   class get, so works without Mapped itself having expression
   methods
5. ORM constructs now generic on [_T]

also includes some early typing work, most of which will
be in later commits:

1. URL and History become typing.NamedTuple
2. come up with type-checking friendly way of type
   checking cy extensions, where type checking will be applied
   to the py versions, just needed to come up with a succinct
   conditional pattern for the imports

References: #6810
References: #7535
References: #7562
Change-Id: Ie5d9a44631626c021d130ca4ce395aba623c71fb

3 files changed, 11 insertions, 4 deletions

diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py
index 52817e838..c7d9d4f88 100644
--- a/lib/sqlalchemy/ext/hybrid.py
+++ b/lib/sqlalchemy/ext/hybrid.py
@@ -802,10 +802,15 @@ advanced and/or patient developers, there's probably a whole lot of amazing
 things it can be used for.
 
 """  # noqa
+from typing import Any
+from typing import TypeVar
+
 from .. import util
 from ..orm import attributes
 from ..orm import interfaces
 
+_T = TypeVar("_T", bound=Any)
+
 HYBRID_METHOD = util.symbol("HYBRID_METHOD")
 """Symbol indicating an :class:`InspectionAttr` that's
    of type :class:`.hybrid_method`.
@@ -1147,7 +1152,7 @@ class hybrid_property(interfaces.InspectionAttrInfo):
         return expr_comparator
 
 
-class Comparator(interfaces.PropComparator):
+class Comparator(interfaces.PropComparator[_T]):
     """A helper class that allows easy construction of custom
     :class:`~.orm.interfaces.PropComparator`
     classes for usage with hybrids."""
@@ -1168,7 +1173,7 @@ class Comparator(interfaces.PropComparator):
         return self
 
 
-class ExprComparator(Comparator):
+class ExprComparator(Comparator[_T]):
     def __init__(self, cls, expression, hybrid):
         self.cls = cls
         self.expression = expression
diff --git a/lib/sqlalchemy/ext/mypy/names.py b/lib/sqlalchemy/ext/mypy/names.py
index 8ec15a6d4..b6f911979 100644
--- a/lib/sqlalchemy/ext/mypy/names.py
+++ b/lib/sqlalchemy/ext/mypy/names.py
@@ -104,7 +104,7 @@ _lookup: Dict[str, Tuple[int, Set[str]]] = {
         },
     ),
     "TypeEngine": (TYPEENGINE, {"sqlalchemy.sql.type_api.TypeEngine"}),
-    "Mapped": (MAPPED, {"sqlalchemy.orm.attributes.Mapped"}),
+    "Mapped": (MAPPED, {NAMED_TYPE_SQLA_MAPPED}),
     "declarative_base": (
         DECLARATIVE_BASE,
         {
diff --git a/lib/sqlalchemy/ext/mypy/plugin.py b/lib/sqlalchemy/ext/mypy/plugin.py
index 8687012a1..0a21feb51 100644
--- a/lib/sqlalchemy/ext/mypy/plugin.py
+++ b/lib/sqlalchemy/ext/mypy/plugin.py
@@ -112,6 +112,8 @@ class SQLAlchemyPlugin(Plugin):
         self, file: MypyFile
     ) -> List[Tuple[int, str, int]]:
         return [
+            #
+            (10, "sqlalchemy.orm", -1),
             (10, "sqlalchemy.orm.attributes", -1),
             (10, "sqlalchemy.orm.decl_api", -1),
         ]
@@ -270,7 +272,7 @@ def _add_globals(ctx: Union[ClassDefContext, DynamicClassDefContext]) -> None:
 
     """
 
-    util.add_global(ctx, "sqlalchemy.orm.attributes", "Mapped", "__sa_Mapped")
+    util.add_global(ctx, "sqlalchemy.orm", "Mapped", "__sa_Mapped")
 
 
 def _set_declarative_metaclass(