load_on_pending is different from enable_relationship_loading and should

not be superseded.  both have a potential use.

Conflicts:
	lib/sqlalchemy/orm/relationships.py

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index fb489866a0c62d2df6e05fed74ae3b9169cde112..9677e55c61f841f6f2707acd7639e15b59075e3b 100644 (file)
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -502,10 +502,6 @@ def relationship(argument, secondary=None, **kwargs):
     :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
@@ -521,6 +517,12 @@ def relationship(argument, secondary=None, **kwargs):
 
       .. 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 dc8b936ca4fb18777a3b40828b02b1ed4c9c9cd3..9eceeae8c39699775447f8369a1035a2d0c956f1 100644 (file)
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -1703,8 +1703,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.
@@ -1721,6 +1721,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)