From: Mattwmaster58 <mattmarcus58@gmail.com>
Date: Mon, 2 Dec 2019 11:56:25 +0000 (-0700)
Subject: Clarify multipart documentation (#580)
X-Git-Tag: 0.9.0~29
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=33cb39733f91be715cb84d7934503b221fac12a9;p=thirdparty%2Fhttpx.git

Clarify multipart documentation (#580)

*Clarify multipart behvaiour
---

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')}