📝 Add source examples for Python 3.9 and 3.10 (#715)

* 📝 Add source examples for Python 3.9 and 3.10

* ✅ Add tests for new source examples for Python 3.9 and 3.10, still needs pytest markers

* ✅ Add tests for fastapi examples

* ✅ Update tests for FastAPI app testing, for Python 3.9 and 3.10, fixing multi-app testing conflicts

* ✅ Require Python 3.9 and 3.10 for tests

* ✅ Update tests with missing markers

docs_src/tutorial/fastapi/app_testing/tutorial001/test_extra_coverage.py

@@ -0,0 +1,38 @@
+from fastapi.testclient import TestClient
+from sqlalchemy import Inspector, inspect
+from sqlmodel import Session, create_engine
+
+from . import main as app_mod
+from .test_main import client_fixture, session_fixture
+
+assert client_fixture, "This keeps the client fixture used below"
+assert session_fixture, "This keeps the session fixture used by client_fixture"
+
+
+def test_startup():
+    app_mod.engine = create_engine("sqlite://")
+    app_mod.on_startup()
+    insp: Inspector = inspect(app_mod.engine)
+    assert insp.has_table(str(app_mod.Hero.__tablename__))
+
+
+def test_get_session():
+    app_mod.engine = create_engine("sqlite://")
+    for session in app_mod.get_session():
+        assert isinstance(session, Session)
+        assert session.bind == app_mod.engine
+
+
+def test_read_hero_not_found(client: TestClient):
+    response = client.get("/heroes/9000")
+    assert response.status_code == 404
+
+
+def test_update_hero_not_found(client: TestClient):
+    response = client.patch("/heroes/9000", json={"name": "Very-Rusty-Man"})
+    assert response.status_code == 404
+
+
+def test_delete_hero_not_found(client: TestClient):
+    response = client.delete("/heroes/9000")
+    assert response.status_code == 404

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_001.md

@@ -0,0 +1,17 @@
+1. Import the `app` from the the `main` module.
+
+2. We create a `TestClient` for the FastAPI `app` and put it in the variable `client`.
+
+3. Then we use use this `client` to **talk to the API** and send a `POST` HTTP operation, creating a new hero.
+
+4. Then we get the **JSON data** from the response and put it in the variable `data`.
+
+5. Next we start testing the results with `assert` statements, we check that the status code of the response is `200`.
+
+6. We check that the `name` of the hero created is `"Deadpond"`.
+
+7. We check that the `secret_name` of the hero created is `"Dive Wilson"`.
+
+8. We check that the `age` of the hero created is `None`, because we didn't send an age.
+
+9. We check that the hero created has an `id` created by the database, so it's not `None`.

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_002.md

@@ -0,0 +1,25 @@
+1. Import the `get_session` dependency from the the `main` module.
+
+2. Define the new function that will be the new **dependency override**.
+
+3. This function will return a different **session** than the one that would be returned by the original `get_session` function.
+
+    We haven't seen how this new **session** object is created yet, but the point is that this is a different session than the original one from the app.
+
+    This session is attached to a different **engine**, and that different **engine** uses a different URL, for a database just for testing.
+
+    We haven't defined that new **URL** nor the new **engine** yet, but here we already see the that this object `session` will override the one returned by the original dependency  `get_session()`.
+
+4. Then, the FastAPI `app` object has an attribute `app.dependency_overrides`.
+
+    This attribute is a dictionary, and we can put dependency overrides in it by passing, as the **key**, the **original dependency function**, and as the **value**, the **new overriding dependency function**.
+
+    So, here we are telling the FastAPI app to use `get_session_override` instead of `get_session` in all the places in the code that depend on `get_session`, that is, all the parameters with something like:
+
+    ```Python
+    session: Session = Depends(get_session)
+    ```
+
+5. After we are done with the dependency override, we can restore the application back to normal, by removing all the values in this dictionary `app.dependency_overrides`.
+
+    This way whenever a *path operation function* needs the dependency FastAPI will use the original one instead of the override.

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_003.md

@@ -0,0 +1,37 @@
+1. Here's a subtle thing to notice.
+
+    Remember that [Order Matters](../create-db-and-table.md#sqlmodel-metadata-order-matters){.internal-link target=_blank} and we need to make sure all the **SQLModel** models are already defined and **imported** before calling `.create_all()`.
+
+    IN this line, by importing something, *anything*, from `.main`, the code in `.main` will be executed, including the definition of the **table models**, and that will automatically register them in `SQLModel.metadata`.
+
+2. Here we create a new **engine**, completely different from the one in `main.py`.
+
+    This is the engine we will use for the tests.
+
+    We use the new URL of the database for tests:
+
+    ```
+    sqlite:///testing.db
+    ```
+
+    And again, we use the connection argument `check_same_thread=False`.
+
+3. Then we call:
+
+    ```Python
+    SQLModel.metadata.create_all(engine)
+    ```
+
+    ...to make sure we create all the tables in the new testing database.
+
+    The **table models** are registered in `SQLModel.metadata` just because we imported *something* from `.main`, and the code in `.main` was executed, creating the classes for the **table models** and automatically registering them in `SQLModel.metadata`.
+
+    So, by the point we call this method, the **table models** are already registered there. 💯
+
+4. Here's where we create the custom **session** object for this test in a `with` block.
+
+    It uses the new custom **engine** we created, so anything that uses this session will be using the testing database.
+
+5. Now, back to the dependency override, it is just returning the same **session** object from outside, that's it, that's the whole trick.
+
+6. By this point, the testing **session** `with` block finishes, and the session is closed, the file is closed, etc.

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_004.md

@@ -0,0 +1,26 @@
+1. Import `StaticPool` from `sqlmodel`, we will use it in a bit.
+
+2. For the **SQLite URL**, don't write any file name, leave it empty.
+
+    So, instead of:
+
+    ```
+    sqlite:///testing.db
+    ```
+
+    ...just write:
+
+    ```
+    sqlite://
+    ```
+
+    This is enough to tell **SQLModel** (actually SQLAlchemy) that we want to use an **in-memory SQLite database**.
+
+3. Remember that we told the **low-level** library in charge of communicating with SQLite that we want to be able to **access the database from different threads** with `check_same_thread=False`?
+
+    Now that we use an **in-memory database**, we need to also tell SQLAlchemy that we want to be able to use the **same in-memory database** object from different threads.
+
+    We tell it that with the `poolclass=StaticPool` parameter.
+
+    !!! info
+        You can read more details in the <a href="https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#using-a-memory-database-in-multiple-threads" class="external-link" target="_blank">SQLAlchemy documentation about Using a Memory Database in Multiple Threads</a>

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_005.md

@@ -0,0 +1,41 @@
+1. Import `pytest`.
+
+2. Use the `@pytest.fixture()` decorator on top of the function to tell pytest that this is a **fixture** function (equivalent to a FastAPI dependency).
+
+    We also give it a name of `"session"`, this will be important in the testing function.
+
+3. Create the fixture function. This is equivalent to a FastAPI dependency function.
+
+    In this fixture we create the custom **engine**, with the in-memory database, we create the tables, and we create the **session**.
+
+    Then we `yield` the `session` object.
+
+4. The thing that we `return` or `yield` is what will be available to the test function, in this case, the `session` object.
+
+    Here we use `yield` so that **pytest** comes back to execute "the rest of the code" in this function once the testing function is done.
+
+    We don't have any more visible "rest of the code" after the `yield`, but we have the end of the `with` block that will close the **session**.
+
+    By using `yield`, pytest will:
+
+    * run the first part
+    * create the **session** object
+    * give it to the test function
+    * run the test function
+    * once the test function is done, it will continue here, right after the `yield`, and will correctly close the **session** object in the end of the `with` block.
+
+5. Now, in the test function, to tell **pytest** that this test wants to get the fixture, instead of declaring something like in FastAPI with:
+
+    ```Python
+    session: Session = Depends(session_fixture)
+    ```
+
+    ...the way we tell pytest what is the fixture that we want is by using the **exact same name** of the fixture.
+
+    In this case, we named it `session`, so the parameter has to be exactly named `session` for it to work.
+
+    We also add the type annotation `session: Session` so that we can get autocompletion and inline error checks in our editor.
+
+6. Now in the dependency override function, we just return the same `session` object that came from outside it.
+
+    The `session` object comes from the parameter passed to the test function, and we just re-use it and return it here in the dependency override.

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_006.md

@@ -0,0 +1,23 @@
+1. Create the new fixture named `"client"`.
+
+2. This **client fixture**, in turn, also requires the **session fixture**.
+
+3. Now we create the **dependency override** inside the client fixture.
+
+4. Set the **dependency override** in the `app.dependency_overrides` dictionary.
+
+5. Create the `TestClient` with the **FastAPI** `app`.
+
+6. `yield` the `TestClient` instance.
+
+    By using `yield`, after the test function is done, pytest will come back to execute the rest of the code after `yield`.
+
+7. This is the cleanup code, after `yield`, and after the test function is done.
+
+    Here we clear the dependency overrides (here it's only one) in the FastAPI `app`.
+
+8. Now the test function requires the **client fixture**.
+
+    And inside the test function, the code is quite **simple**, we just use the `TestClient` to make requests to the API, check the data, and that's it.
+
+    The fixtures take care of all the **setup** and **cleanup** code.

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/main.py

@@ -0,0 +1,104 @@
+from fastapi import Depends, FastAPI, HTTPException, Query
+from sqlmodel import Field, Session, SQLModel, create_engine, select
+
+
+class HeroBase(SQLModel):
+    name: str = Field(index=True)
+    secret_name: str
+    age: int | None = Field(default=None, index=True)
+
+
+class Hero(HeroBase, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+
+
+class HeroCreate(HeroBase):
+    pass
+
+
+class HeroRead(HeroBase):
+    id: int
+
+
+class HeroUpdate(SQLModel):
+    name: str | None = None
+    secret_name: str | None = None
+    age: int | None = None
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+connect_args = {"check_same_thread": False}
+engine = create_engine(sqlite_url, echo=True, connect_args=connect_args)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def get_session():
+    with Session(engine) as session:
+        yield session
+
+
+app = FastAPI()
+
+
+@app.on_event("startup")
+def on_startup():
+    create_db_and_tables()
+
+
+@app.post("/heroes/", response_model=HeroRead)
+def create_hero(*, session: Session = Depends(get_session), hero: HeroCreate):
+    db_hero = Hero.from_orm(hero)
+    session.add(db_hero)
+    session.commit()
+    session.refresh(db_hero)
+    return db_hero
+
+
+@app.get("/heroes/", response_model=list[HeroRead])
+def read_heroes(
+    *,
+    session: Session = Depends(get_session),
+    offset: int = 0,
+    limit: int = Query(default=100, le=100),
+):
+    heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
+    return heroes
+
+
+@app.get("/heroes/{hero_id}", response_model=HeroRead)
+def read_hero(*, session: Session = Depends(get_session), hero_id: int):
+    hero = session.get(Hero, hero_id)
+    if not hero:
+        raise HTTPException(status_code=404, detail="Hero not found")
+    return hero
+
+
+@app.patch("/heroes/{hero_id}", response_model=HeroRead)
+def update_hero(
+    *, session: Session = Depends(get_session), hero_id: int, hero: HeroUpdate
+):
+    db_hero = session.get(Hero, hero_id)
+    if not db_hero:
+        raise HTTPException(status_code=404, detail="Hero not found")
+    hero_data = hero.dict(exclude_unset=True)
+    for key, value in hero_data.items():
+        setattr(db_hero, key, value)
+    session.add(db_hero)
+    session.commit()
+    session.refresh(db_hero)
+    return db_hero
+
+
+@app.delete("/heroes/{hero_id}")
+def delete_hero(*, session: Session = Depends(get_session), hero_id: int):
+    hero = session.get(Hero, hero_id)
+    if not hero:
+        raise HTTPException(status_code=404, detail="Hero not found")
+    session.delete(hero)
+    session.commit()
+    return {"ok": True}

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/test_extra_coverage.py

@@ -0,0 +1,38 @@
+from fastapi.testclient import TestClient
+from sqlalchemy import Inspector, inspect
+from sqlmodel import Session, create_engine
+
+from . import main as app_mod
+from .test_main import client_fixture, session_fixture
+
+assert client_fixture, "This keeps the client fixture used below"
+assert session_fixture, "This keeps the session fixture used by client_fixture"
+
+
+def test_startup():
+    app_mod.engine = create_engine("sqlite://")
+    app_mod.on_startup()
+    insp: Inspector = inspect(app_mod.engine)
+    assert insp.has_table(str(app_mod.Hero.__tablename__))
+
+
+def test_get_session():
+    app_mod.engine = create_engine("sqlite://")
+    for session in app_mod.get_session():
+        assert isinstance(session, Session)
+        assert session.bind == app_mod.engine
+
+
+def test_read_hero_not_found(client: TestClient):
+    response = client.get("/heroes/9000")
+    assert response.status_code == 404
+
+
+def test_update_hero_not_found(client: TestClient):
+    response = client.patch("/heroes/9000", json={"name": "Very-Rusty-Man"})
+    assert response.status_code == 404
+
+
+def test_delete_hero_not_found(client: TestClient):
+    response = client.delete("/heroes/9000")
+    assert response.status_code == 404

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/test_main.py

@@ -0,0 +1,125 @@
+import pytest
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool
+
+from .main import Hero, app, get_session
+
+
+@pytest.fixture(name="session")
+def session_fixture():
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        yield session
+
+
+@pytest.fixture(name="client")
+def client_fixture(session: Session):
+    def get_session_override():
+        return session
+
+    app.dependency_overrides[get_session] = get_session_override
+    client = TestClient(app)
+    yield client
+    app.dependency_overrides.clear()
+
+
+def test_create_hero(client: TestClient):
+    response = client.post(
+        "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+    )
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == "Deadpond"
+    assert data["secret_name"] == "Dive Wilson"
+    assert data["age"] is None
+    assert data["id"] is not None
+
+
+def test_create_hero_incomplete(client: TestClient):
+    # No secret_name
+    response = client.post("/heroes/", json={"name": "Deadpond"})
+    assert response.status_code == 422
+
+
+def test_create_hero_invalid(client: TestClient):
+    # secret_name has an invalid type
+    response = client.post(
+        "/heroes/",
+        json={
+            "name": "Deadpond",
+            "secret_name": {"message": "Do you wanna know my secret identity?"},
+        },
+    )
+    assert response.status_code == 422
+
+
+def test_read_heroes(session: Session, client: TestClient):
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    hero_2 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)
+    session.add(hero_1)
+    session.add(hero_2)
+    session.commit()
+
+    response = client.get("/heroes/")
+    data = response.json()
+
+    assert response.status_code == 200
+
+    assert len(data) == 2
+    assert data[0]["name"] == hero_1.name
+    assert data[0]["secret_name"] == hero_1.secret_name
+    assert data[0]["age"] == hero_1.age
+    assert data[0]["id"] == hero_1.id
+    assert data[1]["name"] == hero_2.name
+    assert data[1]["secret_name"] == hero_2.secret_name
+    assert data[1]["age"] == hero_2.age
+    assert data[1]["id"] == hero_2.id
+
+
+def test_read_hero(session: Session, client: TestClient):
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    session.add(hero_1)
+    session.commit()
+
+    response = client.get(f"/heroes/{hero_1.id}")
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == hero_1.name
+    assert data["secret_name"] == hero_1.secret_name
+    assert data["age"] == hero_1.age
+    assert data["id"] == hero_1.id
+
+
+def test_update_hero(session: Session, client: TestClient):
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    session.add(hero_1)
+    session.commit()
+
+    response = client.patch(f"/heroes/{hero_1.id}", json={"name": "Deadpuddle"})
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == "Deadpuddle"
+    assert data["secret_name"] == "Dive Wilson"
+    assert data["age"] is None
+    assert data["id"] == hero_1.id
+
+
+def test_delete_hero(session: Session, client: TestClient):
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    session.add(hero_1)
+    session.commit()
+
+    response = client.delete(f"/heroes/{hero_1.id}")
+
+    hero_in_db = session.get(Hero, hero_1.id)
+
+    assert response.status_code == 200
+
+    assert hero_in_db is None

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/test_main_001.py

@@ -0,0 +1,32 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+
+from .main import app, get_session  # (1)!
+
+
+def test_create_hero():
+    engine = create_engine(
+        "sqlite:///testing.db", connect_args={"check_same_thread": False}
+    )
+    SQLModel.metadata.create_all(engine)
+
+    with Session(engine) as session:
+
+        def get_session_override():
+            return session
+
+        app.dependency_overrides[get_session] = get_session_override
+
+        client = TestClient(app)  # (2)!
+
+        response = client.post(  # (3)!
+            "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+        )
+        app.dependency_overrides.clear()
+        data = response.json()  # (4)!
+
+        assert response.status_code == 200  # (5)!
+        assert data["name"] == "Deadpond"  # (6)!
+        assert data["secret_name"] == "Dive Wilson"  # (7)!
+        assert data["age"] is None  # (8)!
+        assert data["id"] is not None  # (9)!

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/test_main_002.py

@@ -0,0 +1,32 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+
+from .main import app, get_session  # (1)!
+
+
+def test_create_hero():
+    engine = create_engine(
+        "sqlite:///testing.db", connect_args={"check_same_thread": False}
+    )
+    SQLModel.metadata.create_all(engine)
+
+    with Session(engine) as session:
+
+        def get_session_override():  # (2)!
+            return session  # (3)!
+
+        app.dependency_overrides[get_session] = get_session_override  # (4)!
+
+        client = TestClient(app)
+
+        response = client.post(
+            "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+        )
+        app.dependency_overrides.clear()  # (5)!
+        data = response.json()
+
+        assert response.status_code == 200
+        assert data["name"] == "Deadpond"
+        assert data["secret_name"] == "Dive Wilson"
+        assert data["age"] is None
+        assert data["id"] is not None

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/test_main_003.py

@@ -0,0 +1,33 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+
+from .main import app, get_session  # (1)!
+
+
+def test_create_hero():
+    engine = create_engine(  # (2)!
+        "sqlite:///testing.db", connect_args={"check_same_thread": False}
+    )
+    SQLModel.metadata.create_all(engine)  # (3)!
+
+    with Session(engine) as session:  # (4)!
+
+        def get_session_override():
+            return session  # (5)!
+
+        app.dependency_overrides[get_session] = get_session_override  # (4)!
+
+        client = TestClient(app)
+
+        response = client.post(
+            "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+        )
+        app.dependency_overrides.clear()
+        data = response.json()
+
+        assert response.status_code == 200
+        assert data["name"] == "Deadpond"
+        assert data["secret_name"] == "Dive Wilson"
+        assert data["age"] is None
+        assert data["id"] is not None
+    # (6)!

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/test_main_004.py

@@ -0,0 +1,35 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool  # (1)!
+
+from .main import app, get_session
+
+
+def test_create_hero():
+    engine = create_engine(
+        "sqlite://",  # (2)!
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,  # (3)!
+    )
+    SQLModel.metadata.create_all(engine)
+
+    with Session(engine) as session:
+
+        def get_session_override():
+            return session
+
+        app.dependency_overrides[get_session] = get_session_override
+
+        client = TestClient(app)
+
+        response = client.post(
+            "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+        )
+        app.dependency_overrides.clear()
+        data = response.json()
+
+        assert response.status_code == 200
+        assert data["name"] == "Deadpond"
+        assert data["secret_name"] == "Dive Wilson"
+        assert data["age"] is None
+        assert data["id"] is not None

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/test_main_005.py

@@ -0,0 +1,37 @@
+import pytest  # (1)!
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool
+
+from .main import app, get_session
+
+
+@pytest.fixture(name="session")  # (2)!
+def session_fixture():  # (3)!
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        yield session  # (4)!
+
+
+def test_create_hero(session: Session):  # (5)!
+    def get_session_override():
+        return session  # (6)!
+
+    app.dependency_overrides[get_session] = get_session_override
+
+    client = TestClient(app)
+
+    response = client.post(
+        "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+    )
+    app.dependency_overrides.clear()
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == "Deadpond"
+    assert data["secret_name"] == "Dive Wilson"
+    assert data["age"] is None
+    assert data["id"] is not None

docs_src/tutorial/fastapi/app_testing/tutorial001_py310/test_main_006.py

@@ -0,0 +1,41 @@
+import pytest
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool
+
+from .main import app, get_session
+
+
+@pytest.fixture(name="session")
+def session_fixture():
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        yield session
+
+
+@pytest.fixture(name="client")  # (1)!
+def client_fixture(session: Session):  # (2)!
+    def get_session_override():  # (3)!
+        return session
+
+    app.dependency_overrides[get_session] = get_session_override  # (4)!
+
+    client = TestClient(app)  # (5)!
+    yield client  # (6)!
+    app.dependency_overrides.clear()  # (7)!
+
+
+def test_create_hero(client: TestClient):  # (8)!
+    response = client.post(
+        "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+    )
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == "Deadpond"
+    assert data["secret_name"] == "Dive Wilson"
+    assert data["age"] is None
+    assert data["id"] is not None

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/annotations/en/test_main_001.md

@@ -0,0 +1,17 @@
+1. Import the `app` from the the `main` module.
+
+2. We create a `TestClient` for the FastAPI `app` and put it in the variable `client`.
+
+3. Then we use use this `client` to **talk to the API** and send a `POST` HTTP operation, creating a new hero.
+
+4. Then we get the **JSON data** from the response and put it in the variable `data`.
+
+5. Next we start testing the results with `assert` statements, we check that the status code of the response is `200`.
+
+6. We check that the `name` of the hero created is `"Deadpond"`.
+
+7. We check that the `secret_name` of the hero created is `"Dive Wilson"`.
+
+8. We check that the `age` of the hero created is `None`, because we didn't send an age.
+
+9. We check that the hero created has an `id` created by the database, so it's not `None`.

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/annotations/en/test_main_002.md

@@ -0,0 +1,25 @@
+1. Import the `get_session` dependency from the the `main` module.
+
+2. Define the new function that will be the new **dependency override**.
+
+3. This function will return a different **session** than the one that would be returned by the original `get_session` function.
+
+    We haven't seen how this new **session** object is created yet, but the point is that this is a different session than the original one from the app.
+
+    This session is attached to a different **engine**, and that different **engine** uses a different URL, for a database just for testing.
+
+    We haven't defined that new **URL** nor the new **engine** yet, but here we already see the that this object `session` will override the one returned by the original dependency  `get_session()`.
+
+4. Then, the FastAPI `app` object has an attribute `app.dependency_overrides`.
+
+    This attribute is a dictionary, and we can put dependency overrides in it by passing, as the **key**, the **original dependency function**, and as the **value**, the **new overriding dependency function**.
+
+    So, here we are telling the FastAPI app to use `get_session_override` instead of `get_session` in all the places in the code that depend on `get_session`, that is, all the parameters with something like:
+
+    ```Python
+    session: Session = Depends(get_session)
+    ```
+
+5. After we are done with the dependency override, we can restore the application back to normal, by removing all the values in this dictionary `app.dependency_overrides`.
+
+    This way whenever a *path operation function* needs the dependency FastAPI will use the original one instead of the override.

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/annotations/en/test_main_003.md

@@ -0,0 +1,37 @@
+1. Here's a subtle thing to notice.
+
+    Remember that [Order Matters](../create-db-and-table.md#sqlmodel-metadata-order-matters){.internal-link target=_blank} and we need to make sure all the **SQLModel** models are already defined and **imported** before calling `.create_all()`.
+
+    IN this line, by importing something, *anything*, from `.main`, the code in `.main` will be executed, including the definition of the **table models**, and that will automatically register them in `SQLModel.metadata`.
+
+2. Here we create a new **engine**, completely different from the one in `main.py`.
+
+    This is the engine we will use for the tests.
+
+    We use the new URL of the database for tests:
+
+    ```
+    sqlite:///testing.db
+    ```
+
+    And again, we use the connection argument `check_same_thread=False`.
+
+3. Then we call:
+
+    ```Python
+    SQLModel.metadata.create_all(engine)
+    ```
+
+    ...to make sure we create all the tables in the new testing database.
+
+    The **table models** are registered in `SQLModel.metadata` just because we imported *something* from `.main`, and the code in `.main` was executed, creating the classes for the **table models** and automatically registering them in `SQLModel.metadata`.
+
+    So, by the point we call this method, the **table models** are already registered there. 💯
+
+4. Here's where we create the custom **session** object for this test in a `with` block.
+
+    It uses the new custom **engine** we created, so anything that uses this session will be using the testing database.
+
+5. Now, back to the dependency override, it is just returning the same **session** object from outside, that's it, that's the whole trick.
+
+6. By this point, the testing **session** `with` block finishes, and the session is closed, the file is closed, etc.

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/annotations/en/test_main_004.md

@@ -0,0 +1,26 @@
+1. Import `StaticPool` from `sqlmodel`, we will use it in a bit.
+
+2. For the **SQLite URL**, don't write any file name, leave it empty.
+
+    So, instead of:
+
+    ```
+    sqlite:///testing.db
+    ```
+
+    ...just write:
+
+    ```
+    sqlite://
+    ```
+
+    This is enough to tell **SQLModel** (actually SQLAlchemy) that we want to use an **in-memory SQLite database**.
+
+3. Remember that we told the **low-level** library in charge of communicating with SQLite that we want to be able to **access the database from different threads** with `check_same_thread=False`?
+
+    Now that we use an **in-memory database**, we need to also tell SQLAlchemy that we want to be able to use the **same in-memory database** object from different threads.
+
+    We tell it that with the `poolclass=StaticPool` parameter.
+
+    !!! info
+        You can read more details in the <a href="https://docs.sqlalchemy.org/en/14/dialects/sqlite.html#using-a-memory-database-in-multiple-threads" class="external-link" target="_blank">SQLAlchemy documentation about Using a Memory Database in Multiple Threads</a>

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/annotations/en/test_main_005.md

@@ -0,0 +1,41 @@
+1. Import `pytest`.
+
+2. Use the `@pytest.fixture()` decorator on top of the function to tell pytest that this is a **fixture** function (equivalent to a FastAPI dependency).
+
+    We also give it a name of `"session"`, this will be important in the testing function.
+
+3. Create the fixture function. This is equivalent to a FastAPI dependency function.
+
+    In this fixture we create the custom **engine**, with the in-memory database, we create the tables, and we create the **session**.
+
+    Then we `yield` the `session` object.
+
+4. The thing that we `return` or `yield` is what will be available to the test function, in this case, the `session` object.
+
+    Here we use `yield` so that **pytest** comes back to execute "the rest of the code" in this function once the testing function is done.
+
+    We don't have any more visible "rest of the code" after the `yield`, but we have the end of the `with` block that will close the **session**.
+
+    By using `yield`, pytest will:
+
+    * run the first part
+    * create the **session** object
+    * give it to the test function
+    * run the test function
+    * once the test function is done, it will continue here, right after the `yield`, and will correctly close the **session** object in the end of the `with` block.
+
+5. Now, in the test function, to tell **pytest** that this test wants to get the fixture, instead of declaring something like in FastAPI with:
+
+    ```Python
+    session: Session = Depends(session_fixture)
+    ```
+
+    ...the way we tell pytest what is the fixture that we want is by using the **exact same name** of the fixture.
+
+    In this case, we named it `session`, so the parameter has to be exactly named `session` for it to work.
+
+    We also add the type annotation `session: Session` so that we can get autocompletion and inline error checks in our editor.
+
+6. Now in the dependency override function, we just return the same `session` object that came from outside it.
+
+    The `session` object comes from the parameter passed to the test function, and we just re-use it and return it here in the dependency override.

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/annotations/en/test_main_006.md

@@ -0,0 +1,23 @@
+1. Create the new fixture named `"client"`.
+
+2. This **client fixture**, in turn, also requires the **session fixture**.
+
+3. Now we create the **dependency override** inside the client fixture.
+
+4. Set the **dependency override** in the `app.dependency_overrides` dictionary.
+
+5. Create the `TestClient` with the **FastAPI** `app`.
+
+6. `yield` the `TestClient` instance.
+
+    By using `yield`, after the test function is done, pytest will come back to execute the rest of the code after `yield`.
+
+7. This is the cleanup code, after `yield`, and after the test function is done.
+
+    Here we clear the dependency overrides (here it's only one) in the FastAPI `app`.
+
+8. Now the test function requires the **client fixture**.
+
+    And inside the test function, the code is quite **simple**, we just use the `TestClient` to make requests to the API, check the data, and that's it.
+
+    The fixtures take care of all the **setup** and **cleanup** code.

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/main.py

@@ -0,0 +1,106 @@
+from typing import Optional
+
+from fastapi import Depends, FastAPI, HTTPException, Query
+from sqlmodel import Field, Session, SQLModel, create_engine, select
+
+
+class HeroBase(SQLModel):
+    name: str = Field(index=True)
+    secret_name: str
+    age: Optional[int] = Field(default=None, index=True)
+
+
+class Hero(HeroBase, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+
+
+class HeroCreate(HeroBase):
+    pass
+
+
+class HeroRead(HeroBase):
+    id: int
+
+
+class HeroUpdate(SQLModel):
+    name: Optional[str] = None
+    secret_name: Optional[str] = None
+    age: Optional[int] = None
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+connect_args = {"check_same_thread": False}
+engine = create_engine(sqlite_url, echo=True, connect_args=connect_args)
+
+
+def create_db_and_tables():
+    SQLModel.metadata.create_all(engine)
+
+
+def get_session():
+    with Session(engine) as session:
+        yield session
+
+
+app = FastAPI()
+
+
+@app.on_event("startup")
+def on_startup():
+    create_db_and_tables()
+
+
+@app.post("/heroes/", response_model=HeroRead)
+def create_hero(*, session: Session = Depends(get_session), hero: HeroCreate):
+    db_hero = Hero.from_orm(hero)
+    session.add(db_hero)
+    session.commit()
+    session.refresh(db_hero)
+    return db_hero
+
+
+@app.get("/heroes/", response_model=list[HeroRead])
+def read_heroes(
+    *,
+    session: Session = Depends(get_session),
+    offset: int = 0,
+    limit: int = Query(default=100, le=100),
+):
+    heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
+    return heroes
+
+
+@app.get("/heroes/{hero_id}", response_model=HeroRead)
+def read_hero(*, session: Session = Depends(get_session), hero_id: int):
+    hero = session.get(Hero, hero_id)
+    if not hero:
+        raise HTTPException(status_code=404, detail="Hero not found")
+    return hero
+
+
+@app.patch("/heroes/{hero_id}", response_model=HeroRead)
+def update_hero(
+    *, session: Session = Depends(get_session), hero_id: int, hero: HeroUpdate
+):
+    db_hero = session.get(Hero, hero_id)
+    if not db_hero:
+        raise HTTPException(status_code=404, detail="Hero not found")
+    hero_data = hero.dict(exclude_unset=True)
+    for key, value in hero_data.items():
+        setattr(db_hero, key, value)
+    session.add(db_hero)
+    session.commit()
+    session.refresh(db_hero)
+    return db_hero
+
+
+@app.delete("/heroes/{hero_id}")
+def delete_hero(*, session: Session = Depends(get_session), hero_id: int):
+    hero = session.get(Hero, hero_id)
+    if not hero:
+        raise HTTPException(status_code=404, detail="Hero not found")
+    session.delete(hero)
+    session.commit()
+    return {"ok": True}

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/test_extra_coverage.py

@@ -0,0 +1,38 @@
+from fastapi.testclient import TestClient
+from sqlalchemy import Inspector, inspect
+from sqlmodel import Session, create_engine
+
+from . import main as app_mod
+from .test_main import client_fixture, session_fixture
+
+assert client_fixture, "This keeps the client fixture used below"
+assert session_fixture, "This keeps the session fixture used by client_fixture"
+
+
+def test_startup():
+    app_mod.engine = create_engine("sqlite://")
+    app_mod.on_startup()
+    insp: Inspector = inspect(app_mod.engine)
+    assert insp.has_table(str(app_mod.Hero.__tablename__))
+
+
+def test_get_session():
+    app_mod.engine = create_engine("sqlite://")
+    for session in app_mod.get_session():
+        assert isinstance(session, Session)
+        assert session.bind == app_mod.engine
+
+
+def test_read_hero_not_found(client: TestClient):
+    response = client.get("/heroes/9000")
+    assert response.status_code == 404
+
+
+def test_update_hero_not_found(client: TestClient):
+    response = client.patch("/heroes/9000", json={"name": "Very-Rusty-Man"})
+    assert response.status_code == 404
+
+
+def test_delete_hero_not_found(client: TestClient):
+    response = client.delete("/heroes/9000")
+    assert response.status_code == 404

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/test_main.py

@@ -0,0 +1,125 @@
+import pytest
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool
+
+from .main import Hero, app, get_session
+
+
+@pytest.fixture(name="session")
+def session_fixture():
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        yield session
+
+
+@pytest.fixture(name="client")
+def client_fixture(session: Session):
+    def get_session_override():
+        return session
+
+    app.dependency_overrides[get_session] = get_session_override
+    client = TestClient(app)
+    yield client
+    app.dependency_overrides.clear()
+
+
+def test_create_hero(client: TestClient):
+    response = client.post(
+        "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+    )
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == "Deadpond"
+    assert data["secret_name"] == "Dive Wilson"
+    assert data["age"] is None
+    assert data["id"] is not None
+
+
+def test_create_hero_incomplete(client: TestClient):
+    # No secret_name
+    response = client.post("/heroes/", json={"name": "Deadpond"})
+    assert response.status_code == 422
+
+
+def test_create_hero_invalid(client: TestClient):
+    # secret_name has an invalid type
+    response = client.post(
+        "/heroes/",
+        json={
+            "name": "Deadpond",
+            "secret_name": {"message": "Do you wanna know my secret identity?"},
+        },
+    )
+    assert response.status_code == 422
+
+
+def test_read_heroes(session: Session, client: TestClient):
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    hero_2 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)
+    session.add(hero_1)
+    session.add(hero_2)
+    session.commit()
+
+    response = client.get("/heroes/")
+    data = response.json()
+
+    assert response.status_code == 200
+
+    assert len(data) == 2
+    assert data[0]["name"] == hero_1.name
+    assert data[0]["secret_name"] == hero_1.secret_name
+    assert data[0]["age"] == hero_1.age
+    assert data[0]["id"] == hero_1.id
+    assert data[1]["name"] == hero_2.name
+    assert data[1]["secret_name"] == hero_2.secret_name
+    assert data[1]["age"] == hero_2.age
+    assert data[1]["id"] == hero_2.id
+
+
+def test_read_hero(session: Session, client: TestClient):
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    session.add(hero_1)
+    session.commit()
+
+    response = client.get(f"/heroes/{hero_1.id}")
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == hero_1.name
+    assert data["secret_name"] == hero_1.secret_name
+    assert data["age"] == hero_1.age
+    assert data["id"] == hero_1.id
+
+
+def test_update_hero(session: Session, client: TestClient):
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    session.add(hero_1)
+    session.commit()
+
+    response = client.patch(f"/heroes/{hero_1.id}", json={"name": "Deadpuddle"})
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == "Deadpuddle"
+    assert data["secret_name"] == "Dive Wilson"
+    assert data["age"] is None
+    assert data["id"] == hero_1.id
+
+
+def test_delete_hero(session: Session, client: TestClient):
+    hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
+    session.add(hero_1)
+    session.commit()
+
+    response = client.delete(f"/heroes/{hero_1.id}")
+
+    hero_in_db = session.get(Hero, hero_1.id)
+
+    assert response.status_code == 200
+
+    assert hero_in_db is None

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/test_main_001.py

@@ -0,0 +1,32 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+
+from .main import app, get_session  # (1)!
+
+
+def test_create_hero():
+    engine = create_engine(
+        "sqlite:///testing.db", connect_args={"check_same_thread": False}
+    )
+    SQLModel.metadata.create_all(engine)
+
+    with Session(engine) as session:
+
+        def get_session_override():
+            return session
+
+        app.dependency_overrides[get_session] = get_session_override
+
+        client = TestClient(app)  # (2)!
+
+        response = client.post(  # (3)!
+            "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+        )
+        app.dependency_overrides.clear()
+        data = response.json()  # (4)!
+
+        assert response.status_code == 200  # (5)!
+        assert data["name"] == "Deadpond"  # (6)!
+        assert data["secret_name"] == "Dive Wilson"  # (7)!
+        assert data["age"] is None  # (8)!
+        assert data["id"] is not None  # (9)!

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/test_main_002.py

@@ -0,0 +1,32 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+
+from .main import app, get_session  # (1)!
+
+
+def test_create_hero():
+    engine = create_engine(
+        "sqlite:///testing.db", connect_args={"check_same_thread": False}
+    )
+    SQLModel.metadata.create_all(engine)
+
+    with Session(engine) as session:
+
+        def get_session_override():  # (2)!
+            return session  # (3)!
+
+        app.dependency_overrides[get_session] = get_session_override  # (4)!
+
+        client = TestClient(app)
+
+        response = client.post(
+            "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+        )
+        app.dependency_overrides.clear()  # (5)!
+        data = response.json()
+
+        assert response.status_code == 200
+        assert data["name"] == "Deadpond"
+        assert data["secret_name"] == "Dive Wilson"
+        assert data["age"] is None
+        assert data["id"] is not None

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/test_main_003.py

@@ -0,0 +1,33 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+
+from .main import app, get_session  # (1)!
+
+
+def test_create_hero():
+    engine = create_engine(  # (2)!
+        "sqlite:///testing.db", connect_args={"check_same_thread": False}
+    )
+    SQLModel.metadata.create_all(engine)  # (3)!
+
+    with Session(engine) as session:  # (4)!
+
+        def get_session_override():
+            return session  # (5)!
+
+        app.dependency_overrides[get_session] = get_session_override  # (4)!
+
+        client = TestClient(app)
+
+        response = client.post(
+            "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+        )
+        app.dependency_overrides.clear()
+        data = response.json()
+
+        assert response.status_code == 200
+        assert data["name"] == "Deadpond"
+        assert data["secret_name"] == "Dive Wilson"
+        assert data["age"] is None
+        assert data["id"] is not None
+    # (6)!

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/test_main_004.py

@@ -0,0 +1,35 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool  # (1)!
+
+from .main import app, get_session
+
+
+def test_create_hero():
+    engine = create_engine(
+        "sqlite://",  # (2)!
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,  # (3)!
+    )
+    SQLModel.metadata.create_all(engine)
+
+    with Session(engine) as session:
+
+        def get_session_override():
+            return session
+
+        app.dependency_overrides[get_session] = get_session_override
+
+        client = TestClient(app)
+
+        response = client.post(
+            "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+        )
+        app.dependency_overrides.clear()
+        data = response.json()
+
+        assert response.status_code == 200
+        assert data["name"] == "Deadpond"
+        assert data["secret_name"] == "Dive Wilson"
+        assert data["age"] is None
+        assert data["id"] is not None

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/test_main_005.py

@@ -0,0 +1,37 @@
+import pytest  # (1)!
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool
+
+from .main import app, get_session
+
+
+@pytest.fixture(name="session")  # (2)!
+def session_fixture():  # (3)!
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        yield session  # (4)!
+
+
+def test_create_hero(session: Session):  # (5)!
+    def get_session_override():
+        return session  # (6)!
+
+    app.dependency_overrides[get_session] = get_session_override
+
+    client = TestClient(app)
+
+    response = client.post(
+        "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+    )
+    app.dependency_overrides.clear()
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == "Deadpond"
+    assert data["secret_name"] == "Dive Wilson"
+    assert data["age"] is None
+    assert data["id"] is not None

docs_src/tutorial/fastapi/app_testing/tutorial001_py39/test_main_006.py

@@ -0,0 +1,41 @@
+import pytest
+from fastapi.testclient import TestClient
+from sqlmodel import Session, SQLModel, create_engine
+from sqlmodel.pool import StaticPool
+
+from .main import app, get_session
+
+
+@pytest.fixture(name="session")
+def session_fixture():
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        yield session
+
+
+@pytest.fixture(name="client")  # (1)!
+def client_fixture(session: Session):  # (2)!
+    def get_session_override():  # (3)!
+        return session
+
+    app.dependency_overrides[get_session] = get_session_override  # (4)!
+
+    client = TestClient(app)  # (5)!
+    yield client  # (6)!
+    app.dependency_overrides.clear()  # (7)!
+
+
+def test_create_hero(client: TestClient):  # (8)!
+    response = client.post(
+        "/heroes/", json={"name": "Deadpond", "secret_name": "Dive Wilson"}
+    )
+    data = response.json()
+
+    assert response.status_code == 200
+    assert data["name"] == "Deadpond"
+    assert data["secret_name"] == "Dive Wilson"
+    assert data["age"] is None
+    assert data["id"] is not None