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

10 files changed, 191 insertions, 114 deletions

diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py
index c7c242501..cd81d759d 100644
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -452,50 +452,57 @@ class AttributeImpl(object):
     ):
         r"""Construct an AttributeImpl.
 
-        \class_
-          associated class
+        :param \class_: associated class
 
-        key
-          string name of the attribute
+        :param key: string name of the attribute
 
-        \callable_
+        :param \callable_:
           optional function which generates a callable based on a parent
           instance, which produces the "default" values for a scalar or
           collection attribute when it's first accessed, if not present
           already.
 
-        trackparent
+        :param trackparent:
           if True, attempt to track if an instance has a parent attached
           to it via this attribute.
 
-        extension
+        :param extension:
           a single or list of AttributeExtension object(s) which will
-          receive set/delete/append/remove/etc. events.  Deprecated.
+          receive set/delete/append/remove/etc. events.
           The event package is now used.
 
-        compare_function
+          .. deprecated::  1.3
+
+            The :paramref:`.AttributeImpl.extension` parameter is deprecated
+            and will be removed in a future release, corresponding to the
+            "extension" parameter on the :class:`.MapperProprty` classes
+            like :func:`.column_property` and :func:`.relationship`  The
+            events system is now used.
+
+        :param compare_function:
           a function that compares two values which are normally
           assignable to this attribute.
 
-        active_history
+        :param active_history:
           indicates that get_history() should always return the "old" value,
           even if it means executing a lazy callable upon attribute change.
 
-        parent_token
+        :param parent_token:
           Usually references the MapperProperty, used as a key for
           the hasparent() function to identify an "owning" attribute.
           Allows multiple AttributeImpls to all match a single
           owner attribute.
 
-        expire_missing
+        :param expire_missing:
           if False, don't add an "expiry" callable to this attribute
           during state.expire_attributes(None), if no value is present
           for this key.
 
-        send_modified_events
+        :param send_modified_events:
           if False, the InstanceState._modified_event method will have no
           effect; this means the attribute will never show up as changed in a
           history entry.
+
         """
         self.class_ = class_
         self.key = key
@@ -1841,9 +1848,9 @@ def init_collection(obj, key):
     For an easier way to do the above, see
     :func:`~sqlalchemy.orm.attributes.set_committed_value`.
 
-    obj is an instrumented object instance.  An InstanceState
-    is accepted directly for backwards compatibility but
-    this usage is deprecated.
+    :param obj: a mapped object
+
+    :param key: string attribute name where the collection is located.
 
     """
     state = instance_state(obj)
diff --git a/lib/sqlalchemy/orm/collections.py b/lib/sqlalchemy/orm/collections.py
index 1e561369f..b9297e15c 100644
--- a/lib/sqlalchemy/orm/collections.py
+++ b/lib/sqlalchemy/orm/collections.py
@@ -460,7 +460,7 @@ class collection(object):
     @staticmethod
     @util.deprecated(
         "1.3",
-        "The :meth:`.collection.converter` method is deprecated and will "
+        "The :meth:`.collection.converter` handler is deprecated and will "
         "be removed in a future release.  Please refer to the "
         ":class:`.AttributeEvents.bulk_replace` listener interface in "
         "conjunction with the :func:`.event.listen` function.",
diff --git a/lib/sqlalchemy/orm/deprecated_interfaces.py b/lib/sqlalchemy/orm/deprecated_interfaces.py
index 50ef8448a..4069b43a5 100644
--- a/lib/sqlalchemy/orm/deprecated_interfaces.py
+++ b/lib/sqlalchemy/orm/deprecated_interfaces.py
@@ -87,6 +87,14 @@ class MapperExtension(object):
             ls_meth = getattr(listener, meth)
 
             if not util.methods_equivalent(me_meth, ls_meth):
+                util.warn_deprecated(
+                    "MapperExtension.%s is deprecated.  The "
+                    "MapperExtension class will be removed in a future "
+                    "release.  Please transition to the @event interface, "
+                    "using @event.listens_for(mapped_class, '%s')."
+                    % (meth, meth)
+                )
+
                 if meth == "reconstruct_instance":
 
                     def go(ls_meth):
@@ -359,6 +367,13 @@ class SessionExtension(object):
             ls_meth = getattr(listener, meth)
 
             if not util.methods_equivalent(me_meth, ls_meth):
+                util.warn_deprecated(
+                    "SessionExtension.%s is deprecated.  The "
+                    "SessionExtension class will be removed in a future "
+                    "release.  Please transition to the @event interface, "
+                    "using @event.listens_for(Session, '%s')." % (meth, meth)
+                )
+
                 event.listen(self, meth, getattr(listener, meth))
 
     def before_commit(self, session):
@@ -492,6 +507,19 @@ class AttributeExtension(object):
 
     @classmethod
     def _adapt_listener(cls, self, listener):
+        for meth in ["append", "remove", "set"]:
+            me_meth = getattr(AttributeExtension, meth)
+            ls_meth = getattr(listener, meth)
+
+            if not util.methods_equivalent(me_meth, ls_meth):
+                util.warn_deprecated(
+                    "AttributeExtension.%s is deprecated.  The "
+                    "AttributeExtension class will be removed in a future "
+                    "release.  Please transition to the @event interface, "
+                    "using @event.listens_for(Class.attribute, '%s')."
+                    % (meth, meth)
+                )
+
         event.listen(
             self,
             "append",
diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py
index 45600928f..c1e5866b5 100644
--- a/lib/sqlalchemy/orm/descriptor_props.py
+++ b/lib/sqlalchemy/orm/descriptor_props.py
@@ -93,6 +93,15 @@ class CompositeProperty(DescriptorProperty):
 
     """
 
+    @util.deprecated_params(
+        extension=(
+            "0.7",
+            ":class:`.AttributeExtension` is deprecated in favor of the "
+            ":class:`.AttributeEvents` listener interface.  The "
+            ":paramref:`.composite.extension` parameter will be "
+            "removed in a future release.",
+        )
+    )
     def __init__(self, class_, *attrs, **kwargs):
         r"""Return a composite column-based property for use with a Mapper.
 
@@ -141,13 +150,6 @@ class CompositeProperty(DescriptorProperty):
           attribute listeners for the resulting descriptor placed on the
           class.
 
-           .. deprecated:: 0.7
-
-                :class:`.AttributeExtension` is deprecated in favor of the
-                :class:`.AttributeEvents` listener interface.  The
-                :paramref:`.composite.extension` parameter will be
-                removed in a future release.
-
         """
         super(CompositeProperty, self).__init__()
 
@@ -698,6 +700,12 @@ class SynonymProperty(DescriptorProperty):
 
 
 @util.langhelpers.dependency_for("sqlalchemy.orm.properties", add_to_all=True)
+@util.deprecated_cls(
+    "0.7",
+    ":func:`.comparable_property` is deprecated and will be removed in a "
+    "future release.  Please refer to the :mod:`~sqlalchemy.ext.hybrid` "
+    "extension.",
+)
 class ComparableProperty(DescriptorProperty):
     """Instruments a Python property for use in query expressions."""
 
@@ -707,10 +715,6 @@ class ComparableProperty(DescriptorProperty):
         """Provides a method of applying a :class:`.PropComparator`
         to any Python descriptor attribute.
 
-        .. deprecated:: 0.7
-            :func:`.comparable_property` is superseded by
-            the :mod:`~sqlalchemy.ext.hybrid` extension.  See the example
-            at :ref:`hybrid_custom_comparators`.
 
         Allows any Python descriptor to behave like a SQL-enabled
         attribute when used at the class level in queries, allowing
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index a394ec06e..0c8ab0b10 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -104,6 +104,22 @@ class Mapper(InspectionAttr):
     _new_mappers = False
     _dispose_called = False
 
+    @util.deprecated_params(
+        extension=(
+            "0.7",
+            ":class:`.MapperExtension` is deprecated in favor of the "
+            ":class:`.MapperEvents` listener interface.  The "
+            ":paramref:`.mapper.extension` parameter will be "
+            "removed in a future release.",
+        ),
+        order_by=(
+            "1.1",
+            "The :paramref:`.Mapper.order_by` parameter "
+            "is deprecated, and will be removed in a future release. "
+            "Use :meth:`.Query.order_by` to determine the ordering of a "
+            "result set.",
+        ),
+    )
     def __init__(
         self,
         class_,
@@ -272,13 +288,6 @@ class Mapper(InspectionAttr):
            list of :class:`.MapperExtension` instances which will be applied
            to all operations by this :class:`.Mapper`.
 
-           .. deprecated:: 0.7
-
-                :class:`.MapperExtension` is deprecated in favor of the
-                :class:`.MapperEvents` listener interface.  The
-                :paramref:`.mapper.extension` parameter will be
-                removed in a future release.
-
         :param include_properties: An inclusive list or set of string column
           names to map.
 
@@ -339,11 +348,6 @@ class Mapper(InspectionAttr):
            ordering for entities.  By default mappers have no pre-defined
            ordering.
 
-           .. deprecated:: 1.1 The :paramref:`.Mapper.order_by` parameter
-              is deprecated, and will be removed in a future release.
-              Use :meth:`.Query.order_by` to determine the ordering of a
-              result set.
-
         :param passive_deletes: Indicates DELETE behavior of foreign key
            columns when a joined-table inheritance entity is being deleted.
            Defaults to ``False`` for a base mapper; for an inheriting mapper,
@@ -604,12 +608,6 @@ class Mapper(InspectionAttr):
 
         if order_by is not False:
             self.order_by = util.to_list(order_by)
-            util.warn_deprecated(
-                "Mapper.order_by is deprecated."
-                "Use Query.order_by() in order to affect the ordering of ORM "
-                "result sets."
-            )
-
         else:
             self.order_by = order_by
 
diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index 328c9b1b4..530eadb6b 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -55,6 +55,15 @@ class ColumnProperty(StrategizedProperty):
         "_deferred_column_loader",
     )
 
+    @util.deprecated_params(
+        extension=(
+            "0.7",
+            ":class:`.AttributeExtension` is deprecated in favor of the "
+            ":class:`.AttributeEvents` listener interface.  The "
+            ":paramref:`.column_property.extension` parameter will be "
+            "removed in a future release.",
+        )
+    )
     def __init__(self, *columns, **kwargs):
         r"""Provide a column-level property for use with a Mapper.
 
@@ -120,13 +129,6 @@ class ColumnProperty(StrategizedProperty):
             which will be prepended to the list of attribute listeners for the
             resulting descriptor placed on the class.
 
-           .. deprecated:: 0.7
-
-                :class:`.AttributeExtension` is deprecated in favor of the
-                :class:`.AttributeEvents` listener interface.   The
-                :paramref:`.column_property.extension` parameter will be
-                removed in a future release.
-
         """
         super(ColumnProperty, self).__init__()
         self._orig_columns = [expression._labeled(c) for c in columns]
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 387a72d0b..150347995 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1569,16 +1569,16 @@ class Query(object):
         self._execution_options = self._execution_options.union(kwargs)
 
     @_generative()
+    @util.deprecated(
+        "0.9",
+        "The :meth:`.Query.with_lockmode` method is deprecated and will "
+        "be removed in a future release.  Please refer to "
+        ":meth:`.Query.with_for_update`. ",
+    )
     def with_lockmode(self, mode):
         """Return a new :class:`.Query` object with the specified "locking mode",
         which essentially refers to the ``FOR UPDATE`` clause.
 
-        .. deprecated:: 0.9
-
-            The :meth:`.Query.with_lockmode` method is deprecated and will
-            be removed in a future release.  Please refer to
-            :meth:`.Query.with_for_update`.
-
         :param mode: a string representing the desired locking mode.
          Valid values are:
 
diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py
index af4d9a782..be2093fb9 100644
--- a/lib/sqlalchemy/orm/relationships.py
+++ b/lib/sqlalchemy/orm/relationships.py
@@ -105,6 +105,15 @@ class RelationshipProperty(StrategizedProperty):
 
     _dependency_processor = None
 
+    @util.deprecated_params(
+        extension=(
+            "0.7",
+            ":class:`.AttributeExtension` is deprecated in favor of the "
+            ":class:`.AttributeEvents` listener interface.  The "
+            ":paramref:`.relationship.extension` parameter will be "
+            "removed in a future release.",
+        )
+    )
     def __init__(
         self,
         argument,
@@ -402,13 +411,6 @@ class RelationshipProperty(StrategizedProperty):
           which will be prepended to the list of attribute listeners for
           the resulting descriptor placed on the class.
 
-           .. deprecated:: 0.7
-
-                :class:`.AttributeExtension` is deprecated in favor of the
-                :class:`.AttributeEvents` listener interface. The
-                :paramref:`.relationship.extension` parameter will be
-                removed in a future release.
-
         :param foreign_keys:
 
           a list of columns which are to be used as "foreign key"
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 5993e91b8..53f99b99d 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -427,7 +427,7 @@ class SessionTransaction(object):
                         "given Connection's Engine"
                     )
             else:
-                conn = bind.contextual_connect()
+                conn = bind._contextual_connect()
 
         if execution_options:
             conn = conn.execution_options(**execution_options)
@@ -642,6 +642,30 @@ class Session(_SessionClassMethods):
         "scalar",
     )
 
+    @util.deprecated_params(
+        weak_identity_map=(
+            "1.0",
+            "The :paramref:`.Session.weak_identity_map` parameter as well as "
+            "the strong-referencing identity map are deprecated, and will be "
+            "removed in a future release.  For the use case where objects "
+            "present in a :class:`.Session` need to be automatically strong "
+            "referenced, see the recipe at "
+            ":ref:`session_referencing_behavior` for an event-based approach "
+            "to maintaining strong identity references. ",
+        ),
+        _enable_transaction_accounting=(
+            "0.7",
+            "The :paramref:`.Session._enable_transaction_accounting` "
+            "parameter is deprecated and will be removed in a future release.",
+        ),
+        extension=(
+            "0.7",
+            ":class:`.SessionExtension` is deprecated in favor of the "
+            ":class:`.SessionEvents` listener interface.  The "
+            ":paramref:`.Session.extension` parameter will be "
+            "removed in a future release.",
+        ),
+    )
     def __init__(
         self,
         bind=None,
@@ -650,12 +674,12 @@ class Session(_SessionClassMethods):
         _enable_transaction_accounting=True,
         autocommit=False,
         twophase=False,
-        weak_identity_map=True,
+        weak_identity_map=None,
         binds=None,
         extension=None,
         enable_baked_queries=True,
         info=None,
-        query_cls=query.Query,
+        query_cls=None,
     ):
         r"""Construct a new Session.
 
@@ -754,15 +778,10 @@ class Session(_SessionClassMethods):
 
            .. versionadded:: 1.2
 
-        :param _enable_transaction_accounting:  Defaults to ``True``.  A
+        :param _enable_transaction_accounting:   A
            legacy-only flag which when ``False`` disables *all* 0.5-style
            object accounting on transaction boundaries.
 
-           .. deprecated::  0.7
-
-                the :paramref:`.Session._enable_transaction_accounting`
-                parameter will be removed in a future release.
-
         :param expire_on_commit:  Defaults to ``True``. When ``True``, all
            instances will be fully expired after each :meth:`~.commit`,
            so that all attribute/object access subsequent to a completed
@@ -773,13 +792,6 @@ class Session(_SessionClassMethods):
            of such instances, which will receive pre- and post- commit and
            flush events, as well as a post-rollback event.
 
-           .. deprecated:: 0.7
-
-                :class:`.SessionExtension` is deprecated in favor of the
-                :class:`.SessionEvents` listener interface.  The
-                :paramref:`.Session.extension` parameter will be
-                removed in a future release.
-
         :param info: optional dictionary of arbitrary data to be associated
            with this :class:`.Session`.  Is available via the
            :attr:`.Session.info` attribute.  Note the dictionary is copied at
@@ -807,30 +819,14 @@ class Session(_SessionClassMethods):
            strongly referenced until explicitly removed or the
            :class:`.Session` is closed.
 
-           .. deprecated:: 1.0
-
-               The :paramref:`.Session.weak_identity_map` parameter as well as
-               the strong-referencing identity map are deprecated, and will be
-               removed in a future release.  For the use case where objects
-               present in a :class:`.Session` need to be automatically strong
-               referenced, see the recipe at
-               :ref:`session_referencing_behavior` for an event-based approach
-               to maintaining strong identity references.
-
 
         """
 
-        if weak_identity_map:
+        if weak_identity_map in (True, None):
             self._identity_cls = identity.WeakInstanceDict
         else:
-            util.warn_deprecated(
-                "weak_identity_map=False is deprecated.  "
-                "See the documentation on 'Session Referencing Behavior' "
-                "for an event-based approach to maintaining strong identity "
-                "references."
-            )
-
             self._identity_cls = identity.StrongInstanceDict
+
         self.identity_map = self._identity_cls()
 
         self._new = {}  # InstanceState->object, strong refs object
@@ -846,8 +842,9 @@ class Session(_SessionClassMethods):
         self.expire_on_commit = expire_on_commit
         self.enable_baked_queries = enable_baked_queries
         self._enable_transaction_accounting = _enable_transaction_accounting
+
         self.twophase = twophase
-        self._query_cls = query_cls
+        self._query_cls = query_cls if query_cls else query.Query
         if info:
             self.info.update(info)
 
@@ -1068,7 +1065,7 @@ class Session(_SessionClassMethods):
 
         Alternatively, if this :class:`.Session` is configured with
         ``autocommit=True``, an ad-hoc :class:`.Connection` is returned
-        using :meth:`.Engine.contextual_connect` on the underlying
+        using :meth:`.Engine.connect` on the underlying
         :class:`.Engine`.
 
         Ambiguity in multi-bind or unbound :class:`.Session` objects can be
@@ -1132,7 +1129,7 @@ class Session(_SessionClassMethods):
                 engine, execution_options
             )
         else:
-            conn = engine.contextual_connect(**kw)
+            conn = engine._contextual_connect(**kw)
             if execution_options:
                 conn = conn.execution_options(**execution_options)
             return conn
@@ -2872,7 +2869,15 @@ class Session(_SessionClassMethods):
         finally:
             self._flushing = False
 
-    def is_modified(self, instance, include_collections=True, passive=True):
+    @util.deprecated_params(
+        passive=(
+            "0.8",
+            "The :paramref:`.Session.is_modified.passive` flag is deprecated "
+            "and will be removed in a future release.  The flag is no longer "
+            "used and is ignored.",
+        )
+    )
+    def is_modified(self, instance, include_collections=True, passive=None):
         r"""Return ``True`` if the given instance has locally
         modified attributes.
 
@@ -2921,11 +2926,7 @@ class Session(_SessionClassMethods):
          way to detect only local-column based properties (i.e. scalar columns
          or many-to-one foreign keys) that would result in an UPDATE for this
          instance upon flush.
-        :param passive:
-
-         .. deprecated:: 0.8
-             The ``passive`` flag is deprecated and will be removed
-             in a future release.  The flag is no longer used and is ignored.
+        :param passive: not used
 
         """
         state = object_state(instance)
diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index b3f52a2f7..6f9746daa 100644
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -818,7 +818,6 @@ See :func:`.orm.%(name)s` for usage examples.
         return self
 
     def _add_unbound_all_fn(self, fn):
-        self._unbound_all_fn = fn
         fn.__doc__ = """Produce a standalone "all" option for :func:`.orm.%(name)s`.
 
 .. deprecated:: 0.9
@@ -834,6 +833,15 @@ See :func:`.orm.%(name)s` for usage examples.
 """ % {
             "name": self.name
         }
+        fn = util.deprecated(
+            "0.9",
+            "The :func:`.%(name)s_all` function is deprecated, and will be "
+            "removed in a future release.  Please use method chaining with "
+            ":func:`.%(name)s` instead" % {"name": self.name},
+            add_deprecation_to_docstring=False,
+        )(fn)
+
+        self._unbound_all_fn = fn
         return self
 
 
@@ -1307,8 +1315,8 @@ def defaultload(*keys):
 
 @loader_option()
 def defer(loadopt, key):
-    r"""Indicate that the given column-oriented attribute should be deferred, e.g.
-    not loaded until accessed.
+    r"""Indicate that the given column-oriented attribute should be deferred,
+    e.g. not loaded until accessed.
 
     This function is part of the :class:`.Load` interface and supports
     both method-chained and standalone operation.
@@ -1346,10 +1354,16 @@ def defer(loadopt, key):
 
     :param key: Attribute to be deferred.
 
-    :param \*addl_attrs: Deprecated; this option supports the old 0.8 style
+    :param \*addl_attrs: This option supports the old 0.8 style
      of specifying a path as a series of attributes, which is now superseded
      by the method-chained style.
 
+        .. deprecated:: 0.9  The \*addl_attrs on :func:`.orm.defer` is
+           deprecated and will be removed in a future release.   Please
+           use method chaining in conjunction with defaultload() to
+           indicate a path.
+
+
     .. seealso::
 
         :ref:`deferred`
@@ -1364,6 +1378,12 @@ def defer(loadopt, key):
 
 @defer._add_unbound_fn
 def defer(key, *addl_attrs):
+    if addl_attrs:
+        util.warn_deprecated(
+            "The *addl_attrs on orm.defer is deprecated.  Please use "
+            "method chaining in conjunction with defaultload() to "
+            "indicate a path."
+        )
     return _UnboundLoad._from_keys(
         _UnboundLoad.defer, (key,) + addl_attrs, False, {}
     )
@@ -1389,12 +1409,21 @@ def undefer(loadopt, key):
         session.query(MyClass, MyOtherClass).options(
             Load(MyClass).undefer("*"))
 
+        # undefer a column on a related object
+        session.query(MyClass).options(
+            defaultload(MyClass.items).undefer('text'))
+
     :param key: Attribute to be undeferred.
 
-    :param \*addl_attrs: Deprecated; this option supports the old 0.8 style
+    :param \*addl_attrs: This option supports the old 0.8 style
      of specifying a path as a series of attributes, which is now superseded
      by the method-chained style.
 
+        .. deprecated:: 0.9  The \*addl_attrs on :func:`.orm.undefer` is
+           deprecated and will be removed in a future release.   Please
+           use method chaining in conjunction with defaultload() to
+           indicate a path.
+
     .. seealso::
 
         :ref:`deferred`
@@ -1411,6 +1440,12 @@ def undefer(loadopt, key):
 
 @undefer._add_unbound_fn
 def undefer(key, *addl_attrs):
+    if addl_attrs:
+        util.warn_deprecated(
+            "The *addl_attrs on orm.undefer is deprecated.  Please use "
+            "method chaining in conjunction with defaultload() to "
+            "indicate a path."
+        )
     return _UnboundLoad._from_keys(
         _UnboundLoad.undefer, (key,) + addl_attrs, False, {}
     )