more docs on this

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 9068a133209388da9f0a4c25ebaa20f756936c8b..39c68f0aaf9da3625709c8b4b9f0f9395c9b587b 100644 (file)
--- 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 3bf8280f64543da62c1bf446eaa9a0f80a2eb808..6c5e8c81ca1969061d5c57879624705dfbc83907 100644 (file)
--- 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 982b4442009c0d7990962f2794f1e55a8de62aa6..ab3aafcbbc0872104061f42fe9cf9be941f9129a 100644 (file)
--- 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