From b5ee0c7ff566291ce5823ba3e0ea624946c966b5 Mon Sep 17 00:00:00 2001 From: Eitan Mosenkis Date: Mon, 14 Nov 2022 23:11:15 +0200 Subject: [PATCH] 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) --- lib/sqlalchemy/orm/query.py | 7 ++++--- lib/sqlalchemy/sql/selectable.py | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) 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) -- 2.47.2