Clarify order_by(False)

It wasn't clear how this differs from order_by(None);
add more tests and document that this has to do with whether or
not mapper.order_by will be re-enabled as well.

Change-Id: I332e8ac60c999b38c5a243f1cb72de3cf77891b6

1 files changed, 4 insertions, 5 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index c5ecbaffe..f15f4340b 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1523,17 +1523,16 @@ class Query(object):
         passing ``None`` - this will suppress any ORDER BY configured
         on mappers as well.
 
-        Alternatively, an existing ORDER BY setting on the Query
-        object can be entirely cancelled by passing ``False``
-        as the value - use this before calling methods where
-        an ORDER BY is invalid.
+        Alternatively, passing False will reset ORDER BY and additionally
+        re-allow default mapper.order_by to take place.   Note mapper.order_by
+        is deprecated.
 
         """
 
         if len(criterion) == 1:
             if criterion[0] is False:
                 if '_order_by' in self.__dict__:
-                    del self._order_by
+                    self._order_by = False
                 return
             if criterion[0] is None:
                 self._order_by = None