Serialise FORM bodies with pydantic via type annotiations

[1oglop1]

Description

I started to use FastAPI and enjoyed serialisation of JSON bodies into pydantic models via type annotations and then I passed the form to my request handler and was surprised with AttributeError.

So I re-read the docs about forms and found its behaviour inconsistent with JSON bodies even though probably all code might already support this.

Example

from fastapi import FastAPI, Request, Form
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    another: str


@app.post("/item_form", response_model=Item)
async def find_item(r: Request):
    # current workaround
    form = await r.form()
    item = Item(**form)
    return item


@app.post("/item", response_model=Item)
async def find_item(r: Request, item: Item):
    # JSON Body works nicely
    print(item.name)
    return item


@app.post("/item_form_a", response_model=Item)
async def find_item(item: Item = Form(...)):
    # alternative 1
    # current: 422 Unprocessable Entity
    return item


class ItemForm(BaseModel):
    name: str = Form(...)
    another: str = Form(...)


@app.post("/item_form_b", response_model=ItemForm)
async def find_item(item: ItemForm):
    # alternative 2
    # current: AttributeError and 422 Unprocessable Entity
    print(item.name)
    return item

Motivation

I'm building a slack bot application which receives slash commands from Slack. POST request received from slack is an URL encoded body. https://api.slack.com/web#slack-web-api__basics__post-bodies__url-encoded-bodies

[Mause]

Please make sure you have installed the python-multipart library to enable form body support

[1oglop1]

@Mause I did, it did not change anything. I was talking to @ycd about this via gitter.
AFAIK python-multipart is mainly for support of files.

[ArcLightSlavik]

You can do something like this

class AnyForm(BaseModel):
    name: str
    another: str


@app.post("/item_form_b", response_model=AnyForm)
async def find_item(name: str = Form(...), another: str = Form(...)):
    any_form = AnyForm(name=name, another=another)
    return any_form

or you can also use Depends()

class AnyForm(BaseModel):
    name: str
    another: str

    @classmethod
    def as_form(cls, name: str = Form(...), another: str = Form(...)):
        return cls(name=name, another=another)


@app.post("/item_form_a", response_model=AnyForm)
async def any_view(form_data: AnyForm = Depends(AnyForm.as_form)):
    return form_data

Both of those look nice in the /docs as well 🙂 (something you won't get with await request.Form())

Which you use is up to you, i prefer the first example since i'm not a fan of using Depends for too many stuff.

[Mause]

This is another possibility:

def form_body(cls):
    cls.__signature__ = cls.__signature__.replace(
        parameters=[
            arg.replace(default=Form(...))
            for arg in cls.__signature__.parameters.values()
        ]
    )
    return cls


@form_body
class Item(BaseModel):
    name: str
    another: str

[1oglop1]

@ArcLightSlavik Thank you for providing examples
I'd really like to avoid the first option because it goes agains general advice of having maximum 5 parameters per function.
The second option with Depends looks like something I could use!

@Mause Could you please provide more complete example? I'm not sure I used it right because I got an error
This is how I tried to use it.

def form_body(cls):
    cls.__signature__ = cls.__signature__.replace(
        parameters=[
            arg.replace(default=Form(...))
            for arg in cls.__signature__.parameters.values()
        ]
    )
    return cls


@form_body
class Item(BaseModel):
    name: str
    another: str

@app.post("/item")
async def find_item(item: Item):
    print(item.name)
    return item

[Mause]

Sorry, should have given a full example:

from fastapi.testclient import TestClient
from fastapi import FastAPI, Depends, Form
from pydantic import BaseModel


app = FastAPI()


def form_body(cls):
    cls.__signature__ = cls.__signature__.replace(
        parameters=[
            arg.replace(default=Form(...))
            for arg in cls.__signature__.parameters.values()
        ]
    )
    return cls


@form_body
class Item(BaseModel):
    name: str
    another: str


@app.post('/test', response_model=Item)
def endpoint(item: Item = Depends(Item)):
    return item


tc = TestClient(app)


r = tc.post('/test', data={'name': 'name', 'another': 'another'})

assert r.status_code == 200
assert r.json() == {'name': 'name', 'another': 'another'}

[1oglop1]

Thanks @Mause this is just perfect for my use-case!

[ArcLightSlavik]

@1oglop1 Could you close the issue

[mjgraham123]

I took @Mause's idea (and some other add-ons I found Googling) and took it one step further. The current solutions didn't carry additional parameters like alias, description, example, and validation into the model / documentation. My solution is below. Any thoughts about potential issues or ways to further improve?

def form_body_model(cls: Type[BaseModel]):
    """Adds an as_form class method to decorated models.

    The as_form class method can be used with FastAPI endpoints to treat the
    model as a form body, eliminating the need to have all of the form fields
    described in the endpoint function definition.

    Example usage:
    @form_body_model
    class MessageIn(BaseModel):
        from_number: str = Form(
            ...,
            alias='FromNumber',
            example='+18445551212',
            description='Sender Phone Number',
        )
        to_number: str = Form(
            ...,
            alias='ToNumber',
            example='+18885551212',
            description='Recipient Phone Number',
        )
        body: str = Form(
            ...,
            alias='Body',
            example='Happy Birthday',
            description='Text message body',
        )
        delivery_time: Optional[datetime.datetime] = Form(
            '',
            alias='ApiVersion',
            example='2021-03-10T07:00:00-0500',
            description='Scheduled time for delivery (default is immediate)',
        )
        log_comment: Optional[str] = Form(
            '',
            alias='Body',
            example='This is a test',
            description='Comments that are captured in the log',
        )


    @route.post('/message/schedule')
    async def schedule_message(data: MessageIn = Depends(MessageIn.as_form)):
        # data is a Pydantic model with parsed form post data
        print(data.dict())
        return data.dict()
    """
    new_params = []
    for field in cls.__fields__.values():
        new_params.append(
            inspect.Parameter(
                field.alias,
                inspect.Parameter.POSITIONAL_ONLY,
                annotation=cls.__annotations__[field.name],
                default=(
                    Form(
                        field.default if not field.required else ...,
                        description=field.field_info.description,
                        alias=field.alias,
                        ge=getattr(field, 'ge', None),
                        gt=getattr(field, 'gt', None),
                        le=getattr(field, 'le', None),
                        lt=getattr(field, 'lt', None),
                        max_length=getattr(field, 'max_length', None),
                        min_length=getattr(field, 'min_length', None),
                        regex=getattr(field, 'regex', None),
                        title=getattr(field, 'title', None),
                        media_type=getattr(field, 'media_type', None),
                        **field.field_info.extra,
                    )
                ),
            )
        )

    async def _as_form(**data):
        return cls(**data)

    sig = inspect.signature(_as_form)
    sig = sig.replace(parameters=new_params)
    _as_form.__signature__ = sig
    setattr(cls, 'as_form', _as_form)

    return cls

[Priyansh2]

Hi @mjgraham123 . I'm a newbie to Fastapi and pydantic ecosystem. How is this code changed with v2 pydantic? I am getting error at field.alias inside inspect.Parameter method

inspect.Parameter(
  File "/usr/lib/python3.8/inspect.py", line 2507, in __init__ 
    raise TypeError(msg)
TypeError: name must be a str, not a NoneType

[benlau6]

@mjgraham123's idea worked perfectly in my use case with slight changes, that getattr from field.field_info instead of field, otherwise those attributes will be ignored.

                        ge=getattr(field.field_info, 'ge', None),
                        gt=getattr(field.field_info, 'gt', None),
                        le=getattr(field.field_info, 'le', None),
                        lt=getattr(field.field_info, 'lt', None),
                        max_length=getattr(field.field_info, 'max_length', None),
                        min_length=getattr(field.field_info, 'min_length', None),
                        regex=getattr(field.field_info, 'regex', None),
                        title=getattr(field.field_info, 'title', None),
                        media_type=getattr(field.field_info, 'media_type', None),

and these are the libraries to be imported

from fastapi import Form
from pydantic import BaseModel
from typing import Type
import inspect

[imiten]

@Mause if I use Json as my type for a parameter in pydantic model I get error that "JSON object must be str, bytes or bytearray (type=type_error.json)". I have Form input field that shall pass json string as text. If I use in pydantic model its type as str things will work but am loosing that validate json feature. either you can alter your code above or guide on how to further use Depends to do that validation in the pydantic model.

[dotX12]

I've implemented a simple library to use the pydantic schema for www-form-data FastAPI, hope you find it easier to work with :) Full support for validators, alias, example, regex, gt, ge and more...

https://github.com/dotX12/pyfa-converter

[sanzoghenzo]

Any chance this will updated to use pydantic v2?
As of now it crashes due to the missing pydantic.fields.ModelField (now the same information is in cls.model_fields, which is a dict[str, FieldInfo]), and who knows which other errors...

I also would like to see this feature built in into FastAPI!

[ShadowLNC]

I would really love to see this pyfa-converter library included upstream in fastapi - it solved my issue immediately. Thanks @dotX12 😁

Just from searching for ways to resolve this issue, I think it's a semi-common use case and it'd be great to see officially supported. 🎉

[gabrielbitti]

Based on @Mause's implementation, I did the following:

def form_body(cls):
    """."""
    params = []
    for arg in cls.__signature__.parameters.values():
        arg_type = str(arg).split(':')[1]
        new_arg = arg.replace(default=Form(...))
        if 'Optional' in arg_type:
            new_arg = arg.replace(default=Form(None))
        params.append(new_arg)

    cls.__signature__ = cls.__signature__.replace(parameters=params)

    return cls

And now the pydantic schema can have Optional parameters.

Example here

[TomFaulkner]

This works well. Thank you.

I'll probably include the newer typehint style for optional, num: int | None = None syntax.