From 33cb39733f91be715cb84d7934503b221fac12a9 Mon Sep 17 00:00:00 2001 From: Mattwmaster58 Date: Mon, 2 Dec 2019 04:56:25 -0700 Subject: [PATCH] Clarify multipart documentation (#580) *Clarify multipart behvaiour --- docs/advanced.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/advanced.md b/docs/advanced.md index bc1d0f87..d087bd25 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -347,7 +347,7 @@ await httpx.get(url, timeout=timeout) # Does not timeout, returns after 10s As mentioned in the [quickstart](/quickstart#sending-multipart-file-uploads) multipart file encoding is available by passing a dictionary with the -name of the payloads as keys and a tuple of elements as values. +name of the payloads as keys and either tuple of elements or a file-like object or a string as values. ```python >>> files = {'upload-file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel')} @@ -362,17 +362,17 @@ name of the payloads as keys and a tuple of elements as values. } ``` -More specifically, this tuple must have at least two elements and maximum of three: +More specifically, if a tuple is used as a value, it must have between 2 and 3 elements: -- The first one is an optional file name which can be set to `None`. -- The second may be a file-like object or a string which will be automatically +- The first element is an optional file name which can be set to `None`. +- The second element may be a file-like object or a string which will be automatically encoded in UTF-8. -- An optional third element can be included with the +- An optional third element can be used to specify the [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_Types) -of the file being uploaded. If not specified HTTPX will attempt to guess the MIME type -based on the file name specified as the first element or the tuple, if that -is set to `None` or it cannot be inferred from it, HTTPX will default to -`applicaction/octet-stream`. +of the file being uploaded. If not specified HTTPX will attempt to guess the MIME type based +on the file name, with unknown file extensions defaulting to "application/octet-stream". +If the file name is explicitly set to `None` then HTTPX will not include a content-type +MIME header field. ```python >>> files = {'upload-file': (None, 'text content', 'text/plain')} -- 2.47.3