From: Stepland <16676308+Stepland@users.noreply.github.com>
Date: Mon, 16 Sep 2019 15:40:29 +0000 (-0400)
Subject: Add note on the use of tuple_() for the IN operator in the docs
X-Git-Tag: rel_1_3_9~15
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d3eecfb7013a70127e39e73e9ddfde8a18689c7f;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 1b92ddced9..09b6cd7e35 100644
--- 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 3f081de50d..b7148bf501 100644
--- 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 ea7b51f799..fd8007f07d 100644
--- 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_([]))