Merge pull request #284 from twm/278-json-docs

Improve JSON documentation

Author: twm

changelog.d/278.doc.rst

@@ -0,0 +1 @@
+An example of sending and receiving JSON has been added.

docs/examples/basic_post.py

@@ -1,15 +1,12 @@
-import json
-
 from twisted.internet.task import react
 from _utils import print_response
 
 import treq
 
 
-def main(reactor, *args):
-    d = treq.post('https://httpbin.org/post',
-                  json.dumps({"msg": "Hello!"}).encode('ascii'),
-                  headers={b'Content-Type': [b'application/json']})
+def main(reactor):
+    d = treq.post("https://httpbin.org/post",
+                  data={"form": "data"})
     d.addCallback(print_response)
     return d
 

docs/examples/json_post.py

@@ -0,0 +1,18 @@
+from pprint import pprint
+
+from twisted.internet import defer
+from twisted.internet.task import react
+
+import treq
+
+
+@defer.inlineCallbacks
+def main(reactor):
+    response = yield treq.post(
+        'https://httpbin.org/post',
+        json={"msg": "Hello!"},
+    )
+    data = yield response.json()
+    pprint(data)
+
+react(main, [])

docs/howto.rst

@@ -58,6 +58,22 @@ or a ``list`` of ``str`` values.
 
 Full example: :download:`query_params.py <examples/query_params.py>`
 
+JSON
+----
+
+:meth:`HTTPClient.request() <treq.client.HTTPClient.request>` supports a *json* keyword argument that gives a data structure to serialize as JSON (using :func:`json.dumps()`).
+This also implies a ``Content-Type: application/json`` request header.
+The *json* parameter is mutually-exclusive with *data*.
+
+The :meth:`_Response.json()` method decodes a JSON response body.
+It buffers the whole response and decodes it with :func:`json.loads()`.
+
+.. literalinclude:: examples/json_post.py
+    :linenos:
+    :pyobject: main
+
+Full example: :download:`json_post.py <examples/json_post.py>`
+
 Auth
 ----
 

docs/index.rst

@@ -29,17 +29,15 @@ GET
 +++
 
 .. literalinclude:: examples/basic_get.py
-    :linenos:
-    :lines: 7-10
+    :pyobject: main
 
 Full example: :download:`basic_get.py <examples/basic_get.py>`
 
 POST
 ++++
 
 .. literalinclude:: examples/basic_post.py
-    :linenos:
-    :lines: 9-14
+    :pyobject: main
 
 Full example: :download:`basic_post.py <examples/basic_post.py>`