Add deprecation warnings to all deprecated APIs

A large change throughout the library has ensured that all objects, parameters,
and behaviors which have been noted as deprecated or legacy now emit
``DeprecationWarning`` warnings when invoked.   As the Python 3 interpreter now
defaults to displaying deprecation warnings, as well as that modern test suites
based on tools like tox and pytest tend to display deprecation warnings,
this change should make it easier to note what API features are obsolete.

See the notes added to the changelog and migration notes for further
details.

Fixes: #4393
Change-Id: If0ea11a1fc24f9a8029352eeadfc49a7a54c0a1b

8 files changed, 87 insertions, 44 deletions

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index 5f77d17a1..fbf346cec 100644
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -147,6 +147,13 @@ def create_engine(*args, **kwargs):
         columns to accommodate Python Unicode objects directly as though the
         datatype were the :class:`.Unicode` type.
 
+          .. deprecated:: The :paramref:`.create_engine.convert_unicode` flag
+             and related Unicode conversion features are legacy Python 2
+             mechanisms which no longer have relevance under Python 3.
+             As all modern DBAPIs now support Python Unicode fully even
+             under Python 2, these flags will be removed in an upcoming
+             release.
+
         .. note::
 
             SQLAlchemy's unicode-conversion flags and features only apply
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index ebf8dd28a..64303f290 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -493,19 +493,7 @@ class Connection(Connectable):
 
         return self._branch()
 
-    def contextual_connect(self, **kwargs):
-        """Returns a branched version of this :class:`.Connection`.
-
-        The :meth:`.Connection.close` method on the returned
-        :class:`.Connection` can be called and this
-        :class:`.Connection` will remain open.
-
-        This method provides usage symmetry with
-        :meth:`.Engine.contextual_connect`, including for usage
-        with context managers.
-
-        """
-
+    def _contextual_connect(self, **kwargs):
         return self._branch()
 
     def invalidate(self, exception=None):
@@ -1993,13 +1981,13 @@ class Engine(Connectable, log.Identified):
         self.dispatch.engine_disposed(self)
 
     def _execute_default(self, default):
-        with self.contextual_connect() as conn:
+        with self._contextual_connect() as conn:
             return conn._execute_default(default, (), {})
 
     @contextlib.contextmanager
     def _optional_conn_ctx_manager(self, connection=None):
         if connection is None:
-            with self.contextual_connect() as conn:
+            with self._contextual_connect() as conn:
                 yield conn
         else:
             yield connection
@@ -2058,7 +2046,7 @@ class Engine(Connectable, log.Identified):
             for a particular :class:`.Connection`.
 
         """
-        conn = self.contextual_connect(close_with_result=close_with_result)
+        conn = self._contextual_connect(close_with_result=close_with_result)
         try:
             trans = conn.begin()
         except:
@@ -2105,7 +2093,7 @@ class Engine(Connectable, log.Identified):
 
         """
 
-        with self.contextual_connect() as conn:
+        with self._contextual_connect() as conn:
             return conn.transaction(callable_, *args, **kwargs)
 
     def run_callable(self, callable_, *args, **kwargs):
@@ -2121,7 +2109,7 @@ class Engine(Connectable, log.Identified):
         which one is being dealt with.
 
         """
-        with self.contextual_connect() as conn:
+        with self._contextual_connect() as conn:
             return conn.run_callable(callable_, *args, **kwargs)
 
     def execute(self, statement, *multiparams, **params):
@@ -2140,18 +2128,18 @@ class Engine(Connectable, log.Identified):
 
         """
 
-        connection = self.contextual_connect(close_with_result=True)
+        connection = self._contextual_connect(close_with_result=True)
         return connection.execute(statement, *multiparams, **params)
 
     def scalar(self, statement, *multiparams, **params):
         return self.execute(statement, *multiparams, **params).scalar()
 
     def _execute_clauseelement(self, elem, multiparams=None, params=None):
-        connection = self.contextual_connect(close_with_result=True)
+        connection = self._contextual_connect(close_with_result=True)
         return connection._execute_clauseelement(elem, multiparams, params)
 
     def _execute_compiled(self, compiled, multiparams, params):
-        connection = self.contextual_connect(close_with_result=True)
+        connection = self._contextual_connect(close_with_result=True)
         return connection._execute_compiled(compiled, multiparams, params)
 
     def connect(self, **kwargs):
@@ -2170,6 +2158,13 @@ class Engine(Connectable, log.Identified):
 
         return self._connection_cls(self, **kwargs)
 
+    @util.deprecated(
+        "1.3",
+        "The :meth:`.Engine.contextual_connect` method is deprecated.  This "
+        "method is an artifact of the threadlocal engine strategy which is "
+        "also to be deprecated.   For explicit connections from an "
+        ":class:`.Engine`, use the :meth:`.Engine.connect` method.",
+    )
     def contextual_connect(self, close_with_result=False, **kwargs):
         """Return a :class:`.Connection` object which may be part of some
         ongoing context.
@@ -2187,6 +2182,11 @@ class Engine(Connectable, log.Identified):
 
         """
 
+        return self._contextual_connect(
+            close_with_result=close_with_result, **kwargs
+        )
+
+    def _contextual_connect(self, close_with_result=False, **kwargs):
         return self._connection_cls(
             self,
             self._wrap_pool_connect(self.pool.connect, None),
diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py
index 9c8069ff1..e54e99b75 100644
--- a/lib/sqlalchemy/engine/default.py
+++ b/lib/sqlalchemy/engine/default.py
@@ -184,6 +184,15 @@ class DefaultDialect(interfaces.Dialect):
 
     """
 
+    @util.deprecated_params(
+        convert_unicode=(
+            "1.3",
+            "The :paramref:`.create_engine.convert_unicode` parameter "
+            "and corresponding dialect-level parameters are deprecated, "
+            "and will be removed in a future release.  Modern DBAPIs support "
+            "Python Unicode natively and this parameter is unnecessary.",
+        )
+    )
     def __init__(
         self,
         convert_unicode=False,
diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index d4cd55b2f..d579e6fdb 100644
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -251,15 +251,15 @@ class Dialect(object):
 
         raise NotImplementedError()
 
+    @util.deprecated(
+        "0.8",
+        "The :meth:`.Dialect.get_primary_keys` method is deprecated and "
+        "will be removed in a future release.   Please refer to the "
+        ":meth:`.Dialect.get_pk_constraint` method. ",
+    )
     def get_primary_keys(self, connection, table_name, schema=None, **kw):
         """Return information about primary keys in `table_name`.
 
-        .. deprecated:: 0.8
-
-            The :meth:`.Dialect.get_primary_keys` method is deprecated and
-            will be removed in a future release.   Please refer to the
-            :meth:`.Dialect.get_pk_constraint` method.
-
         """
 
         raise NotImplementedError()
@@ -1117,7 +1117,15 @@ class Connectable(object):
 
         """
 
-    def contextual_connect(self):
+    @util.deprecated(
+        "1.3",
+        "The :meth:`.Engine.contextual_connect` and "
+        ":meth:`.Connection.contextual_connect` methods are deprecated.  This "
+        "method is an artifact of the threadlocal engine strategy which is "
+        "also to be deprecated.   For explicit connections from an "
+        ":class:`.Engine`, use the :meth:`.Engine.connect` method.",
+    )
+    def contextual_connect(self, *arg, **kw):
         """Return a :class:`.Connection` object which may be part of an ongoing
         context.
 
@@ -1128,6 +1136,9 @@ class Connectable(object):
 
         """
 
+        return self._contextual_connect(*arg, **kw)
+
+    def _contextual_connect(self):
         raise NotImplementedError()
 
     @util.deprecated(
@@ -1136,7 +1147,7 @@ class Connectable(object):
         "removed in a future release.  Please use the ``.create()`` method "
         "on specific schema objects to emit DDL sequences, including "
         ":meth:`.Table.create`, :meth:`.Index.create`, and "
-        ":meth:`.MetaData.create_all`."
+        ":meth:`.MetaData.create_all`.",
     )
     def create(self, entity, **kwargs):
         """Emit CREATE statements for the given schema entity.
@@ -1150,7 +1161,8 @@ class Connectable(object):
         "removed in a future release.  Please use the ``.drop()`` method "
         "on specific schema objects to emit DDL sequences, including "
         ":meth:`.Table.drop`, :meth:`.Index.drop`, and "
-        ":meth:`.MetaData.drop_all`.")
+        ":meth:`.MetaData.drop_all`.",
+    )
     def drop(self, entity, **kwargs):
         """Emit DROP statements for the given schema entity.
         """
diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py
index 4e4ddab6d..14d647b9a 100644
--- a/lib/sqlalchemy/engine/reflection.py
+++ b/lib/sqlalchemy/engine/reflection.py
@@ -160,6 +160,16 @@ class Inspector(object):
             )
         return []
 
+    @util.deprecated_params(
+        order_by=(
+            "1.0",
+            "The :paramref:`get_table_names.order_by` parameter is deprecated "
+            "and will be removed in a future release.  Please refer to "
+            ":meth:`.Inspector.get_sorted_table_and_fkc_names` for a "
+            "more comprehensive solution to resolving foreign key cycles "
+            "between tables.",
+        )
+    )
     def get_table_names(self, schema=None, order_by=None):
         """Return all table names in referred to within a particular schema.
 
@@ -179,14 +189,6 @@ class Inspector(object):
          resolve cycles, and will raise :class:`.CircularDependencyError`
          if cycles exist.
 
-         .. deprecated:: 1.0
-
-            The :paramref:`get_table_names.order_by` parameter is deprecated
-            and will be removed in a future release.  Please refer to
-            :meth:`.Inspector.get_sorted_table_and_fkc_names` for a
-            more comprehensive solution to resolving foreign key cycles
-            between tables.
-
         .. seealso::
 
             :meth:`.Inspector.get_sorted_table_and_fkc_names`
@@ -380,7 +382,7 @@ class Inspector(object):
         "0.7",
         "The :meth:`.Inspector.get_primary_keys` method is deprecated and "
         "will be removed in a future release.  Please refer to the "
-        ":meth:`.Inspector.get_pk_constraint` method."
+        ":meth:`.Inspector.get_pk_constraint` method.",
     )
     def get_primary_keys(self, table_name, schema=None, **kw):
         """Return information about primary keys in `table_name`.
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index 55310d8b0..9255343e1 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -512,7 +512,6 @@ class ResultMetaData(object):
                 "smaller than number of columns requested (%d)"
                 % (num_ctx_cols, len(cursor_description))
             )
-
         seen = set()
         for (
             idx,
diff --git a/lib/sqlalchemy/engine/strategies.py b/lib/sqlalchemy/engine/strategies.py
index 2ae48acbd..e367ef890 100644
--- a/lib/sqlalchemy/engine/strategies.py
+++ b/lib/sqlalchemy/engine/strategies.py
@@ -271,6 +271,9 @@ class MockEngineStrategy(EngineStrategy):
         def contextual_connect(self, **kwargs):
             return self
 
+        def connect(self, **kwargs):
+            return self
+
         def execution_options(self, **kw):
             return self
 
diff --git a/lib/sqlalchemy/engine/threadlocal.py b/lib/sqlalchemy/engine/threadlocal.py
index 01d6ecbb2..8e8663ccc 100644
--- a/lib/sqlalchemy/engine/threadlocal.py
+++ b/lib/sqlalchemy/engine/threadlocal.py
@@ -46,11 +46,22 @@ class TLEngine(base.Engine):
 
     _tl_connection_cls = TLConnection
 
+    @util.deprecated(
+        "1.3",
+        "The 'threadlocal' engine strategy is deprecated, and will be "
+        "removed in a future release.  The strategy is no longer relevant "
+        "to modern usage patterns (including that of the ORM "
+        ":class:`.Session` object) which make use of a :class:`.Connection` "
+        "object in order to invoke statements.",
+    )
     def __init__(self, *args, **kwargs):
         super(TLEngine, self).__init__(*args, **kwargs)
         self._connections = util.threading.local()
 
     def contextual_connect(self, **kw):
+        return self._contextual_connect(**kw)
+
+    def _contextual_connect(self, **kw):
         if not hasattr(self._connections, "conn"):
             connection = None
         else:
@@ -72,7 +83,7 @@ class TLEngine(base.Engine):
         if not hasattr(self._connections, "trans"):
             self._connections.trans = []
         self._connections.trans.append(
-            self.contextual_connect().begin_twophase(xid=xid)
+            self._contextual_connect().begin_twophase(xid=xid)
         )
         return self
 
@@ -80,14 +91,14 @@ class TLEngine(base.Engine):
         if not hasattr(self._connections, "trans"):
             self._connections.trans = []
         self._connections.trans.append(
-            self.contextual_connect().begin_nested()
+            self._contextual_connect().begin_nested()
         )
         return self
 
     def begin(self):
         if not hasattr(self._connections, "trans"):
             self._connections.trans = []
-        self._connections.trans.append(self.contextual_connect().begin())
+        self._connections.trans.append(self._contextual_connect().begin())
         return self
 
     def __enter__(self):
@@ -139,7 +150,7 @@ class TLEngine(base.Engine):
 
     def close(self):
         if not self.closed:
-            self.contextual_connect().close()
+            self._contextual_connect().close()
             connection = self._connections.conn()
             connection._force_close()
             del self._connections.conn