Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify docs for multipart file uploads #6383

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

SyntaxColoring
Copy link

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:

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
Copy link
Contributor

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
Copy link
Author

@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
Copy link
Author

Bump. Are any changes needed for this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants