Add multipart docs

diff --git a/README.md b/README.md
index 286aaa65d01eae090e5c0c3d6dfd08d78bd72a6a..4a693392940db947f7c5cd9a6a91b8f030e3e154 100644 (file)
--- 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 49d06532628fbf1798426fb95943b0f68a3f218b..92579c61a96f66e2a32def93791863750270c1d7 100644 (file)
--- 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 5638c68019654e9176c822dd52bd830109e80873..b0b6a757e0b4ed6ae0095a18eb6b007a322941db 100644 (file)
--- 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.