Clarify docs for multipart file uploads #6383
Open
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This makes some documentation changes that clarify the
files
argument ofrequests.post()
et. al.Be more precise when we say "multiple files"
The
files
argument can either be a dict:Or a list of tuples:
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.'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.fileobj
". (It can be a file-like object, orstr
contents, orbytes
contents.)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:
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.