From: Tom Christie <tom@tomchristie.com>
Date: Mon, 17 Jun 2019 13:51:40 +0000 (+0100)
Subject: Add multipart docs
X-Git-Tag: 0.5.0~6
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d21e3ab2f0432b1501f19aabe1fdbbac1c05494d;p=thirdparty%2Fhttpx.git

Add multipart docs
---

diff --git a/README.md b/README.md
index 286aaa65..4a693392 100644
--- a/README.md
+++ b/README.md
@@ -54,7 +54,7 @@ Plus all the standard features of `requests`...
 * Automatic Decompression
 * Automatic Content Decoding
 * Unicode Response Bodies
-* Multipart File Uploads *TODO*
+* Multipart File Uploads
 * HTTP(S) Proxy Support *TODO*
 * Connection Timeouts
 * Streaming Downloads
diff --git a/docs/index.md b/docs/index.md
index 49d06532..92579c61 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -56,7 +56,7 @@ Plus all the standard features of `requests`...
 * Automatic Decompression
 * Automatic Content Decoding
 * Unicode Response Bodies
-* Multipart File Uploads *TODO*
+* Multipart File Uploads
 * HTTP(S) Proxy Support *TODO*
 * Connection Timeouts
 * Streaming Downloads
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 5638c680..b0b6a757 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -161,6 +161,39 @@ Form encoded data can also include multiple values form a given key.
 }
 ```
 
+## Sending Multipart File Uploads
+
+You can also upload files, using HTTP multipart encoding:
+
+```python
+>>> files = {'upload-file': open('report.xls', 'rb')}
+>>> r = http3.post("https://httpbin.org/post", files=files)
+>>> print(r.text)
+{
+  ...
+  "files": {
+    "upload-file": "<... binary content ...>"
+  },
+  ...
+}
+```
+
+You can also explicitly set the filename and content type, by using a tuple
+of items for the file value:
+
+```python
+>>> files = {'upload-file': ('report.xls', open('report.xls', 'rb'), 'application/vnd.ms-excel')}
+>>> r = http3.post("https://httpbin.org/post", files=files)
+>>> print(r.text)
+{
+  ...
+  "files": {
+    "upload-file": "<... binary content ...>"
+  },
+  ...
+}
+```
+
 ## Sending JSON Encoded Data
 
 Form encoded data is okay if all you need is simple key-value data structure.