From: Florimond Manca <florimond.manca@gmail.com>
Date: Mon, 15 Jun 2020 18:40:17 +0000 (+0200)
Subject: Add note on data fields in multipart form encoding (#1022)
X-Git-Tag: 0.14.0~70
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0f7d644b8dba432c5eec08157947a4e551996fa1;p=thirdparty%2Fhttpx.git

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 eae40a07..76321dd1 100644
--- 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 504822b6..67915780 100644
--- 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.