Add note on the use of tuple_() for the IN operator in the docs

Closes: #4861
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/4861
Pull-request-sha: c7379d390752d0c10d6488872b163b06ee30d952

Change-Id: I223008f720fe64951e2a0bf95aab955ece22516b
(cherry picked from commit 6a60d7305bafc311115543e0c2cb5136a254edf2)

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index 1b92ddced93353a96d531c2be3de11b66f74fcdc..09b6cd7e351745a7600b27ee461cefe015f14193 100644 (file)
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -783,6 +783,13 @@ Here's a rundown of some of the most common operators used in
         session.query(User.name).filter(User.name.like('%ed%'))
     ))
 
+    # use tuple_() for composite (multi-column) queries
+    from sqlalchemy import tuple_
+    query.filter(
+        tuple_(User.name, User.nickname).\
+        in_([('ed', 'edsnickname'), ('wendy', 'windy')])
+    )
+
 * :meth:`NOT IN <.ColumnOperators.notin_>`::
 
     query.filter(~User.name.in_(['ed', 'wendy', 'jack']))

diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 3f081de50d4c5b50044c10a8771eed83fac6a938..b7148bf501b5a79944498b74c6d18246f85679d7 100644 (file)
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -2108,7 +2108,8 @@ class Tuple(ClauseList, ColumnElement):
     def __init__(self, *clauses, **kw):
         """Return a :class:`.Tuple`.
 
-        Main usage is to produce a composite IN construct::
+        Main usage is to produce a composite IN construct using
+        :meth:`.ColumnOperators.in_` ::
 
             from sqlalchemy import tuple_
 

diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index ea7b51f799473fcf7739395f2727b58636d3f21f..fd8007f07d334299a105617ad971b24596fdd6a9 100644 (file)
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -528,6 +528,12 @@ class ColumnOperators(Operators):
 
             WHERE COL IN (?, ?, ?)
 
+        * A list of tuples may be provided if the comparison is against a
+          :func:`.tuple_` containing multiple expressions::
+
+            from sqlalchemy import tuple_
+            stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))
+
         * An empty list, e.g.::
 
             stmt.where(column.in_([]))