From 6a60d7305bafc311115543e0c2cb5136a254edf2 Mon Sep 17 00:00:00 2001
From: Stepland <16676308+Stepland@users.noreply.github.com>
Date: Mon, 16 Sep 2019 11:40:29 -0400
Subject: 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
---
 lib/sqlalchemy/sql/elements.py  | 3 ++-
 lib/sqlalchemy/sql/operators.py | 6 ++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

(limited to 'lib/sqlalchemy/sql')

diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 3caa380ee..3045cb84e 100644
--- 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 4a1a0dcd4..3aeaaa601 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_([]))
-- 
cgit v1.2.1