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

2 files changed, 31 insertions, 9 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 5c446a91d..8bcc7e258 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -79,8 +79,8 @@ if typing.TYPE_CHECKING:
 
 """
 
-_EMPTY_EXECUTION_OPTS: _ExecuteOptions = util.immutabledict()
-NO_OPTIONS: Mapping[str, Any] = util.immutabledict()
+_EMPTY_EXECUTION_OPTS: _ExecuteOptions = util.EMPTY_DICT
+NO_OPTIONS: Mapping[str, Any] = util.EMPTY_DICT
 
 
 class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
@@ -936,6 +936,20 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
             )
         )
 
+    def _get_required_transaction(self) -> RootTransaction:
+        trans = self._transaction
+        if trans is None:
+            raise exc.InvalidRequestError("connection is not in a transaction")
+        return trans
+
+    def _get_required_nested_transaction(self) -> NestedTransaction:
+        trans = self._nested_transaction
+        if trans is None:
+            raise exc.InvalidRequestError(
+                "connection is not in a nested transaction"
+            )
+        return trans
+
     def get_transaction(self) -> Optional[RootTransaction]:
         """Return the current root transaction in progress, if any.
 
@@ -1220,7 +1234,7 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
         self,
         func: FunctionElement[Any],
         distilled_parameters: _CoreMultiExecuteParams,
-        execution_options: _ExecuteOptions,
+        execution_options: _ExecuteOptionsParameter,
     ) -> Result:
         """Execute a sql.FunctionElement object."""
 
@@ -1232,7 +1246,7 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
         self,
         default: ColumnDefault,
         distilled_parameters: _CoreMultiExecuteParams,
-        execution_options: _ExecuteOptions,
+        execution_options: _ExecuteOptionsParameter,
     ) -> Any:
         """Execute a schema.ColumnDefault object."""
 
@@ -1291,7 +1305,7 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
         self,
         ddl: DDLElement,
         distilled_parameters: _CoreMultiExecuteParams,
-        execution_options: _ExecuteOptions,
+        execution_options: _ExecuteOptionsParameter,
     ) -> Result:
         """Execute a schema.DDL object."""
 
@@ -1388,7 +1402,7 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
         self,
         elem: Executable,
         distilled_parameters: _CoreMultiExecuteParams,
-        execution_options: _ExecuteOptions,
+        execution_options: _ExecuteOptionsParameter,
     ) -> Result:
         """Execute a sql.ClauseElement object."""
 
@@ -1511,7 +1525,7 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
         self,
         statement: str,
         parameters: Optional[_DBAPIAnyExecuteParams] = None,
-        execution_options: Optional[_ExecuteOptions] = None,
+        execution_options: Optional[_ExecuteOptionsParameter] = None,
     ) -> Result:
         r"""Executes a SQL statement construct and returns a
         :class:`_engine.CursorResult`.
diff --git a/lib/sqlalchemy/engine/util.py b/lib/sqlalchemy/engine/util.py
index 213485cc9..529b2ca73 100644
--- a/lib/sqlalchemy/engine/util.py
+++ b/lib/sqlalchemy/engine/util.py
@@ -10,11 +10,13 @@ from __future__ import annotations
 import typing
 from typing import Any
 from typing import Callable
+from typing import Optional
 from typing import TypeVar
 
 from .. import exc
 from .. import util
 from ..util._has_cy import HAS_CYEXTENSION
+from ..util.typing import Protocol
 
 if typing.TYPE_CHECKING or not HAS_CYEXTENSION:
     from ._py_util import _distill_params_20 as _distill_params_20
@@ -49,6 +51,10 @@ def connection_memoize(key: str) -> Callable[[_C], _C]:
     return decorated  # type: ignore[return-value]
 
 
+class _TConsSubject(Protocol):
+    _trans_context_manager: Optional[TransactionalContext]
+
+
 class TransactionalContext:
     """Apply Python context manager behavior to transaction objects.
 
@@ -59,6 +65,8 @@ class TransactionalContext:
 
     __slots__ = ("_outer_trans_ctx", "_trans_subject", "__weakref__")
 
+    _trans_subject: Optional[_TConsSubject]
+
     def _transaction_is_active(self) -> bool:
         raise NotImplementedError()
 
@@ -82,7 +90,7 @@ class TransactionalContext:
         """
         raise NotImplementedError()
 
-    def _get_subject(self) -> Any:
+    def _get_subject(self) -> _TConsSubject:
         raise NotImplementedError()
 
     def commit(self) -> None:
@@ -95,7 +103,7 @@ class TransactionalContext:
         raise NotImplementedError()
 
     @classmethod
-    def _trans_ctx_check(cls, subject: Any) -> None:
+    def _trans_ctx_check(cls, subject: _TConsSubject) -> None:
         trans_context = subject._trans_context_manager
         if trans_context:
             if not trans_context._transaction_is_active():