- The "objects" argument to session.flush() is deprecated.

State which represents the linkage between a parent and
child object does not support "flushed" status on
one side of the link and not the other, so supporting
this operation leads to misleading results.
[ticket:1315]

diff --git a/CHANGES b/CHANGES
index f47e3ebcb8022007500bfd9663915121ed4f0d44..d2d9304e731e95f9b49abee0afc0f292a8c9a18d 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -6,6 +6,13 @@ CHANGES
 0.5.3
 =====
 - orm
+    - The "objects" argument to session.flush() is deprecated.
+      State which represents the linkage between a parent and
+      child object does not support "flushed" status on
+      one side of the link and not the other, so supporting
+      this operation leads to misleading results.
+      [ticket:1315]
+    
     - Query now implements __clause_element__() which produces
       its selectable, which means a Query instance can be accepted 
       in many SQL expressions, including col.in_(query), 

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 1c061c7ebf3298c7abb7454eb8168cef841c0e7e..5e01443a6833ead2d03de6094cf16544b36ff75f 100644 (file)
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -1333,8 +1333,15 @@ class Session(object):
         objects
           Optional; a list or tuple collection.  Restricts the flush operation
           to only these objects, rather than all pending changes.
+          Deprecated - this flag prevents the session from properly maintaining
+          accounting among inter-object relations and can cause invalid results.
 
         """
+
+        if objects:
+            util.warn_deprecated(
+                "The 'objects' argument to session.flush() is deprecated; "
+                "Please do not add objects to the session which should not yet be persisted.")
         
         if self._flushing:
             raise sa_exc.InvalidRequestError("Session is already flushing")

diff --git a/test/orm/cascade.py b/test/orm/cascade.py
index 746dc0e52f768614e76429624c1518b2044ae00f..c827a85cedec8eaf6d84f9c83fe36f77d9cd1622 100644 (file)
--- a/test/orm/cascade.py
+++ b/test/orm/cascade.py
@@ -1200,7 +1200,7 @@ class PartialFlushTest(_base.MappedTest):
             Column("parent_id", Integer, ForeignKey("parent.id"))
         )
 
-
+    @testing.uses_deprecated()
     @testing.resolve_artifact_names
     def test_o2m_m2o(self):
         class Base(_base.ComparableEntity):
@@ -1250,6 +1250,7 @@ class PartialFlushTest(_base.MappedTest):
         assert c2 in sess and c2 not in sess.new
         assert b1 in sess and b1 in sess.new
 
+    @testing.uses_deprecated()
     @testing.resolve_artifact_names
     def test_circular_sort(self):
         """test ticket 1306"""