From: Eitan Mosenkis <eitan@mosenkis.net>
Date: Mon, 14 Nov 2022 21:11:15 +0000 (+0200)
Subject: Explicitly state what happens if `order_by` is called more than once. (#8791)
X-Git-Tag: rel_1_4_45~31
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b5ee0c7ff566291ce5823ba3e0ea624946c966b5;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Explicitly state what happens if `order_by` is called more than once. (#8791)

* Explicitly state what happens if `order_by` is called more than once.

The existing docs cover how to clear existing `order_by` clauses but don't actually describe the behavior of calling `order_by` multiple times with different clauses.

* Also update Select.order_by.

(cherry picked from commit 9237bf15e612ba82555444751bd69dc2a831e7f4)
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 65b6bf81a0..cef98201f3 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1819,9 +1819,10 @@ class Query(
 
             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.::
+        Calling this method multiple times is equivalent to calling it once
+        with all the clauses concatenated. 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)
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 956f8ae8d8..f8252cbe46 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -3876,9 +3876,10 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
 
             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.::
+        Calling this method multiple times is equivalent to calling it once
+        with all the clauses concatenated. 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
             stmt = stmt.order_by(None).order_by(new_col)