From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 12 Sep 2010 23:52:41 +0000 (-0400)
Subject: more docs on this
X-Git-Tag: rel_0_6_5~70
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=18f6a06a51943198a9a375c781c2dbc1511d24a5;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

more docs on this
---

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 9068a13320..39c68f0aaf 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -356,12 +356,12 @@ def relationship(argument, secondary=None, **kwargs):
        
       Detailed discussion of loader strategies is at :ref:`loading_toplevel`.
     
-    :param load_on_pending:
+    :param load_on_pending=False:
       Indicates loading behavior for transient or pending parent objects.
       
-      This is an advanced user feature that will cause the lazy-loader to
+      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
+      never been flushed.  This may take effect for a pending object when
       autoflush is disabled, or for a transient object that has been
       "attached" to a :class:`.Session` but is not part of its pending
       collection. Attachment of transient objects to the session without
@@ -373,6 +373,12 @@ def relationship(argument, secondary=None, **kwargs):
       object is ultimately flushed, only the user-specific foreign key 
       attributes will be part of the modified state.
       
+      The load_on_pending flag does not improve behavior
+      when the ORM is used normally - object references should be constructed
+      at the object level, not at the foreign key level, so that they
+      are present in an ordinary way before flush() proceeds.  This flag
+      is not not intended for general use.
+      
       New in 0.6.5.
       
     :param order_by:
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 3bf8280f64..6c5e8c81ca 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -633,16 +633,14 @@ class Query(object):
 
     @_generative()
     def populate_existing(self):
-        """Return a Query that will refresh all instances loaded.
-
-        This includes all entities accessed from the database, including
-        secondary entities, eagerly-loaded collection items.
-
-        All changes present on entities which are already present in the
-        session will be reset and the entities will all be marked "clean".
-
-        An alternative to populate_existing() is to expire the Session
-        fully using session.expire_all().
+        """Return a :class:`Query` that will expire and refresh all instances 
+        as they are loaded, or reused from the current :class:`.Session`.
+        
+        :meth:`.populate_existing` does not improve behavior when 
+        the ORM is used normally - the :class:`.Session` object's usual 
+        behavior of maintaining a transaction and expiring all attributes
+        after rollback or commit handles object state automatically.
+        This method is not intended for general use.
 
         """
         self._populate_existing = True
diff --git a/test/orm/test_load_on_fks.py b/test/orm/test_load_on_fks.py
index 982b444200..ab3aafcbbc 100644
--- a/test/orm/test_load_on_fks.py
+++ b/test/orm/test_load_on_fks.py
@@ -127,6 +127,23 @@ class LoadOnFKsTest(AssertsExecutionResults, TestBase):
         c3.parent = p1
         
         assert c3 in p1.children
+    
+    def test_autoflush_on_pending(self):
+        c3 = Child()
+        sess.add(c3)
+        c3.parent_id = p1.id
+        
+        # pendings don't autoflush
+        assert c3.parent is None
+
+    def test_autoflush_on_pending(self):
+        Child.parent.property.load_on_pending = True
+        c3 = Child()
+        sess.add(c3)
+        c3.parent_id = p1.id
+        
+        # ...unless the flag is on
+        assert c3.parent is p1
         
     def test_load_on_pending_with_set(self):
         Child.parent.property.load_on_pending = True