How to handle distinction between multiple models and schemas (database model vs response model)

[kratsg]

FastAPI provides some nice documentation on a "Response" model: https://fastapi.tiangolo.com/tutorial/response-model/ with something like

class BaseUser(BaseModel):
    username: str
    email: EmailStr
    full_name: str | None = None

class UserIn(BaseUser):
    password: str

@app.post("/user/")
async def create_user(user: UserIn) -> BaseUser:
    return user

@app.get("/users/")
async def list_users() -> list[BaseUser]:
  return await UserIn.find().limit(100)

Now, with beanie, we have the Document class. Most of the examples I've seen so far do a split where they define UserBase as the response schema, and UserIn as the database model. The question then is, do we add Document as a parent class in UserIn or on UserBase? So we have two options here (I think):

class BaseUser(Document):
    username: str
    email: EmailStr
    full_name: str | None = None

class UserIn(BaseUser):
    password: str

We replace the response model with a beanie.Document and the rest of the code should work as expected. The other option which I think is a little cleaner in terms of separation of concerns (but seems to run into issues with type-checking) is

class BaseUser(BaseModel):
    username: str
    email: EmailStr
    full_name: str | None = None

class UserIn(Document, BaseUser):
    password: str

where UserIn contains the Document instead of UserBase. That means one cannot use UserBase to query the database, and only UserIn, but this is the intention (I think). However, when doing this, we have a slight problem because of the subclassing

@app.post("/user/")
async def create_user(user: UserIn) -> BaseUser:
    return user

@app.get("/users/")
async def list_users() -> list[BaseUser]:
  return await UserIn.find().limit(100)

where mypy complains about the list_users function here:

src/audrey_two/routers/api/users.py:12: error: Incompatible return value type (got "list[audrey_two.models.user.User]", expected "list[audrey_two.schemas.user.User]")  [return-value]
src/audrey_two/routers/api/users.py:12: note: "List" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
src/audrey_two/routers/api/users.py:12: note: Consider using "Sequence" instead, which is covariant

Now this is a funny issue, because I'm not sure if the intention of beanie was to replace all models (including the response model), or just the database-facing models. That said, I'm not sure what the correct thing to do here is as the type-checking is throwing me off a little bit.

---

One thing I just realized, in all of these examples, if we use Document.get where we're not returning some sort of list of items, then there's no issue in the return type(!). It must be something about whether we should use list or sequence to type-hint the end-result here.

[kratsg]

One alternative I've found (although I'm not sure if this is intended) is to use the projection_model:

@app.get("/users/")
async def list_users() -> list[BaseUser]:
  return await UserIn.find(projection_model=BaseUser).limit(100)

and this happily works for the type-checking, but it does mean that we are projecting at run-time, instead of letting fastapi do it.