From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 29 Oct 2021 21:53:12 +0000 (-0400)
Subject: clarify order_by(None) for Core; improve wording
X-Git-Tag: rel_1_4_27~24
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f008df80c2127bf1234476bef023a9af02094f8b;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

clarify order_by(None) for Core; improve wording

the order_by(None) convention was documented for orm.Query
but not Core select.

Change-Id: I0c1ad76c3eefba1cb54b1649cfd09169c17e2bba
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 83b2994075..eab7a3d75a 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1799,11 +1799,19 @@ class Query(
     @_generative
     @_assertions(_no_statement_condition, _no_limit_offset)
     def order_by(self, *clauses):
-        """Apply one or more ORDER BY criterion to the query and return
+        """Apply one or more ORDER BY criteria to the query and return
         the newly resulting :class:`_query.Query`.
 
-        All existing ORDER BY settings can be suppressed by  passing
-        ``None``.
+        e.g.::
+
+            q = session.query(Entity).order_by(Entity.id, Entity.name)
+
+        All existing ORDER BY criteria may be cancelled by passing
+        ``None`` by itself.  New ORDER BY criteria may then be added by
+        invoking :meth:`_orm.Query.order_by` again, e.g.::
+
+            # will erase all ORDER BY and ORDER BY new_col alone
+            q = q.order_by(None).order_by(new_col)
 
         .. seealso::
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index b0aaa5a31b..aed6482972 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -3781,12 +3781,19 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
     @_generative
     def order_by(self, *clauses):
         r"""Return a new selectable with the given list of ORDER BY
-        criterion applied.
+        criteria applied.
 
         e.g.::
 
             stmt = select(table).order_by(table.c.id, table.c.name)
 
+        All existing ORDER BY criteria may be cancelled by passing
+        ``None`` by itself.  New ORDER BY criteria may then be added by
+        invoking :meth:`_sql.Select.order_by` again, e.g.::
+
+            # will erase all ORDER BY and ORDER BY new_col alone
+            stmt = stmt.order_by(None).order_by(new_col)
+
         :param \*clauses: a series of :class:`_expression.ColumnElement`
          constructs
          which will be used to generate an ORDER BY clause.