From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 28 Mar 2014 20:47:12 +0000 (-0400)
Subject: - the rewording of orderinglist docs got committed by accident, finish it up
X-Git-Tag: rel_0_8_6~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b4eeebbabebc3f26d68e09b8b3c6465cfec7b38d;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- the rewording of orderinglist docs got committed by accident, finish it up
---

diff --git a/lib/sqlalchemy/ext/orderinglist.py b/lib/sqlalchemy/ext/orderinglist.py
index e655099a47..172d3792c5 100644
--- a/lib/sqlalchemy/ext/orderinglist.py
+++ b/lib/sqlalchemy/ext/orderinglist.py
@@ -91,32 +91,24 @@ attribute, so that the ordering is correct when first loaded.
 .. warning::
 
   :class:`.OrderingList` only provides limited functionality when a primary
-  key column or unique column is the target of the sort.  The two operations
-  that are unsupported or are problematic are:
+  key column or unique column is the target of the sort.  Operations
+  that are unsupported or are problematic include:
 
     * two entries must trade values.  This is not supported directly in the
       case of a primary key or unique constraint because it means at least
       one row would need to be temporarily removed first, or changed to
       a third, neutral value while the switch occurs.
 
-    * an entry must be deleted in order to make room for a new entry.  SQLAlchemy's
-      unit of work performs all INSERTs before DELETEs within a single flush
-      by default.  A future feature will allow this to be configurable for
-      specific sets of columns on mappings.
-
-  Additional issues when using primary keys as ordering keys are that UPDATE
-  or DELETE statements on target rows may fail to fire correctly as orderinglist
-  may change their primary key value
-
-
-  Since changing the
-  order of entries often means that either rows must trade values,
-  or rows must be deleted to make way for new inserts, this is not
-  possible when the value is constrained by a primary key or unique
-  constraint, since one of the rows would temporarily have to point to a
-  third available value so that the other row could take its old
-  value. :class:`.OrderingList` doesn't do any of this for you,
-  nor does SQLAlchemy itself.
+    * an entry must be deleted in order to make room for a new entry.
+      SQLAlchemy's unit of work performs all INSERTs before DELETEs within a
+      single flush.  In the case of a primary key, it will trade
+      an INSERT/DELETE of the same primary key for an UPDATE statement in order
+      to lessen the impact of this lmitation, however this does not take place
+      for a UNIQUE column.
+      A future feature will allow the "DELETE before INSERT" behavior to be
+      possible, allevating this limitation, though this feature will require
+      explicit configuration at the mapper level for sets of columns that
+      are to be handled in this way.
 
 :func:`.ordering_list` takes the name of the related object's ordering attribute as
 an argument.  By default, the zero-based integer index of the object's