From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 16 Dec 2013 01:06:27 +0000 (-0500)
Subject: load_on_pending is different from enable_relationship_loading and should
X-Git-Tag: rel_0_8_5~77
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=296f648e39e1fd05f028f156b9817d2de35217e3;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 fb489866a0..9677e55c61 100644
--- 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 dc8b936ca4..9eceeae8c3 100644
--- 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)