From 094a8550f18465b86e7288e04cabedc1f56c47aa Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 28 Mar 2014 16:47:12 -0400 Subject: - the rewording of orderinglist docs got committed by accident, finish it up --- lib/sqlalchemy/ext/orderinglist.py | 32 ++++++++++++-------------------- 1 file changed, 12 insertions(+), 20 deletions(-) diff --git a/lib/sqlalchemy/ext/orderinglist.py b/lib/sqlalchemy/ext/orderinglist.py index 16bab6b29..c4ba6d571 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 -- cgit v1.2.1