Document IN()

docs/tutorial/where.md

@@ -665,7 +665,7 @@ age=32 id=4 name='Tarantula' secret_name='Natalia Roman-on'
 
 ### Less Than or Equal
 
-Finally, we can use `<=` to get the rows where a column is **less than or equal** to a value:
+We can also use `<=` to get the rows where a column is **less than or equal** to a value:
 
 ```Python hl_lines="5"
 # Code above omitted 👆
@@ -694,6 +694,34 @@ age=35 id=5 name='Black Lion' secret_name='Trevor Challa'
 !!! tip
     We get `Black Lion` here too because although the age is not *strictly* less than `35` it is *equal* to `35`.
 
+### In
+
+Finally, we can use `in_ to get the rows where a column is a member of a collection of values:
+
+```Python hl_lines="5"
+# Code above omitted 👆
+
+{!./docs_src/tutorial/where/tutorial0066.py[ln:44-49]!}
+
+# Code below omitted 👇
+```
+
+<details>
+<summary>👀 Full file preview</summary>
+
+```Python
+{!./docs_src/tutorial/where/tutorial0065.py!}
+```
+
+</details>
+
+In this case, we match `Deadpond` since it's part of the collections of names.
+We don't have any hero called `Ratman`, so it does not match any hero.
+
+!!! tip
+    You need to wrap your attribute with `col()` to use `in_`.
+    You can read more about it in the (Type annotations and errors)[#type-annotations-and-errors] section.
+
 ### Benefits of Expressions
 
 Here's a good moment to see that being able to use these pure Python expressions instead of keyword arguments can help a lot. ✨

docs_src/tutorial/where/tutorial0065.py

@@ -0,0 +1,59 @@
+from typing import Optional
+
+from sqlmodel import Field, Session, SQLModel, col, create_engine, select
+
+
+class Hero(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str
+    secret_name: str
+    age: Optional[int] = None
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def create_heroes():
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+    hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)
+    hero_4 = Hero(name="Tarantula", secret_name="Natalia Roman-on", age=32)
+    hero_5 = Hero(name="Black Lion", secret_name="Trevor Challa", age=35)
+    hero_6 = Hero(name="Dr. Weird", secret_name="Steve Weird", age=36)
+    hero_7 = Hero(name="Captain North America", secret_name="Esteban Rogelios", age=93)
+
+    with Session(engine) as session:
+        session.add(hero_1)
+        session.add(hero_2)
+        session.add(hero_3)
+        session.add(hero_4)
+        session.add(hero_5)
+        session.add(hero_6)
+        session.add(hero_7)
+
+        session.commit()
+
+
+def select_heroes():
+    with Session(engine) as session:
+        statement = select(Hero).where(col(Hero.name).in_(["Deadpond", "Ratman"]))
+        results = session.exec(statement)
+        for hero in results:
+            print(hero)
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+    select_heroes()
+
+
+if __name__ == "__main__":
+    main()

tests/test_tutorial/test_where/test_tutorial0065.py

@@ -0,0 +1,28 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ...conftest import get_testing_print_function
+
+
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.where import tutorial0065 as mod
+
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    calls = []
+
+    new_print = get_testing_print_function(calls)
+
+    with patch("builtins.print", new=new_print):
+        mod.main()
+    assert calls == [
+        [
+            {
+                "name": "Deadpond",
+                "secret_name": "Dive Wilson",
+                "age": None,
+                "id": 1,
+            }
+        ]
+    ]