mypy: sqlalchemy.util

Starting to set up practices and conventions to
get the library typed.

Key goals for typing are:

1. whole library can pass mypy without any strict
   turned on.
2. we can incrementally turn on some strict flags on a per-package/
   module basis, as here we turn on more strictness for sqlalchemy.util, exc,
   and log
3. mypy ORM plugin tests work fully without sqlalchemy2-stubs
   installed
4. public facing methods all have return types, major parameter
   signatures filled in also
5. Foundational elements like util etc. are typed enough so that
   we can use them in fully typed internals higher up the stack.

Conventions set up here:

1. we can use lots of config in setup.cfg to limit where mypy
   is throwing errors and how detailed it should be in different
   packages / modules.  We can use this to push up gerrits
   that will pass tests fully without everything being typed.
2. a new tox target pep484 is added.  this links to a new jenkins
   pep484 job that works across all projects (alembic, dogpile, etc.)

We've worked around some mypy bugs that will likely
be around for awhile, and also set up some core practices
for how to deal with certain things such as public_factory
modules (mypy won't accept a module from a callable at all,
so need to use simple type checking conditionals).

References: #6810
Change-Id: I80be58029896a29fd9f491aa3215422a8b705e12

1 files changed, 14 insertions, 3 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 40fc5d162..f7d02e3b0 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -19,13 +19,17 @@ from .util import _distill_params_20
 from .util import _distill_raw_params
 from .util import TransactionalContext
 from .. import exc
+from .. import inspection
 from .. import log
 from .. import util
 from ..sql import compiler
 from ..sql import util as sql_util
+from ..sql._typing import _ExecuteOptions
+from ..sql._typing import _ExecuteParams
 
 if typing.TYPE_CHECKING:
     from .interfaces import Dialect
+    from .reflection import Inspector  # noqa
     from .url import URL
     from ..pool import Pool
     from ..pool import PoolProxiedConnection
@@ -38,7 +42,7 @@ _EMPTY_EXECUTION_OPTS = util.immutabledict()
 NO_OPTIONS = util.immutabledict()
 
 
-class Connection(ConnectionEventsTarget):
+class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]):
     """Provides high-level functionality for a wrapped DB-API connection.
 
     The :class:`_engine.Connection` object is procured by calling
@@ -1079,7 +1083,12 @@ class Connection(ConnectionEventsTarget):
 
         return self.execute(statement, parameters, execution_options).scalars()
 
-    def execute(self, statement, parameters=None, execution_options=None):
+    def execute(
+        self,
+        statement,
+        parameters: Optional[_ExecuteParams] = None,
+        execution_options: Optional[_ExecuteOptions] = None,
+    ):
         r"""Executes a SQL statement construct and returns a
         :class:`_engine.Result`.
 
@@ -2270,7 +2279,9 @@ class TwoPhaseTransaction(RootTransaction):
         self.connection._commit_twophase_impl(self.xid, self._is_prepared)
 
 
-class Engine(ConnectionEventsTarget, log.Identified):
+class Engine(
+    ConnectionEventsTarget, log.Identified, inspection.Inspectable["Inspector"]
+):
     """
     Connects a :class:`~sqlalchemy.pool.Pool` and
     :class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a