Basic pattern for handling forms?

[davepeck]

Hi! I'm new to Litestar and am trying to build a simple old-school web app — that is, one that returns HTML, not JSON, from its endpoints.

I'm curious what patterns Litestar users have adopted for handling bog-standard form POSTs and returning HTML.

For my first attempt, I tried to use Litestar's built-in data validation. I think that ended up being the wrong idea:

from dataclasses import dataclass
from typing import Annotated

from litestar import post, Request
from litestar.exceptions import ValidationException
from litestar.params import Body
from litestar.enums import RequestEncodingType
from litestar.status_codes import HTTP_302_FOUND

@dataclass
class ExampleFormData:
    email: str
    message: str

@get("/example-form")
def example_form(request: Request) -> Template:
     # Use jinja to render a form with two fields: email and message
     ...

@post("/example-form", exception_handlers={ValidationException: example_form_post_error})
def example_form_post(
    request: Request, 
    data: Annotated[ExampleFormData, Body(media_type= RequestEncodingType.URL_ENCODED)]
) -> Redirect:
    do_something_with(data)  # Update the database, or whatever
    return Redirect(path="/somewhere-else", status_code=HTTP_302_FOUND)

def example_form_post_error(request: Request, error: ValidationException) -> Template:
    # Use jinja to render a the same form, but with errors
    ...

Okay, so clearly not how to do things. :-) But, some notes:

1. I don't think validation (at least for dataclasses) collects multiple validation failures into a single exception, so it's not clear if anything like this approach will or could ever work for standard form posts
2. Tying example_form_post(...) to example_form_post_error(...) feels verbose
3. Needing to use Annotated[...] just to say "hey, expect url encoded data" feels verbose
4. For reasons I don't understand, pyright complains about the type of exception_handlers if the request parameter of example_form_post_error() is a litestar_htmx.HTMXRequest rather than a litestar.Request. It seems like this shouldn't happen since the underlying ExceptionHandler type is defined as Callable[[Request, ExceptionT], Response]... but it definitely does happen with the latest build of pyright

---

So... that doesn't seem like the right approach to form handling in Litestar. No worries; I see that request.form() exists, but I'd still like to maybe reuse Litestar's validation features if it's possible. Maybe it's not; I'm not sure.

How can I take advantage of some of Litestar's goodness here, while having more straightforward form handlers? Or should I just use request.form(), dump that into (say) a pydantic or cattrs type (or roll my own validation) and go from there?

Thanks!

[provinzkraut]

Okay, so clearly not how to do things. :-) But, some notes:

Can you elaborate? It seems like the right approach to me.

1. I don't think validation (at least for dataclasses) collects multiple validation failures into a single exception, so it's not clear if anything like this approach will or could ever work for standard form posts

That's correct. The default library used to validate things in Litestar is msgspec, which only reports one error at a time. This is a deliberate design choice (read more about it here), and maybe a bit of a misinterpretation.

The validation offered here is to assert that the data provided has the right shape and schema, not about enforcing semantics. When doing the latter, it definitely makes sense to collect multiple errors in one go, but when doing the former, things can get messy / undeterministic. This is what e.g. Pydantic does, and many of its quirks can be attributed to this.

3. Needing to use Annotated[...] just to say "hey, expect url encoded data" feels verbose

I'd say it's explicit and coherent :)
This is the style Litestar uses to define parameter constraints and metadata in general, which allows a lot of flexibility while also offering type safety.

• Diverging from this for this one use case would be unintuitive
• Implicitly reading data from forms might lead to non-deterministic or unexpected behaviour
• Adding parameters for all of these cases to e.g. the handlers would blow up their signatures (even more 🙂)

4. For reasons I don't understand, pyright complains about the type of exception_handlers if the request parameter of example_form_post_error() is a litestar_htmx.HTMXRequest rather than a litestar.Request. It seems like this shouldn't happen since the underlying ExceptionHandler type is defined as Callable[[Request, ExceptionT], Response]... but it definitely does happen with the latest build of pyright

Not sure about that either. Seems like something has changed in pyright, although it doesn't seem to be failing on our end when we test against pyright. Can you maybe open an issue for this? :)

[davepeck]

Thanks for the reply; it's very helpful.

Can you elaborate? It seems like the right approach to me.

For checking to make sure that an API endpoint was invoked with data conforming to an expected schema: yes, I think it's a great pattern.

But for handling a form POST that returns HTML, maybe less so, for precisely the reason that I may need to render multiple error messages on multiple fields in a single reply.

I'd say it's explicit and coherent :)

Perhaps as I use Litestar more I'll see this pattern in more places. But FWIW my first instinct was that (a) either Litestar would look at the inbound request to automatically determine encoding for data, or (b) there would be a kwarg on @post(...) that would let me explicitly state my expected encoding. I happen to find Annotated[..., Body(media_type=...)] verbose in this case, but fair game: that's just personal aesthetics, and if it's a pattern used everywhere, then carry on. :-)

it doesn't seem to be failing on our end

Good to know, thanks. I'll see if I can get a reproducible case filed. Perhaps there's something quirky on my end, not sure.