From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 1 Oct 2015 13:37:53 +0000 (-0400)
Subject: - remove ambiguous use of the phrase "joined together by AND" as this
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e66297ea3798d6d7d059e96e4ae90e94f8f53cfa;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- 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

(cherry picked from commit ac08920284935e7e7519ce77ba369703390155dc)
---

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index dea1a114b6..d538dcaa53 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -808,11 +808,17 @@ Here's a rundown of some of the most common operators used in :func:`~sqlalchemy
     # or call filter()/filter_by() multiple times
     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_
     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 e604e2dc70..7c049da344 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1202,7 +1202,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)
@@ -1211,9 +1213,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.
@@ -1237,7 +1236,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)