diff --git a/docs/tutorial/where.md b/docs/tutorial/where.md index b6d08e72fa..120874a235 100644 --- a/docs/tutorial/where.md +++ b/docs/tutorial/where.md @@ -562,7 +562,7 @@ We could imagine that **Spider-Boy** is even **younger**. But because we don't k ### 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: {* ./docs_src/tutorial/where/tutorial006_py310.py ln[42:47] hl[44] *} @@ -579,6 +579,22 @@ We get `Black Lion` here too because although the age is not *strictly* less tha /// +### In + +Finally, we can use `in_` to get the rows where a column is a member of a collection of values: + +{* ./docs_src/tutorial/where/tutorial006b_py310.py ln[42:47] hl[44] *} + +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){.internal-link target=_blank} 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. ✨ diff --git a/docs_src/tutorial/where/tutorial006b_py310.py b/docs_src/tutorial/where/tutorial006b_py310.py new file mode 100644 index 0000000000..21a4e28c0f --- /dev/null +++ b/docs_src/tutorial/where/tutorial006b_py310.py @@ -0,0 +1,57 @@ +from sqlmodel import Field, Session, SQLModel, col, create_engine, select + + +class Hero(SQLModel, table=True): + id: int | None = Field(default=None, primary_key=True) + name: str + secret_name: str + age: int | None = 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() diff --git a/docs_src/tutorial/where/tutorial006b_py39.py b/docs_src/tutorial/where/tutorial006b_py39.py new file mode 100644 index 0000000000..deb0b23025 --- /dev/null +++ b/docs_src/tutorial/where/tutorial006b_py39.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() diff --git a/tests/test_tutorial/test_where/test_tutorial006b.py b/tests/test_tutorial/test_where/test_tutorial006b.py new file mode 100644 index 0000000000..237618afea --- /dev/null +++ b/tests/test_tutorial/test_where/test_tutorial006b.py @@ -0,0 +1,35 @@ +import importlib +from types import ModuleType + +import pytest +from sqlmodel import create_engine + +from ...conftest import PrintMock, needs_py310 + + +@pytest.fixture( + name="mod", + params=[ + pytest.param("tutorial006b_py39"), + pytest.param("tutorial006b_py310", marks=needs_py310), + ], +) +def get_module(request: pytest.FixtureRequest) -> ModuleType: + mod = importlib.import_module(f"docs_src.tutorial.where.{request.param}") + mod.sqlite_url = "sqlite://" + mod.engine = create_engine(mod.sqlite_url) + return mod + + +def test_tutorial(print_mock: PrintMock, mod: ModuleType): + mod.main() + assert print_mock.calls == [ + [ + { + "name": "Deadpond", + "secret_name": "Dive Wilson", + "age": None, + "id": 1, + } + ] + ]