Fix documentation around JSON and content-type (#2598)

docs/client_advanced.rst

@@ -26,27 +26,35 @@ Custom Request Headers
 If you need to add HTTP headers to a request, pass them in a
 :class:`dict` to the *headers* parameter.
 
-For example, if you want to specify the content-type for the previous
-example::
+For example, if you want to specify the content-type directly::
 
-    import json
-    url = 'https://api.github.com/some/endpoint'
-    payload = {'some': 'data'}
-    headers = {'content-type': 'application/json'}
+    url = 'http://example.com/image'
+    payload = b'GIF89a\x01\x00\x01\x00\x00\xff\x00,\x00\x00'
+              b'\x00\x00\x01\x00\x01\x00\x00\x02\x00;'
+    headers = {'content-type': 'image/gif'}
 
     await session.post(url,
-                       data=json.dumps(payload),
+                       data=payload,
                        headers=headers)
 
 You also can set default headers for all session requests::
 
-    async with aiohttp.ClientSession(
-        headers={"Authorization": "Basic bG9naW46cGFzcw=="}) as session:
+    headers={"Authorization": "Basic bG9naW46cGFzcw=="}
+    async with aiohttp.ClientSession(headers) as session:
         async with session.get("http://httpbin.org/headers") as r:
             json_body = await r.json()
             assert json_body['headers']['Authorization'] == \
                 'Basic bG9naW46cGFzcw=='
 
+Typical use case is sending JSON body. You can specify content type
+directly as shown above, but it is more convenient to use special keyword
+``json``::
+
+    await session.post(url, json={'example': 'text'})
+
+The same for *text/plain*::
+
+    await session.post(url, text='Привет, Мир!')
 
 Custom Cookies
 --------------

docs/client_quickstart.rst

@@ -251,18 +251,22 @@ dictionary of data will automatically be form-encoded when the request is made::
     }
 
 If you want to send data that is not form-encoded you can do it by
-passing a :class:`str` instead of a :class:`dict`. This data will be
-posted directly.
+passing a :class:`bytes` instead of a :class:`dict`. This data will be
+posted directly and content-type set to 'application/octet-stream' by
+default::
 
-For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data::
+    async with session.post(url, data=b'\x00Binary-data\x00') as resp:
+        ...
 
-    import json
-    url = 'https://api.github.com/some/endpoint'
-    payload = {'some': 'data'}
+If you want to send JSON data::
 
-    async with session.post(url, data=json.dumps(payload)) as resp:
+    async with session.post(url, json={'example': 'test'}) as resp:
         ...
 
+To send text with appropriate content-type just use ``text`` attribute ::
+
+    async with session.post(url, text='Тест') as resp:
+        ...
 
 POST a Multipart-Encoded File
 -----------------------------

docs/web_advanced.rst

@@ -389,25 +389,20 @@ A common use of middlewares is to implement custom error pages.  The following
 example will render 404 errors using a JSON response, as might be appropriate
 a JSON REST service::
 
-    import json
     from aiohttp import web
 
-    def json_error(message):
-        return web.Response(
-            body=json.dumps({'error': message}).encode('utf-8'),
-            content_type='application/json')
-
     @web.middleware
     async def error_middleware(request, handler):
         try:
             response = await handler(request)
-            if response.status == 404:
-                return json_error(response.message)
-            return response
+            if response.status != 404:
+                return response
+            message = response.message
         except web.HTTPException as ex:
-            if ex.status == 404:
-                return json_error(ex.reason)
-            raise
+            if ex.status != 404:
+                raise
+            message = ex.reason
+        return web.json_response({'error': message})
 
     app = web.Application(middlewares=[error_middleware])