How-To: Use Type Annotations with FastAPI-Restly#

FastAPI-Restly supports two typing styles:

  • Low-friction mode: keep your view classes simple and let the framework do the work.

  • Stronger typing mode: add explicit type parameters when you want better editor help for perform_* overrides.

This guide focuses on practical usage with Pyright and VS Code with Pylance.

Start simple#

For normal CRUD usage, you do not need to parameterize RestView or AsyncRestView.

import fastapi_restly as fr
from fastapi import FastAPI
from sqlalchemy.orm import Mapped

app = FastAPI()


class User(fr.IDBase):
    name: Mapped[str]
    email: Mapped[str]


@fr.include_view(app)
class UserView(fr.AsyncRestView):
    prefix = "/users"
    model = User

This is the recommended starting point.

Use IDSchema for response schemas#

You can subclass IDSchema directly:

class UserRead(fr.IDSchema):
    name: str
    email: str

IDSchema is the usual base for response schemas because it adds the resource’s own read-only id field. You can parameterize it when you want the schema class itself to carry the SQLAlchemy model type:

class UserRead(fr.IDSchema[User]):
    name: str
    email: str

For most top-level response schemas, either form is fine. The bare form is the recommended starting point.

For foreign-key fields, use IDRef[RelatedModel]:

class ArticleRead(fr.IDSchema):
    title: str
    author_id: fr.IDRef[User]

That tells Restly which model should be resolved from the scalar id payload.

When view generics are useful#

AsyncRestView and RestView can be parameterized, but this is optional.

The generic form is useful when you override handlers such as:

  • perform_get

  • perform_create

  • perform_update

  • perform_delete

  • perform_listing

Without view generics, these handlers still work, but their types are broader. With view generics, your editor can infer the concrete model, schema, and id types.

class UserRead(fr.IDSchema[User]):
    name: str
    email: str


class UserCreate(fr.BaseSchema):
    name: str
    email: str


class UserUpdate(fr.BaseSchema):
    name: str
    email: str


@fr.include_view(app)
class UserView(
    fr.AsyncRestView[User, UserRead, UserCreate, UserUpdate, int]
):
    prefix = "/users"
    model = User
    schema = UserRead
    creation_schema = UserCreate
    update_schema = UserUpdate

    async def perform_get(self, id: int) -> User:
        return await super().perform_get(id)

    async def perform_create(self, schema_obj: UserCreate) -> User:
        return await super().perform_create(schema_obj)

    async def perform_update(self, id: int, schema_obj: UserUpdate) -> User:
        return await super().perform_update(id, schema_obj)

This looks heavier because it is more explicit. Use it when that extra precision is valuable to you.

fr.BaseSchema is a convenient default, not a hard requirement for input schemas. Explicit creation_schema and update_schema classes may inherit directly from pydantic.BaseModel when you do not need Restly’s schema helpers.

A good rule of thumb#

Use the simplest form that gives you the typing help you want:

  • No generics at all for normal CRUD views

  • IDRef[RelatedModel] for foreign-key fields

  • IDSchema[RelatedModel] only when you intentionally want a nested relationship object field

  • View generics only when you want precise perform_* handler typing

That keeps everyday usage clean while still allowing stricter typing for projects that want it.

Custom routes are straightforward#

Custom route methods do not need view generics unless they depend on strongly typed handler interactions.

@fr.include_view(app)
class UserView(fr.AsyncRestView):
    prefix = "/users"
    model = User

    @fr.get("/health")
    async def health(self) -> dict[str, str]:
        return {"status": "ok"}

For extra endpoints like this, normal Python return annotations are usually enough.

What the type checker cannot fully model#

FastAPI-Restly does some runtime work to register and annotate view methods for FastAPI. This includes copying inherited endpoints and adjusting signatures during view registration.

That runtime behavior is part of how the framework works, but static type checkers do not understand every detail of that process.

The practical takeaway is:

  • Type checkers are best at the public contract: models, schemas, IDSchema[...], IDRef[...], class attributes, and perform_* handlers.

  • Type checkers are less useful for the internal signature-rewriting machinery.

You usually do not need to care about that distinction unless you are modifying the framework itself.

Summary#

  • Bare IDSchema is supported.

  • IDRef[Model] is preferred for foreign-key fields.

  • IDSchema[Model] is available for nested relationship-object fields.

  • Bare RestView / AsyncRestView are the default.

  • Parameterized views are optional and mainly help with perform_* handler typing.

  • Custom route methods work well with ordinary Python annotations.