Improve documentation of request.FILES

[Janos Roden]

Regarding request.FILES and multipart/form-data requests I think it worth to mention in the doc that the filename parameter of the content-disposition header of the part is ​crucial to handle the part as a file.

I used a low level library to generate requests and I thought Django will use a temporary file (and file name) for this content.
Of course after I found out how it works it's make sense, but read about it in the docs would have help me to fix my code much quicker.

[Carlton Gibson]

HI Janos, yes OK. Very happy to look at a suggestion to the docs here. Thanks.

[Janos Roden]

Hi Carlton,

I'm thinking about ​this section:

Note that request.FILES will only contain data if the request method was POST and the <form> that posted the request has the attribute enctype="multipart/form-data". Otherwise, request.FILES will be empty.

Could be extended as

Note that request.FILES will only contain data from form fields if the request method was POST and the <form> that posted the request has the attribute enctype="multipart/form-data" and contains at least one <intput type="file"> field.
Or more technically if request method was POST, the Content-Type general header was multipart/form-data and the Content-Disposition subpart header contains the filename parameter (default behavior in browsers for this enctype).
Otherwise, request.FILES will be empty.

Feel free to correct my english, please.
I hope it isn't too complicated, what do you think?

[Carlton Gibson]

Hi Janos. First glance seems a bit 😬: the point is the Content-Disposition header right? But how do we state that in the context of form submission... — yes, via the input... — Can you open a PR, and we discuss there? (It's much easier to review and suggest changes there.) Thanks.

[Janos Roden]

Okay, I created one, let's discuss how to phrase it: ​https://github.com/django/django/pull/13425

[Carlton Gibson <carlton@…>]

In 9e4b1ad:

Fixed #32004 -- Clarified docs for when request.FILES is set.

Co-authored-by: Carlton Gibson <carlton.gibson@…>

[Carlton Gibson <carlton.gibson@…>]

In 1d7c4add:

[3.1.x] Fixed #32004 -- Clarified docs for when request.FILES is set.

Co-authored-by: Carlton Gibson <carlton.gibson@…>

Backport of 9e4b1ad33e436e8fe60af756d7e09639ee886ac2 from master