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

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index 14ea82a0ddd2bb5e82429bc5e65b0d0b46b8b979..9842ece51f1bfaa37c65ec40be87cd893f5dfe54 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 3caa380ee48ef401ed074af4843e6d18440d3ebc..3045cb84ebe1341f70ab053be22b41e7159d66d5 100644 (file)
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -2214,7 +2214,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 4a1a0dcd4c3868560e1f17e6aff49dd21d299386..3aeaaa601f6e4a3f1b2d47961101e25650e0f3ae 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_([]))