From ac08920284935e7e7519ce77ba369703390155dc Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Thu, 1 Oct 2015 09:37:53 -0400 Subject: [PATCH] - remove ambiguous use of the phrase "joined together by AND" as this may be construed as the Python "and" keyword - add notes to ORM tutorial for beginners that Python "and" keyword is not to be used fixes #3545 --- doc/build/orm/tutorial.rst | 6 ++++++ lib/sqlalchemy/orm/query.py | 11 ++++++----- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index ed8d05534e..42e94338be 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -795,11 +795,17 @@ Here's a rundown of some of the most common operators used in # or chain multiple filter()/filter_by() calls query.filter(User.name == 'ed').filter(User.fullname == 'Ed Jones') + .. note:: Make sure you use :func:`.and_` and **not** the + Python ``and`` operator! + * :func:`OR <.sql.expression.or_>`:: from sqlalchemy import or_ query.filter(or_(User.name == 'ed', User.name == 'wendy')) + .. note:: Make sure you use :func:`.or_` and **not** the + Python ``or`` operator! + * :meth:`MATCH <.ColumnOperators.match>`:: query.filter(User.name.match('wendy')) diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index f0b8969a2a..0af22b2290 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -1292,7 +1292,9 @@ class Query(object): session.query(MyClass).filter(MyClass.name == 'some name') - Multiple criteria are joined together by AND:: + Multiple criteria may be specified as comma separated; the effect + is that they will be joined together using the :func:`.and_` + function:: session.query(MyClass).\\ filter(MyClass.name == 'some name', MyClass.id > 5) @@ -1301,9 +1303,6 @@ class Query(object): WHERE clause of a select. String expressions are coerced into SQL expression constructs via the :func:`.text` construct. - .. versionchanged:: 0.7.5 - Multiple criteria joined by AND. - .. seealso:: :meth:`.Query.filter_by` - filter on keyword expressions. @@ -1327,7 +1326,9 @@ class Query(object): session.query(MyClass).filter_by(name = 'some name') - Multiple criteria are joined together by AND:: + Multiple criteria may be specified as comma separated; the effect + is that they will be joined together using the :func:`.and_` + function:: session.query(MyClass).\\ filter_by(name = 'some name', id = 5) -- 2.47.2