Add note on data fields in multipart form encoding (#1022)

* Add note on data fields in multipart form encoding

* Fix message

diff --git a/docs/advanced.md b/docs/advanced.md
index eae40a0793c132fccce6c378992cfc1facc45268..76321dd1b2c221d6ae44290d3d4c2ae2fb748d2d 100644 (file)
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -463,6 +463,8 @@ MIME header field.
 !!! tip
     It is safe to upload large files this way. File uploads are streaming by default, meaning that only one chunk will be loaded into memory at a time.
  
+ Non-file data fields can be included in the multipart form using by passing them to `data=...`.
+
 ## Customizing authentication
 
 When issuing requests or instantiating a client, the `auth` argument can be used to pass an authentication scheme to use. The `auth` argument may be one of the following...

diff --git a/docs/quickstart.md b/docs/quickstart.md
index 504822b605d07c04a4b625902d5598165b1cf6f4..67915780e01fe60b2f4c7bb59c95f79e75eb0acc 100644 (file)
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -191,6 +191,25 @@ of items for the file value:
 }
 ```
 
+If you need to include non-file data fields in the multipart form, use the `data=...` parameter:
+
+```python
+>>> data = {'message': 'Hello, world!'}
+>>> files = {'file': open('report.xls', 'rb')}
+>>> r = httpx.post("https://httpbin.org/post", data=data, files=files)
+>>> print(r.text)
+{
+  ...
+  "files": {
+    "file": "<... binary content ...>"
+  },
+  "form": {
+    "message": "Hello, world!",
+  },
+  ...
+}
+```
+
 ## Sending JSON Encoded Data
 
 Form encoded data is okay if all you need is a simple key-value data structure.