From f008df80c2127bf1234476bef023a9af02094f8b Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 29 Oct 2021 17:53:12 -0400 Subject: [PATCH] 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 --- lib/sqlalchemy/orm/query.py | 14 +++++++++++--- lib/sqlalchemy/sql/selectable.py | 9 ++++++++- 2 files changed, 19 insertions(+), 4 deletions(-) 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. -- 2.47.2