use ..deprecated directive w/ version in all cases

These changes should be ported from 1.3 back to 1.0 or
possibly 0.9 to the extent they are relevant in each
version. In 1.3 we hope to turn all deprecation documentation
into warnings.

Change-Id: I205186cde161af9389af513a425c62ce90dd54d8

12 files changed, 115 insertions, 58 deletions

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index d9f50e153..eedb89ecd 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -193,8 +193,8 @@ comparable_property = public_factory(
 
 @_sa_util.deprecated(
     "0.7",
-    message=":func:`.compile_mappers` "
-    "is renamed to :func:`.configure_mappers`",
+    message=":func:`.compile_mappers` is deprecated and will be removed "
+    "in a future release.  Please use :func:`.configure_mappers`",
 )
 def compile_mappers():
     """Initialize the inter-mapper relationships of all mappers that have
diff --git a/lib/sqlalchemy/orm/collections.py b/lib/sqlalchemy/orm/collections.py
index 2454f9fae..76d5713aa 100644
--- a/lib/sqlalchemy/orm/collections.py
+++ b/lib/sqlalchemy/orm/collections.py
@@ -428,6 +428,13 @@ class collection(object):
         return fn
 
     @staticmethod
+    @util.deprecated(
+        "1.0",
+        "The :meth:`.collection.linker` handler is deprecated and will "
+        "be removed in a future release.  Please refer to the "
+        ":meth:`.AttributeEvents.init_collection` "
+        "and :meth:`.AttributeEvents.dispose_collection` event handlers. "
+    )
     def linker(fn):
         """Tag the method as a "linked to attribute" event handler.
 
@@ -437,19 +444,27 @@ class collection(object):
         the instance.  A single argument is passed: the collection adapter
         that has been linked, or None if unlinking.
 
-        .. deprecated:: 1.0.0 - the :meth:`.collection.linker` handler
-           is superseded by the :meth:`.AttributeEvents.init_collection`
-           and :meth:`.AttributeEvents.dispose_collection` handlers.
 
         """
         fn._sa_instrument_role = "linker"
         return fn
 
     link = linker
-    """deprecated; synonym for :meth:`.collection.linker`."""
+    """Synonym for :meth:`.collection.linker`.
+
+    .. deprecated:: 1.0 - :meth:`.collection.link` is deprecated and will be
+       removed in a future release.
+
+    """
 
     @staticmethod
-    @util.deprecated("1.3", "Use the bulk_replace event handler")
+    @util.deprecated(
+        "1.3",
+        "The :meth:`.collection.converter` method 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."
+    )
     def converter(fn):
         """Tag the method as the collection converter.
 
diff --git a/lib/sqlalchemy/orm/deprecated_interfaces.py b/lib/sqlalchemy/orm/deprecated_interfaces.py
index 0b99ce85d..619bfaba1 100644
--- a/lib/sqlalchemy/orm/deprecated_interfaces.py
+++ b/lib/sqlalchemy/orm/deprecated_interfaces.py
@@ -14,11 +14,11 @@ from .. import util
 class MapperExtension(object):
     """Base implementation for :class:`.Mapper` event hooks.
 
-    .. note::
+    .. deprecated:: 0.7
 
-       :class:`.MapperExtension` is deprecated.   Please
-       refer to :func:`.event.listen` as well as
-       :class:`.MapperEvents`.
+       :class:`.MapperExtension` is deprecated and will be removed in a future
+       release.  Please refer to :func:`.event.listen` in conjunction with
+       the :class:`.MapperEvents` listener interface.
 
     New extension classes subclass :class:`.MapperExtension` and are specified
     using the ``extension`` mapper() argument, which is a single
@@ -318,11 +318,11 @@ class SessionExtension(object):
 
     """Base implementation for :class:`.Session` event hooks.
 
-    .. note::
+    .. deprecated:: 0.7
 
-       :class:`.SessionExtension` is deprecated.   Please
-       refer to :func:`.event.listen` as well as
-       :class:`.SessionEvents`.
+       :class:`.SessionExtension` is deprecated and will be removed in a future
+       release.  Please refer to :func:`.event.listen` in conjunction with
+       the :class:`.SessionEvents` listener interface.
 
     Subclasses may be installed into a :class:`.Session` (or
     :class:`.sessionmaker`) using the ``extension`` keyword
@@ -439,11 +439,11 @@ class AttributeExtension(object):
     """Base implementation for :class:`.AttributeImpl` event hooks, events
     that fire upon attribute mutations in user code.
 
-    .. note::
+    .. deprecated:: 0.7
 
-       :class:`.AttributeExtension` is deprecated.   Please
-       refer to :func:`.event.listen` as well as
-       :class:`.AttributeEvents`.
+       :class:`.AttributeExtension` is deprecated and will be removed in a
+       future release.  Please refer to :func:`.event.listen` in conjunction
+       with the :class:`.AttributeEvents` listener interface.
 
     :class:`.AttributeExtension` is used to listen for set,
     remove, and append events on individual mapped attributes.
diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py
index 0891a2a9d..8a217e4cd 100644
--- a/lib/sqlalchemy/orm/descriptor_props.py
+++ b/lib/sqlalchemy/orm/descriptor_props.py
@@ -145,7 +145,14 @@ class CompositeProperty(DescriptorProperty):
           an :class:`.AttributeExtension` instance,
           or list of extensions, which will be prepended to the list of
           attribute listeners for the resulting descriptor placed on the
-          class.  **Deprecated.**  Please see :class:`.AttributeEvents`.
+          class.
+
+           .. deprecated:: 0.7
+
+                :class:`.AttributeExtension` is deprecated in favor of the
+                :class:`.AttributeEvents` listener interface.  The
+                :paramref:`.CompositeProperty.extension` parameter will be
+                removed in a future release.
 
         """
         super(CompositeProperty, self).__init__()
diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 7c4cfc3ba..3ad5dfa7f 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -2070,8 +2070,6 @@ class AttributeEvents(event.Events):
                 else:
                     return value
 
-
-
         .. versionadded:: 1.2
 
         :param target: the object instance receiving the event.
@@ -2279,7 +2277,7 @@ class AttributeEvents(event.Events):
 
         .. versionadded:: 1.0.0 the :meth:`.AttributeEvents.init_collection`
            and :meth:`.AttributeEvents.dispose_collection` events supersede
-           the :class:`.collection.linker` hook.
+           the :class:`.orm.collection.linker` hook.
 
         """
 
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index c0a53694a..975ffb6ab 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -270,8 +270,14 @@ class Mapper(InspectionAttr):
 
         :param extension: A :class:`.MapperExtension` instance or
            list of :class:`.MapperExtension` instances which will be applied
-           to all operations by this :class:`.Mapper`.  **Deprecated.**
-           Please see :class:`.MapperEvents`.
+           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.
@@ -344,8 +350,9 @@ class Mapper(InspectionAttr):
            ordering.
 
            .. deprecated:: 1.1 The :paramref:`.Mapper.order_by` parameter
-              is deprecated.   Use :meth:`.Query.order_by` to determine the
-              ordering of a result set.
+              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.
diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index 3ea68a913..700e86566 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -122,12 +122,16 @@ class ColumnProperty(StrategizedProperty):
             .. versionadded:: 0.8
 
         :param extension:
-            an
-            :class:`.AttributeExtension`
-            instance, or list of extensions, which will be prepended
-            to the list of attribute listeners for the resulting
-            descriptor placed on the class.
-            **Deprecated.** Please see :class:`.AttributeEvents`.
+            an :class:`.AttributeExtension` instance, or list of extensions,
+            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:`.ColumnProperty.extension` parameter will be
+                removed in a future release.
 
         """
         super(ColumnProperty, self).__init__()
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index a4dddcd23..775a38635 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1595,7 +1595,11 @@ class Query(object):
         """Return a new :class:`.Query` object with the specified "locking mode",
         which essentially refers to the ``FOR UPDATE`` clause.
 
-        .. deprecated:: 0.9.0 superseded by :meth:`.Query.with_for_update`.
+        .. 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:
@@ -1756,12 +1760,9 @@ class Query(object):
         the newly resulting ``Query``
 
         All existing ORDER BY settings can be suppressed by
-        passing ``None`` - this will suppress any ORDER BY configured
-        on mappers as well.
-
-        Alternatively, passing False will reset ORDER BY and additionally
-        re-allow default mapper.order_by to take place.   Note mapper.order_by
-        is deprecated.
+        passing ``None`` - this will suppress any ordering configured
+        on the :func:`.mapper` object using the deprecated
+        :paramref:`.mapper.order_by` parameter.
 
         """
 
diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py
index 27a8c4ca9..b16a72996 100644
--- a/lib/sqlalchemy/orm/relationships.py
+++ b/lib/sqlalchemy/orm/relationships.py
@@ -411,7 +411,12 @@ class RelationshipProperty(StrategizedProperty):
           which will be prepended to the list of attribute listeners for
           the resulting descriptor placed on the class.
 
-          .. deprecated:: 0.7 Please see :class:`.AttributeEvents`.
+           .. deprecated:: 0.7
+
+                :class:`.AttributeExtension` is deprecated in favor of the
+                :class:`.AttributeEvents` listener interface. The
+                :paramref:`.RelationshipProperty.extension` parameter will be
+                removed in a future release.
 
         :param foreign_keys:
 
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index d226edf81..a275e44aa 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -751,10 +751,12 @@ class Session(_SessionClassMethods):
 
         :param _enable_transaction_accounting:  Defaults to ``True``.  A
            legacy-only flag which when ``False`` disables *all* 0.5-style
-           object accounting on transaction boundaries, including auto-expiry
-           of instances on rollback and commit, maintenance of the "new" and
-           "deleted" lists upon rollback, and autoflush of pending changes
-           upon :meth:`~.Session.begin`, all of which are interdependent.
+           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`,
@@ -764,8 +766,14 @@ class Session(_SessionClassMethods):
         :param extension: An optional
            :class:`~.SessionExtension` instance, or a list
            of such instances, which will receive pre- and post- commit and
-           flush events, as well as a post-rollback event. **Deprecated.**
-           Please see :class:`.SessionEvents`.
+           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
@@ -792,11 +800,18 @@ class Session(_SessionClassMethods):
         :param weak_identity_map:  Defaults to ``True`` - when set to
            ``False``, objects placed in the :class:`.Session` will be
            strongly referenced until explicitly removed or the
-           :class:`.Session` is closed.  **Deprecated** - The strong
-           reference identity map is legacy.  See the
-           recipe at :ref:`session_referencing_behavior` for
-           an event-based approach to maintaining strong identity
-           references.
+           :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.
+
 
         """
 
@@ -1757,8 +1772,9 @@ class Session(_SessionClassMethods):
 
     @util.deprecated(
         "0.7",
-        "The non-weak-referencing identity map "
-        "feature is no longer needed.",
+        "The :meth:`.Session.prune` method is deprecated along with "
+        ":paramref:`.Session.weak_identity_map`.  This method will be "
+        "removed in a future release.",
     )
     def prune(self):
         """Remove unreferenced instances cached in the identity map.
diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index 2d0716991..3aaf70013 100644
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -821,9 +821,11 @@ See :func:`.orm.%(name)s` for usage examples.
         self._unbound_all_fn = fn
         fn.__doc__ = """Produce a standalone "all" option for :func:`.orm.%(name)s`.
 
-.. deprecated:: 0.9.0
+.. deprecated:: 0.9
 
-    The "_all()" style is replaced by method chaining, e.g.::
+    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, as in::
 
         session.query(MyClass).options(
             %(name)s("someattribute").%(name)s("anotherattribute")
diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index 4a1e18c1a..1f30fafec 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -1085,8 +1085,10 @@ def join(
     See :meth:`.Query.join` for information on modern usage
     of ORM level joins.
 
-    .. versionchanged:: 0.8.1 - the ``join_to_left`` parameter
-       is no longer used, and is deprecated.
+    .. deprecated:: 0.8
+
+        the ``join_to_left`` parameter is deprecated, and will be removed
+        in a future release.  The parameter has no effect.
 
     """
     return _ORMJoin(left, right, onclause, isouter, full)