Add json convenience methods to websocket message objects (#897)

* Add json convenience methods to websocket message objects

* add versionadded tags, rename base class, fix typo

* pass json loader from receive_json to Message.json

aiohttp/web_ws.py

@@ -1,5 +1,6 @@
 import sys
 import asyncio
+import json
 import warnings
 
 from . import hdrs
@@ -285,6 +286,15 @@ def receive_bytes(self):
                                                                msg.data))
         return msg.data
 
+    @asyncio.coroutine
+    def receive_json(self, *, loads=json.loads):
+        msg = yield from self.receive()
+        if msg.tp != MsgType.text:
+            raise TypeError(
+                "Received message {}:{!r} is not str".format(msg.tp, msg.data)
+            )
+        return msg.json(loads=loads)
+
     def write(self, data):
         raise RuntimeError("Cannot call .write() for websocket")
 

aiohttp/websocket.py

@@ -4,6 +4,7 @@
 import binascii
 import collections
 import hashlib
+import json
 import os
 import random
 import sys
@@ -57,7 +58,6 @@
            hdrs.SEC_WEBSOCKET_KEY,
            hdrs.SEC_WEBSOCKET_PROTOCOL)
 
-Message = collections.namedtuple('Message', ['tp', 'data', 'extra'])
 
 UNPACK_LEN2 = Struct('!H').unpack_from
 UNPACK_LEN3 = Struct('!Q').unpack_from
@@ -69,6 +69,18 @@
 MSG_SIZE = 2 ** 14
 
 
+_MessageBase = collections.namedtuple('Message', ['tp', 'data', 'extra'])
+
+
+class Message(_MessageBase):
+    def json(self, *, loads=json.loads):
+        """Return parsed JSON data.
+
+        .. versionadded:: 0.22
+        """
+        return loads(self.data)
+
+
 class WebSocketError(Exception):
     """WebSocket protocol parser error."""
 

docs/web_reference.rst

@@ -260,9 +260,9 @@ like one using :meth:`Request.copy`.
 
          async def json(self, *, loads=json.loads):
              body = await self.text()
-             return loader(body)
+             return loads(body)
 
-      :param callable loader: any :term:`callable` that accepts
+      :param callable loads: any :term:`callable` that accepts
                               :class:`str` and returns :class:`dict`
                               with parsed JSON (:func:`json.loads` by
                               default).
@@ -894,7 +894,7 @@ WebSocketResponse
 
    .. coroutinemethod:: receive_str()
 
-      A :ref:`coroutine<coroutine>` that calls :meth:`receive_mgs` but
+      A :ref:`coroutine<coroutine>` that calls :meth:`receive` but
       also asserts the message type is
       :const:`~aiohttp.websocket.MSG_TEXT`.
 
@@ -904,14 +904,32 @@ WebSocketResponse
 
    .. coroutinemethod:: receive_bytes()
 
-      A :ref:`coroutine<coroutine>` that calls :meth:`receive_mgs` but
+      A :ref:`coroutine<coroutine>` that calls :meth:`receive` but
       also asserts the message type is
       :const:`~aiohttp.websocket.MSG_BINARY`.
 
       :return bytes: peer's message content.
 
       :raise TypeError: if message is :const:`~aiohttp.websocket.MSG_TEXT`.
 
+   .. coroutinemethod:: receive_json(*, loads=json.loads)
+
+      A :ref:`coroutine<coroutine>` that calls :meth:`receive`, asserts the
+      message type is :const:`~aiohttp.websocket.MSG_TEXT`, and loads the JSON
+      string to a Python dict.
+
+      :param callable loads: any :term:`callable` that accepts
+                              :class:`str` and returns :class:`dict`
+                              with parsed JSON (:func:`json.loads` by
+                              default).
+
+      :return dict: loaded JSON content
+
+      :raise TypeError: if message is :const:`~aiohttp.websocket.MSG_BINARY`.
+      :raise ValueError: if message is not valid JSON.
+
+      .. versionadded:: 0.22
+
 
 .. versionadded:: 0.14