pep-484: session, instancestate, etc

Also adds some fixes to annotation-based mapping
that have come up, as well as starts to add more
pep-484 test cases

Change-Id: Ia722bbbc7967a11b23b66c8084eb61df9d233fee

1 files changed, 56 insertions, 20 deletions

diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 982b4b6d9..c85861a59 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -22,9 +22,13 @@ from itertools import chain
 import sys
 import threading
 from typing import Any
+from typing import Callable
 from typing import Generic
+from typing import Iterator
+from typing import Optional
+from typing import Tuple
 from typing import Type
-from typing import TypeVar
+from typing import TYPE_CHECKING
 import weakref
 
 from . import attributes
@@ -33,9 +37,11 @@ from . import instrumentation
 from . import loading
 from . import properties
 from . import util as orm_util
+from ._typing import _O
 from .base import _class_to_mapper
 from .base import _state_mapper
 from .base import class_mapper
+from .base import PassiveFlag
 from .base import state_str
 from .interfaces import _MappedAttribute
 from .interfaces import EXT_SKIP
@@ -62,10 +68,15 @@ from ..sql import visitors
 from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL
 from ..util import HasMemoized
 
-_mapper_registries = weakref.WeakKeyDictionary()
-
+if TYPE_CHECKING:
+    from ._typing import _IdentityKeyType
+    from ._typing import _InstanceDict
+    from .instrumentation import ClassManager
+    from .state import InstanceState
+    from ..sql.elements import ColumnElement
+    from ..sql.schema import Column
 
-_MC = TypeVar("_MC")
+_mapper_registries = weakref.WeakKeyDictionary()
 
 
 def _all_registries():
@@ -99,7 +110,7 @@ class Mapper(
     sql_base.MemoizedHasCacheKey,
     InspectionAttr,
     log.Identified,
-    Generic[_MC],
+    Generic[_O],
 ):
     """Defines an association between a Python class and a database table or
     other relational structure, so that ORM operations against the class may
@@ -115,9 +126,13 @@ class Mapper(
     _dispose_called = False
     _ready_for_configure = False
 
-    class_: Type[_MC]
+    class_: Type[_O]
     """The class to which this :class:`_orm.Mapper` is mapped."""
 
+    _identity_class: Type[_O]
+
+    always_refresh: bool
+
     @util.deprecated_params(
         non_primary=(
             "1.3",
@@ -130,7 +145,7 @@ class Mapper(
     )
     def __init__(
         self,
-        class_: Type[_MC],
+        class_: Type[_O],
         local_table=None,
         properties=None,
         primary_key=None,
@@ -813,7 +828,7 @@ class Mapper(
 
     """
 
-    primary_key = None
+    primary_key: Tuple[Column[Any], ...]
     """An iterable containing the collection of :class:`_schema.Column`
     objects
     which comprise the 'primary key' of the mapped table, from the
@@ -837,7 +852,7 @@ class Mapper(
 
     """
 
-    class_ = None
+    class_: Type[_O]
     """The Python class which this :class:`_orm.Mapper` maps.
 
     This is a *read only* attribute determined during mapper construction.
@@ -845,7 +860,7 @@ class Mapper(
 
     """
 
-    class_manager = None
+    class_manager: ClassManager[_O]
     """The :class:`.ClassManager` which maintains event listeners
     and class-bound descriptors for this :class:`_orm.Mapper`.
 
@@ -1965,7 +1980,7 @@ class Mapper(
             else self.persist_selectable.description,
         )
 
-    def _is_orphan(self, state):
+    def _is_orphan(self, state: InstanceState[_O]) -> bool:
         orphan_possible = False
         for mapper in self.iterate_to_root():
             for (key, cls) in mapper._delete_orphans:
@@ -2804,16 +2819,24 @@ class Mapper(
             identity_token,
         )
 
-    def identity_key_from_primary_key(self, primary_key, identity_token=None):
+    def identity_key_from_primary_key(
+        self,
+        primary_key: Tuple[Any, ...],
+        identity_token: Optional[Any] = None,
+    ) -> _IdentityKeyType[_O]:
         """Return an identity-map key for use in storing/retrieving an
         item from an identity map.
 
         :param primary_key: A list of values indicating the identifier.
 
         """
-        return self._identity_class, tuple(primary_key), identity_token
+        return (
+            self._identity_class,
+            tuple(primary_key),
+            identity_token,
+        )
 
-    def identity_key_from_instance(self, instance):
+    def identity_key_from_instance(self, instance: _O) -> _IdentityKeyType[_O]:
         """Return the identity key for the given instance, based on
         its primary key attributes.
 
@@ -2830,8 +2853,10 @@ class Mapper(
         return self._identity_key_from_state(state, attributes.PASSIVE_OFF)
 
     def _identity_key_from_state(
-        self, state, passive=attributes.PASSIVE_RETURN_NO_VALUE
-    ):
+        self,
+        state: InstanceState[_O],
+        passive: PassiveFlag = attributes.PASSIVE_RETURN_NO_VALUE,
+    ) -> _IdentityKeyType[_O]:
         dict_ = state.dict
         manager = state.manager
         return (
@@ -2845,7 +2870,7 @@ class Mapper(
             state.identity_token,
         )
 
-    def primary_key_from_instance(self, instance):
+    def primary_key_from_instance(self, instance: _O) -> Tuple[Any, ...]:
         """Return the list of primary key values for the given
         instance.
 
@@ -2903,8 +2928,12 @@ class Mapper(
         return {self._columntoproperty[col].key for col in self._all_pk_cols}
 
     def _get_state_attr_by_column(
-        self, state, dict_, column, passive=attributes.PASSIVE_RETURN_NO_VALUE
-    ):
+        self,
+        state: InstanceState[_O],
+        dict_: _InstanceDict,
+        column: Column[Any],
+        passive: PassiveFlag = PassiveFlag.PASSIVE_RETURN_NO_VALUE,
+    ) -> Any:
         prop = self._columntoproperty[column]
         return state.manager[prop.key].impl.get(state, dict_, passive=passive)
 
@@ -3146,7 +3175,14 @@ class Mapper(
     def _subclass_load_via_in_mapper(self):
         return self._subclass_load_via_in(self)
 
-    def cascade_iterator(self, type_, state, halt_on=None):
+    def cascade_iterator(
+        self,
+        type_: str,
+        state: InstanceState[_O],
+        halt_on: Optional[Callable[[InstanceState[Any]], bool]] = None,
+    ) -> Iterator[
+        Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict]
+    ]:
         r"""Iterate each element and its mapper in an object graph,
         for all relationships that meet the given cascade rule.