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

3 files changed, 168 insertions, 0 deletions

diff --git a/lib/sqlalchemy/util/__init__.py b/lib/sqlalchemy/util/__init__.py
index f812671d3..383c143c4 100644
--- a/lib/sqlalchemy/util/__init__.py
+++ b/lib/sqlalchemy/util/__init__.py
@@ -87,6 +87,8 @@ from .compat import win32  # noqa
 from .compat import with_metaclass  # noqa
 from .compat import zip_longest  # noqa
 from .deprecations import deprecated  # noqa
+from .deprecations import deprecated_cls  # noqa
+from .deprecations import deprecated_params  # noqa
 from .deprecations import inject_docstring_text  # noqa
 from .deprecations import pending_deprecation  # noqa
 from .deprecations import warn_deprecated  # noqa
diff --git a/lib/sqlalchemy/util/compat.py b/lib/sqlalchemy/util/compat.py
index abd36d9b0..ff644cd36 100644
--- a/lib/sqlalchemy/util/compat.py
+++ b/lib/sqlalchemy/util/compat.py
@@ -44,6 +44,19 @@ FullArgSpec = collections.namedtuple(
     ],
 )
 
+FullArgSpec = collections.namedtuple(
+    "FullArgSpec",
+    [
+        "args",
+        "varargs",
+        "varkw",
+        "defaults",
+        "kwonlyargs",
+        "kwonlydefaults",
+        "annotations",
+    ],
+)
+
 try:
     import threading
 except ImportError:
diff --git a/lib/sqlalchemy/util/deprecations.py b/lib/sqlalchemy/util/deprecations.py
index e7b972deb..a43acc72e 100644
--- a/lib/sqlalchemy/util/deprecations.py
+++ b/lib/sqlalchemy/util/deprecations.py
@@ -12,6 +12,7 @@ import re
 import textwrap
 import warnings
 
+from . import compat
 from .langhelpers import decorator
 from .. import exc
 
@@ -24,6 +25,21 @@ def warn_pending_deprecation(msg, stacklevel=3):
     warnings.warn(msg, exc.SAPendingDeprecationWarning, stacklevel=stacklevel)
 
 
+def deprecated_cls(version, message, constructor="__init__"):
+    header = ".. deprecated:: %s %s" % (version, (message or ""))
+
+    def decorate(cls):
+        return _decorate_cls_with_warning(
+            cls,
+            constructor,
+            exc.SADeprecationWarning,
+            message % dict(func=constructor),
+            header,
+        )
+
+    return decorate
+
+
 def deprecated(version, message=None, add_deprecation_to_docstring=True):
     """Decorates a function and issues a deprecation warning on use.
 
@@ -60,6 +76,74 @@ def deprecated(version, message=None, add_deprecation_to_docstring=True):
     return decorate
 
 
+def deprecated_params(**specs):
+    """Decorates a function to warn on use of certain parameters.
+
+    e.g. ::
+
+        @deprecated_params(
+            weak_identity_map=(
+                "0.7",
+                "the :paramref:`.Session.weak_identity_map parameter "
+                "is deprecated."
+            )
+
+        )
+
+    """
+
+    messages = {}
+    for param, (version, message) in specs.items():
+        messages[param] = _sanitize_restructured_text(message)
+
+    def decorate(fn):
+        spec = compat.inspect_getfullargspec(fn)
+        if spec.defaults is not None:
+            defaults = dict(
+                zip(
+                    spec.args[(len(spec.args) - len(spec.defaults)) :],
+                    spec.defaults,
+                )
+            )
+            check_defaults = set(defaults).intersection(messages)
+            check_kw = set(messages).difference(defaults)
+        else:
+            check_defaults = ()
+            check_kw = set(messages)
+
+        has_kw = spec.varkw is not None
+
+        @decorator
+        def warned(fn, *args, **kwargs):
+            for m in check_defaults:
+                if kwargs[m] != defaults[m]:
+                    warnings.warn(
+                        messages[m], exc.SADeprecationWarning, stacklevel=3
+                    )
+            for m in check_kw:
+                if m in kwargs:
+                    warnings.warn(
+                        messages[m], exc.SADeprecationWarning, stacklevel=3
+                    )
+
+            return fn(*args, **kwargs)
+
+        doc = fn.__doc__ is not None and fn.__doc__ or ""
+        if doc:
+            doc = inject_param_text(
+                doc,
+                {
+                    param: ".. deprecated:: %s %s" % (version, (message or ""))
+                    for param, (version, message) in specs.items()
+                },
+            )
+        decorated = warned(fn)
+        decorated.__doc__ = doc
+        return decorated
+
+    return decorate
+
+
 def pending_deprecation(
     version, message=None, add_deprecation_to_docstring=True
 ):
@@ -98,6 +182,14 @@ def pending_deprecation(
     return decorate
 
 
+def deprecated_option_value(parameter_value, default_value, warning_text):
+    if parameter_value is None:
+        return default_value
+    else:
+        warn_deprecated(warning_text)
+        return parameter_value
+
+
 def _sanitize_restructured_text(text):
     def repl(m):
         type_, name = m.group(1, 2)
@@ -108,6 +200,33 @@ def _sanitize_restructured_text(text):
     return re.sub(r"\:(\w+)\:`~?\.?(.+?)`", repl, text)
 
 
+def _decorate_cls_with_warning(
+    cls, constructor, wtype, message, docstring_header=None
+):
+    doc = cls.__doc__ is not None and cls.__doc__ or ""
+    if docstring_header is not None:
+        docstring_header %= dict(func=constructor)
+
+        doc = inject_docstring_text(doc, docstring_header, 1)
+
+        if type(cls) is type:
+            clsdict = dict(cls.__dict__)
+            clsdict["__doc__"] = doc
+            cls = type(cls.__name__, cls.__bases__, clsdict)
+            constructor_fn = clsdict[constructor]
+        else:
+            cls.__doc__ = doc
+            constructor_fn = getattr(cls, constructor)
+
+    setattr(
+        cls,
+        constructor,
+        _decorate_with_warning(constructor_fn, wtype, message, None),
+    )
+
+    return cls
+
+
 def _decorate_with_warning(func, wtype, message, docstring_header=None):
     """Wrap a function with a warnings.warn and augmented docstring."""
 
@@ -126,6 +245,7 @@ def _decorate_with_warning(func, wtype, message, docstring_header=None):
 
     decorated = warned(func)
     decorated.__doc__ = doc
+    decorated._sa_warn = lambda: warnings.warn(message, wtype, stacklevel=3)
     return decorated
 
 
@@ -155,3 +275,36 @@ def inject_docstring_text(doctext, injecttext, pos):
 
     lines = lines[0:inject_pos] + injectlines + lines[inject_pos:]
     return "\n".join(lines)
+
+
+def inject_param_text(doctext, inject_params):
+    doclines = doctext.splitlines()
+    lines = []
+
+    to_inject = None
+    while doclines:
+        line = doclines.pop(0)
+        if to_inject is None:
+            m = re.match(r"(\s+):param (.+?):", line)
+            if m:
+                param = m.group(2)
+                if param in inject_params:
+                    # default indent to that of :param: plus one
+                    indent = " " * len(m.group(1)) + " "
+
+                    # but if the next line has text, use that line's
+                    # indentntation
+                    if doclines:
+                        m2 = re.match(r"(\s+)\S", doclines[0])
+                        if m2:
+                            indent = " " * len(m2.group(1))
+
+                    to_inject = indent + inject_params[param]
+        elif not line.rstrip():
+            lines.append(line)
+            lines.append(to_inject)
+            lines.append("\n")
+            to_inject = None
+        lines.append(line)
+
+    return "\n".join(lines)