Clarify docs for multipart file uploads

[SyntaxColoring]

This makes some documentation changes that clarify the files argument of requests.post() et. al.

Be more precise when we say "multiple files"

The files argument can either be a dict:

files = {
    "field_1": file_1,
    "field_2": file_2,
}

Or a list of tuples:

files = [
    ("field_1": file_1),
    ("field_2": file_2),
]

A few places implied that to "upload multiple files in one request," you had to use the list-of-tuples syntax. But the dict syntax supports multiple files just fine. The added power in the list-of-tuples syntax seems to be that you can upload multiple files to the same form field. So, we now say that.

Update the reference docs

The API reference documentation did not completely describe what values were acceptable for files, and in some cases it was misleading.

• It didn't mention the list-of-tuples syntax at all.
• It said you could pass a "dictionary of 'name': file-like-objects". The pluralization there makes it look like you can do something like {"name": [file_1, file_2]}, but that's not correct.
• It didn't describe what you were allowed to provide as a "fileobj". (It can be a file-like object, or str contents, or bytes contents.)
• It said name to refer to the value that Requests uses as the form field name. This could be misconstrued as the file name. RFC 7578 and other examples within Requests call it the "field name" or "form field name."

My sources for these changes:

• The existing POST a Multipart-Encoded File section.
• The existing POST Multiple Multipart-Encoded Files section.
• Request's type stubs.

It's difficult to describe this API concisely because it accepts so many different input shapes, and these additions do make the rendered docs feel a bit crowded.

[sigmavirus24]

The primary benefit of using list of tuples is that order is preserved which is important for some servers that expect fields in a very specific ordering which is way more than it should be

[SyntaxColoring]

@sigmavirus24 Thanks. To be clear, do you think some of this PR needs to change to reflect that, or were you just commenting to lend context?

[SyntaxColoring]

Bump. Are any changes needed for this?