load_on_pending is different from enable_relationship_loading and should

not be superseded.  both have a potential use.

diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py
index c1cf07fbe1d9915d7c160c08c0e4a4381787cad0..c0004e742ac5e01288fe15e9aa257a043380b022 100644 (file)
--- a/lib/sqlalchemy/orm/relationships.py
+++ b/lib/sqlalchemy/orm/relationships.py
@@ -448,10 +448,6 @@ class RelationshipProperty(StrategizedProperty):
         :param load_on_pending=False:
           Indicates loading behavior for transient or pending parent objects.
 
-          .. versionchanged:: 0.8
-              load_on_pending is superseded by
-              :meth:`.Session.enable_relationship_loading`.
-
           When set to ``True``, causes the lazy-loader to
           issue a query for a parent object that is not persistent, meaning it has
           never been flushed.  This may take effect for a pending object when
@@ -467,6 +463,12 @@ class RelationshipProperty(StrategizedProperty):
 
           .. versionadded:: 0.6.5
 
+          .. seealso::
+
+              :meth:`.Session.load_on_pending` - this method establishes
+              "load on pending" behavior for the whole object, and also allows
+              loading on objects that remain transient or detached.
+
         :param order_by:
           indicates the ordering that should be applied when loading these
           items.  ``order_by`` is expected to refer to one of the :class:`.Column`

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index b3720c94e27a95eb15584eea2f6b812bd984b8dd..0c3bc5cbe4fedc5f7811a0243ef528c6ffd50c8a 100644 (file)
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -1758,8 +1758,8 @@ class Session(_SessionClassMethods):
         may not fire off a backref event, if the effective value
         is what was already loaded from a foreign-key-holding value.
 
-        The :meth:`.Session.enable_relationship_loading` method supersedes
-        the ``load_on_pending`` flag on :func:`.relationship`.   Unlike
+        The :meth:`.Session.enable_relationship_loading` method is
+        similar to the ``load_on_pending`` flag on :func:`.relationship`.   Unlike
         that flag, :meth:`.Session.enable_relationship_loading` allows
         an object to remain transient while still being able to load
         related items.
@@ -1776,6 +1776,12 @@ class Session(_SessionClassMethods):
 
         .. versionadded:: 0.8
 
+        .. seealso::
+
+            ``load_on_pending`` at :func:`.relationship` - this flag
+            allows per-relationship loading of many-to-ones on items that
+            are pending.
+
         """
         state = attributes.instance_state(obj)
         self._attach(state, include_before=True)