Make the `data` vs `json` parameters more clear
As question
and answer popularity shows that there is a lot of people who
do not understand the distinction.
@@ -283,8 +283,12 @@ For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data::
>>> r = requests.post(url, data=json.dumps(payload))
-Instead of encoding the ``dict`` yourself, you can also pass it directly using
-the ``json`` parameter (added in version 2.4.2) and it will be encoded automatically::
+Please note that the above code will NOT add the ``Content-Type`` header
+(so in particular it will NOT set it to ``application/json``).
+
+If you need that header set and you don't want to encode the ``dict`` yourself,
+you can also pass it directly using the ``json`` parameter (added in version 2.4.2)
+and it will be encoded automatically:
>>> url = 'https://api.github.com/some/endpoint'
>>> payload = {'some': 'data'}
@@ -293,8 +297,6 @@ the ``json`` parameter (added in version 2.4.2) and it will be encoded automatic
Note, the ``json`` parameter is ignored if either ``data`` or ``files`` is passed.
-Using the ``json`` parameter in the request will change the ``Content-Type`` in the header to ``application/json``.
-
POST a Multipart-Encoded File
-----------------------------
