Seperate content=... and data=... parameters (#1266)

* Seperate content=... and data=... parameters

* Update compatibility.md

Author: lovelydinosaur

docs/compatibility.md

@@ -9,6 +9,28 @@ This documentation outlines places where the API differs...
 Accessing `response.url` will return a `URL` instance, rather than a string.
 Use `str(response.url)` if you need a string instance.
 
+## Request Content
+
+For uploading raw text or binary content we prefer to use a `content` parameter,
+in order to better separate this usage from the case of uploading form data.
+
+For example, using `content=...` to upload raw content:
+
+```python
+# Uploading text, bytes, or a bytes iterator.
+httpx.post(..., content=b"Hello, world")
+```
+
+And using `data=...` to send form data:
+
+```python
+# Uploading form data.
+httpx.post(..., data={"message": "Hello, world"})
+```
+
+If you're using a type checking tool such as `mypy`, you'll see warnings issues if using test/byte content with the `data` argument.
+However, for compatibility reasons with `requests`, we do still handle the case where `data=...` is used with raw binary and text contents.
+
 ## Status Codes
 
 In our documentation we prefer the uppercased versions, such as `codes.NOT_FOUND`, but also provide lower-cased versions for API compatibility with `requests`.

docs/quickstart.md

@@ -249,13 +249,18 @@ For more complicated data structures you'll often want to use JSON encoding inst
 
 ## Sending Binary Request Data
 
-For other encodings, you should use either a `bytes` type or a generator
-that yields `bytes`.
+For other encodings, you should use the `content=...` parameter, passing
+either a `bytes` type or a generator that yields `bytes`.
 
-You'll probably also want to set a custom `Content-Type` header when uploading
+```pycon
+>>> content = b'Hello, world'
+>>> r = httpx.post("https://httpbin.org/post", content=content)
+```
+
+You may also want to set a custom `Content-Type` header when uploading
 binary data.
 
-## Response Status Codes
+## Response Status Codes
 
 We can inspect the HTTP status code of the response:
 

httpx/_api.py

@@ -10,6 +10,7 @@
     HeaderTypes,
     ProxiesTypes,
     QueryParamTypes,
+    RequestContent,
     RequestData,
     RequestFiles,
     TimeoutTypes,
@@ -23,6 +24,7 @@ def request(
     url: URLTypes,
     *,
     params: QueryParamTypes = None,
+    content: RequestContent = None,
     data: RequestData = None,
     files: RequestFiles = None,
     json: typing.Any = None,
@@ -46,8 +48,10 @@ def request(
     * **url** - URL for the new `Request` object.
     * **params** - *(optional)* Query parameters to include in the URL, as a
     string, dictionary, or list of two-tuples.
-    * **data** - *(optional)* Data to include in the body of the request, as a
-    dictionary
+    * **content** - *(optional)* Binary content to include in the body of the
+    request, as bytes or a byte iterator.
+    * **data** - *(optional)* Form data to include in the body of the request,
+    as a dictionary.
     * **files** - *(optional)* A dictionary of upload files to include in the
     body of the request.
     * **json** - *(optional)* A JSON serializable object to include in the body
@@ -89,6 +93,7 @@ def request(
         return client.request(
             method=method,
             url=url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -105,6 +110,7 @@ def stream(
     url: URLTypes,
     *,
     params: QueryParamTypes = None,
+    content: RequestContent = None,
     data: RequestData = None,
     files: RequestFiles = None,
     json: typing.Any = None,
@@ -133,6 +139,7 @@ def stream(
         method=method,
         url=url,
         params=params,
+        content=content,
         data=data,
         files=files,
         json=json,
@@ -266,6 +273,7 @@ def head(
 def post(
     url: URLTypes,
     *,
+    content: RequestContent = None,
     data: RequestData = None,
     files: RequestFiles = None,
     json: typing.Any = None,
@@ -288,6 +296,7 @@ def post(
     return request(
         "POST",
         url,
+        content=content,
         data=data,
         files=files,
         json=json,
@@ -307,6 +316,7 @@ def post(
 def put(
     url: URLTypes,
     *,
+    content: RequestContent = None,
     data: RequestData = None,
     files: RequestFiles = None,
     json: typing.Any = None,
@@ -329,6 +339,7 @@ def put(
     return request(
         "PUT",
         url,
+        content=content,
         data=data,
         files=files,
         json=json,
@@ -348,6 +359,7 @@ def put(
 def patch(
     url: URLTypes,
     *,
+    content: RequestContent = None,
     data: RequestData = None,
     files: RequestFiles = None,
     json: typing.Any = None,
@@ -370,6 +382,7 @@ def patch(
     return request(
         "PATCH",
         url,
+        content=content,
         data=data,
         files=files,
         json=json,

httpx/_client.py

@@ -39,6 +39,7 @@
     HeaderTypes,
     ProxiesTypes,
     QueryParamTypes,
+    RequestContent,
     RequestData,
     RequestFiles,
     TimeoutTypes,
@@ -226,6 +227,7 @@ def stream(
         method: str,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -249,6 +251,7 @@ def stream(
         request = self.build_request(
             method=method,
             url=url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -269,6 +272,7 @@ def build_request(
         method: str,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -294,6 +298,7 @@ def build_request(
         return Request(
             method,
             url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -679,6 +684,7 @@ def request(
         method: str,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -708,6 +714,7 @@ def request(
         request = self.build_request(
             method=method,
             url=url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -962,6 +969,7 @@ def post(
         self,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -980,6 +988,7 @@ def post(
         return self.request(
             "POST",
             url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -995,6 +1004,7 @@ def put(
         self,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -1013,6 +1023,7 @@ def put(
         return self.request(
             "PUT",
             url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -1028,6 +1039,7 @@ def patch(
         self,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -1046,6 +1058,7 @@ def patch(
         return self.request(
             "PATCH",
             url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -1313,6 +1326,7 @@ async def request(
         method: str,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -1342,6 +1356,7 @@ async def request(
         request = self.build_request(
             method=method,
             url=url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -1599,6 +1614,7 @@ async def post(
         self,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -1617,6 +1633,7 @@ async def post(
         return await self.request(
             "POST",
             url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -1632,6 +1649,7 @@ async def put(
         self,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -1650,6 +1668,7 @@ async def put(
         return await self.request(
             "PUT",
             url,
+            content=content,
             data=data,
             files=files,
             json=json,
@@ -1665,6 +1684,7 @@ async def patch(
         self,
         url: URLTypes,
         *,
+        content: RequestContent = None,
         data: RequestData = None,
         files: RequestFiles = None,
         json: typing.Any = None,
@@ -1683,6 +1703,7 @@ async def patch(
         return await self.request(
             "PATCH",
             url,
+            content=content,
             data=data,
             files=files,
             json=json,