allow using Request.form() as a context manager

[adriangb]

Coming from #1888 (comment)

Evidently forgetting / not knowing to call UploadFile.close() is a common issue.
I think FastAPI should be able to automatically call that internally, but Starlette should also do more to nudge users in the right direction. I think the right tool for that in this situation is a context manager.

This PR allows users to use Request.form() both directly (as before) and as a context manager.

I would suggest that we then deprecate the await request.form() usage so that there is only 1 correct way to do things.

[tiangolo]

Amazing! And beautiful types! 🤩 👏

[tiangolo]

Should this be async?

Suggested change

	def form(self) -> AwaitableOrContextManager[FormData]:
	async def form(self) -> AwaitableOrContextManager[FormData]:

I understand it would work either way just because the awaitable thing is returned, but maybe it could help to make it async, to make it explicit in the function that it returns something to be awaited. What do you think?

[adriangb]

Unfortunately I don't think that will work: we want to pass an await able object to AwaitableOrContextManagerWrapper so that it can be used like async with request.form() and not async with await request.form().

[Kludex]

I would suggest that we then deprecate the await request.form() usage so that there is only 1 correct way to do things.

I can live with it. 🤷‍♂️

Also, since 3.11 warns, it shouldn't be much of an issue, I guess?

[Kludex]

@adriangb Would you mind adding some lines to the docs about this? 🙏

[Kludex]

I would suggest that we then deprecate the await request.form() usage so that there is only 1 correct way to do things.

I can live with it. man_shrugging

Also, since 3.11 warns, it shouldn't be much of an issue, I guess?

I'd say for us to focus on getting 1.0 out. It's not a big deal to further deprecate later on.

[adriangb]

I opted to just edit the usage in the docs examples. I do think we should recommend this usage over the await request.form() usage so I felt like adding a note along the lines of "by the way you can do it both ways" would create confusion with no benefit to users. If they're used to doing it the other way they can continue to do so (unless we decide to deprecate it at some point, which I am in favor of but I agree doesn't need to happen right now).