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 9a77b23c19ca2d0f4754b8a4173a209cfbdcbe02..a168760b31bb70b8a5df43cf32c7693d2ea94b5a 100644 (file)
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -781,6 +781,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 3fe26f83efbce17cb1ba454394a51cd650b2c451..513ab74d8e406c927e9ddfc6881f654d7cbe7c97 100644 (file)
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -2056,7 +2056,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 7a46352a6f82d87661d7f5e870064f9d98b130ac..b8435c2f84a2e5c51f334aa58712bd9b626b4fd2 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_([]))