📝 Add tutorial and tests for defining relationship attributes in SQLModel

Author: bolu61

docs_src/tutorial/relationship_attributes/define_relationship_attributes/tutorial001_an_py310.py

@@ -0,0 +1,70 @@
+from typing import Annotated
+
+from sqlmodel import Field, Relationship, Session, SQLModel, create_engine
+
+
+class Team(SQLModel, table=True):
+    id: Annotated[int | None, Field(primary_key=True)] = None
+    name: Annotated[str, Field(index=True)]
+    headquarters: str
+
+    heroes: Annotated[list["Hero"] | None, Relationship(back_populates="team")] = None
+
+
+class Hero(SQLModel, table=True):
+    id: Annotated[int | None, Field(primary_key=True)] = None
+    name: Annotated[str, Field(index=True)]
+    secret_name: str
+    age: Annotated[int | None, Field(index=True)] = None
+
+    team_id: Annotated[int | None, Field(foreign_key="team.id")] = None
+    team: Annotated[Team | None, Relationship(back_populates="heroes")] = 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():
+    with Session(engine) as session:
+        team_preventers = Team(name="Preventers", headquarters="Sharp Tower")
+        team_z_force = Team(name="Z-Force", headquarters="Sister Margaret's Bar")
+
+        hero_deadpond = Hero(
+            name="Deadpond", secret_name="Dive Wilson", team=team_z_force
+        )
+        hero_rusty_man = Hero(
+            name="Rusty-Man", secret_name="Tommy Sharp", age=48, team=team_preventers
+        )
+        hero_spider_boy = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
+        session.add(hero_deadpond)
+        session.add(hero_rusty_man)
+        session.add(hero_spider_boy)
+        session.commit()
+
+        session.refresh(hero_deadpond)
+        session.refresh(hero_rusty_man)
+        session.refresh(hero_spider_boy)
+
+        print("Created hero:", hero_deadpond)
+        print("Created hero:", hero_rusty_man)
+        print("Created hero:", hero_spider_boy)
+
+        hero_spider_boy.team = team_preventers
+        session.add(hero_spider_boy)
+        session.commit()
+
+
+def main():
+    create_db_and_tables()
+    create_heroes()
+
+
+if __name__ == "__main__":
+    main()

tests/test_tutorial/test_relationship_attributes/test_define_relationship_attributes/test_tutorial001_an_py310.py

@@ -0,0 +1,55 @@
+from unittest.mock import patch
+
+from sqlmodel import create_engine
+
+from ....conftest import get_testing_print_function, needs_py310
+
+expected_calls = [
+    [
+        "Created hero:",
+        {
+            "name": "Deadpond",
+            "age": None,
+            "team_id": 1,
+            "id": 1,
+            "secret_name": "Dive Wilson",
+        },
+    ],
+    [
+        "Created hero:",
+        {
+            "name": "Rusty-Man",
+            "age": 48,
+            "team_id": 2,
+            "id": 2,
+            "secret_name": "Tommy Sharp",
+        },
+    ],
+    [
+        "Created hero:",
+        {
+            "name": "Spider-Boy",
+            "age": None,
+            "team_id": None,
+            "id": 3,
+            "secret_name": "Pedro Parqueador",
+        },
+    ],
+]
+
+
+@needs_py310
+def test_tutorial(clear_sqlmodel):
+    from docs_src.tutorial.relationship_attributes.define_relationship_attributes import (
+        tutorial001_an_py310 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 == expected_calls