Can we update the docs to use types for Session.Select and Session.Exec (In Advanced?)

[dave42w]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from sqlmodel import Field, Session, SQLModel, create_engine, select
from sqlmodel.sql.expression import SelectOfScalar
from typing import Sequence


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)

    with Session(engine) as session:
        session.add(hero_1)
        session.add(hero_2)
        session.add(hero_3)

        session.commit()


def select_heroes():
    with Session(engine) as session:
        statement: SelectOfScalar[Hero] = select(Hero)
        results: Sequence[Hero] = session.exec(statement)
        for hero in results:
            print(hero)


def main():
    create_db_and_tables()
    create_heroes()
    select_heroes()


if __name__ == "__main__":
    main()

Description

The tutorial code is not fully typed for MyPy. Moving to full types is not helped by Mypy being confused with the types of the statement and results variables

Can we show how to add types (I'm thinking of an additional topic in the Advanced tutorial)? eg

        statement: SelectOfScalar[Hero] = select(Hero)
        results: Sequence[Hero] = session.exec(statement)

which need these imports:

from sqlmodel.sql.expression import SelectOfScalar
from typing import Sequence

Would you like me to submit a PR with a new doc file?

At the same time, I am confused by the session source code. The return types in a few places have : ... eg at the end of exec

def exec(
... ends with
    ) -> ScalarResult[_TSelectParam]: ...

I can't find anywhere what the ... after the : means.

Thanks

Dave

Operating System

Linux

Operating System Details

Debian12 (using uv with Python 3.12.6)

SQLModel Version

0.0.22

Python Version

3.12.6

Additional Context

No response