Skip to content

Quickstart Forms section recommends async when sync works #1083

Description

@audreyfeldroy

Problem

The quickstart's Forms section (line 476-512) teaches await request.form() as the primary form pattern with the annotation:

As Air is based off starlette, when we receive data from a form it needs to occur within an async view.

This is misleading. Air's AirForm works with def endpoints via FastAPI's dependency injection:

from typing import Annotated
from fastapi import Depends

@app.post("/submit")
def handle_form(form: Annotated[ContactForm, Depends(ContactForm.from_request)]):
    if form.is_valid:
        return air.H1(f"Name: {form.data.name}")
    return form.render()

FastAPI resolves async dependencies on the event loop before dispatching sync endpoints to the threadpool. Verified working.

What should change

  1. The Forms section should lead with the simplest pattern that works
  2. The annotation "it needs to occur within an async view" should be removed or corrected
  3. Raw await request.form() is a Starlette escape hatch, not the primary recommendation

Additional context

The quickstart also uses air.Form(...) as a parameter default (line 104), which is a separate bug (see #1082). air.Form is the HTML <form> tag, not FastAPI's Form().

Found during work on #1077.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions