pep-484 for pool

also extends into some areas of utils, events and others
as needed.

Formalizes a public hierarchy for pool API,
with ManagesConnection -> PoolProxiedConnection /
ConnectionPoolEntry for connectionfairy / connectionrecord,
which are now what's exposed in the event API and other
APIs.  all public API docs moved to the new objects.

Corrects the mypy plugin's check for sqlalchemy-stubs
not being insatlled, which has to be imported using the
dash in the name to be effective.

Change-Id: I16c2cb43b2e840d28e70a015f370a768e70f3581

3 files changed, 35 insertions, 18 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 4fd273948..8c99f6309 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -1771,15 +1771,15 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
             if not self._is_disconnect:
                 if cursor:
                     self._safe_close_cursor(cursor)
-                with util.safe_reraise(warn_only=True):
-                    # "autorollback" was mostly relevant in 1.x series.
-                    # It's very unlikely to reach here, as the connection
-                    # does autobegin so when we are here, we are usually
-                    # in an explicit / semi-explicit transaction.
-                    # however we have a test which manufactures this
-                    # scenario in any case using an event handler.
-                    if not self.in_transaction():
-                        self._rollback_impl()
+                # "autorollback" was mostly relevant in 1.x series.
+                # It's very unlikely to reach here, as the connection
+                # does autobegin so when we are here, we are usually
+                # in an explicit / semi-explicit transaction.
+                # however we have a test which manufactures this
+                # scenario in any case using an event handler.
+                # test/engine/test_execute.py-> test_actual_autorollback
+                if not self.in_transaction():
+                    self._rollback_impl()
 
             if newraise:
                 raise newraise.with_traceback(exc_info[2]) from e
@@ -2318,11 +2318,15 @@ class Engine(
 
     _schema_translate_map = None
 
+    dialect: Dialect
+    pool: Pool
+    url: URL
+
     def __init__(
         self,
-        pool: "Pool",
-        dialect: "Dialect",
-        url: "URL",
+        pool: Pool,
+        dialect: Dialect,
+        url: URL,
         logging_name: Optional[str] = None,
         echo: Union[None, str, bool] = None,
         query_cache_size: int = 500,
diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py
index a252b7cfe..ac3d6a2d8 100644
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -12,11 +12,13 @@ from typing import Union
 
 from . import base
 from . import url as _url
+from .interfaces import DBAPIConnection
 from .mock import create_mock_engine
 from .. import event
 from .. import exc
-from .. import pool as poollib
 from .. import util
+from ..pool import _AdhocProxiedConnection
+from ..pool import ConnectionPoolEntry
 from ..sql import compiler
 
 
@@ -603,10 +605,13 @@ def create_engine(url: Union[str, "_url.URL"], **kwargs: Any) -> "base.Engine":
         if builtin_on_connect:
             event.listen(pool, "connect", builtin_on_connect)
 
-        def first_connect(dbapi_connection, connection_record):
+        def first_connect(
+            dbapi_connection: DBAPIConnection,
+            connection_record: ConnectionPoolEntry,
+        ):
             c = base.Connection(
                 engine,
-                connection=poollib._AdhocProxiedConnection(
+                connection=_AdhocProxiedConnection(
                     dbapi_connection, connection_record
                 ),
                 _has_events=False,
diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index ce884614c..aab6b2de8 100644
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -59,7 +59,7 @@ class DBAPIConnection(Protocol):
     def commit(self) -> None:
         ...
 
-    def cursor(self) -> "DBAPICursor":
+    def cursor(self) -> DBAPICursor:
         ...
 
     def rollback(self) -> None:
@@ -657,6 +657,9 @@ class Dialect:
 
     """
 
+    is_async: bool
+    """Whether or not this dialect is intended for asyncio use."""
+
     def create_connect_args(
         self, url: "URL"
     ) -> Tuple[Tuple[str], Mapping[str, Any]]:
@@ -1091,7 +1094,7 @@ class Dialect:
 
         raise NotImplementedError()
 
-    def do_close(self, dbapi_connection: PoolProxiedConnection) -> None:
+    def do_close(self, dbapi_connection: DBAPIConnection) -> None:
         """Provide an implementation of ``connection.close()``, given a DBAPI
         connection.
 
@@ -1104,6 +1107,11 @@ class Dialect:
 
         raise NotImplementedError()
 
+    def do_ping(self, dbapi_connection: DBAPIConnection) -> bool:
+        """ping the DBAPI connection and return True if the connection is
+        usable."""
+        raise NotImplementedError()
+
     def do_set_input_sizes(
         self,
         cursor: DBAPICursor,
@@ -1679,7 +1687,7 @@ class Dialect:
 
         """
 
-    def get_driver_connection(self, connection: PoolProxiedConnection) -> Any:
+    def get_driver_connection(self, connection: DBAPIConnection) -> Any:
         """Returns the connection object as returned by the external driver
         package.