[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 13/32] python/aqmp: add QMP Message format
From: |
John Snow |
Subject: |
[PULL 13/32] python/aqmp: add QMP Message format |
Date: |
Mon, 27 Sep 2021 15:24:54 -0400 |
The Message class is here primarily to serve as a solid type to use for
mypy static typing for unambiguous annotation and documentation.
We can also stuff JSON serialization and deserialization into this class
itself so it can be re-used even outside this infrastructure.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-id: 20210915162955.333025-14-jsnow@redhat.com
Signed-off-by: John Snow <jsnow@redhat.com>
---
python/qemu/aqmp/__init__.py | 4 +-
python/qemu/aqmp/message.py | 209 +++++++++++++++++++++++++++++++++++
2 files changed, 212 insertions(+), 1 deletion(-)
create mode 100644 python/qemu/aqmp/message.py
diff --git a/python/qemu/aqmp/__init__.py b/python/qemu/aqmp/__init__.py
index 88ead4c0238..96fff1e5f3e 100644
--- a/python/qemu/aqmp/__init__.py
+++ b/python/qemu/aqmp/__init__.py
@@ -22,12 +22,14 @@
# the COPYING file in the top-level directory.
from .error import AQMPError
+from .message import Message
from .protocol import ConnectError, Runstate, StateError
# The order of these fields impact the Sphinx documentation order.
__all__ = (
- # Classes
+ # Classes, most to least important
+ 'Message',
'Runstate',
# Exceptions, most generic to most explicit
diff --git a/python/qemu/aqmp/message.py b/python/qemu/aqmp/message.py
new file mode 100644
index 00000000000..f76ccc90746
--- /dev/null
+++ b/python/qemu/aqmp/message.py
@@ -0,0 +1,209 @@
+"""
+QMP Message Format
+
+This module provides the `Message` class, which represents a single QMP
+message sent to or from the server.
+"""
+
+import json
+from json import JSONDecodeError
+from typing import (
+ Dict,
+ Iterator,
+ Mapping,
+ MutableMapping,
+ Optional,
+ Union,
+)
+
+from .error import ProtocolError
+
+
+class Message(MutableMapping[str, object]):
+ """
+ Represents a single QMP protocol message.
+
+ QMP uses JSON objects as its basic communicative unit; so this
+ Python object is a :py:obj:`~collections.abc.MutableMapping`. It may
+ be instantiated from either another mapping (like a `dict`), or from
+ raw `bytes` that still need to be deserialized.
+
+ Once instantiated, it may be treated like any other MutableMapping::
+
+ >>> msg = Message(b'{"hello": "world"}')
+ >>> assert msg['hello'] == 'world'
+ >>> msg['id'] = 'foobar'
+ >>> print(msg)
+ {
+ "hello": "world",
+ "id": "foobar"
+ }
+
+ It can be converted to `bytes`::
+
+ >>> msg = Message({"hello": "world"})
+ >>> print(bytes(msg))
+ b'{"hello":"world","id":"foobar"}'
+
+ Or back into a garden-variety `dict`::
+
+ >>> dict(msg)
+ {'hello': 'world'}
+
+
+ :param value: Initial value, if any.
+ :param eager:
+ When `True`, attempt to serialize or deserialize the initial value
+ immediately, so that conversion exceptions are raised during
+ the call to ``__init__()``.
+ """
+ # pylint: disable=too-many-ancestors
+
+ def __init__(self,
+ value: Union[bytes, Mapping[str, object]] = b'{}', *,
+ eager: bool = True):
+ self._data: Optional[bytes] = None
+ self._obj: Optional[Dict[str, object]] = None
+
+ if isinstance(value, bytes):
+ self._data = value
+ if eager:
+ self._obj = self._deserialize(self._data)
+ else:
+ self._obj = dict(value)
+ if eager:
+ self._data = self._serialize(self._obj)
+
+ # Methods necessary to implement the MutableMapping interface, see:
+ #
https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping
+
+ # We get pop, popitem, clear, update, setdefault, __contains__,
+ # keys, items, values, get, __eq__ and __ne__ for free.
+
+ def __getitem__(self, key: str) -> object:
+ return self._object[key]
+
+ def __setitem__(self, key: str, value: object) -> None:
+ self._object[key] = value
+ self._data = None
+
+ def __delitem__(self, key: str) -> None:
+ del self._object[key]
+ self._data = None
+
+ def __iter__(self) -> Iterator[str]:
+ return iter(self._object)
+
+ def __len__(self) -> int:
+ return len(self._object)
+
+ # Dunder methods not related to MutableMapping:
+
+ def __repr__(self) -> str:
+ if self._obj is not None:
+ return f"Message({self._object!r})"
+ return f"Message({bytes(self)!r})"
+
+ def __str__(self) -> str:
+ """Pretty-printed representation of this QMP message."""
+ return json.dumps(self._object, indent=2)
+
+ def __bytes__(self) -> bytes:
+ """bytes representing this QMP message."""
+ if self._data is None:
+ self._data = self._serialize(self._obj or {})
+ return self._data
+
+ # Conversion Methods
+
+ @property
+ def _object(self) -> Dict[str, object]:
+ """
+ A `dict` representing this QMP message.
+
+ Generated on-demand, if required. This property is private
+ because it returns an object that could be used to invalidate
+ the internal state of the `Message` object.
+ """
+ if self._obj is None:
+ self._obj = self._deserialize(self._data or b'{}')
+ return self._obj
+
+ @classmethod
+ def _serialize(cls, value: object) -> bytes:
+ """
+ Serialize a JSON object as `bytes`.
+
+ :raise ValueError: When the object cannot be serialized.
+ :raise TypeError: When the object cannot be serialized.
+
+ :return: `bytes` ready to be sent over the wire.
+ """
+ return json.dumps(value, separators=(',', ':')).encode('utf-8')
+
+ @classmethod
+ def _deserialize(cls, data: bytes) -> Dict[str, object]:
+ """
+ Deserialize JSON `bytes` into a native Python `dict`.
+
+ :raise DeserializationError:
+ If JSON deserialization fails for any reason.
+ :raise UnexpectedTypeError:
+ If the data does not represent a JSON object.
+
+ :return: A `dict` representing this QMP message.
+ """
+ try:
+ obj = json.loads(data)
+ except JSONDecodeError as err:
+ emsg = "Failed to deserialize QMP message."
+ raise DeserializationError(emsg, data) from err
+ if not isinstance(obj, dict):
+ raise UnexpectedTypeError(
+ "QMP message is not a JSON object.",
+ obj
+ )
+ return obj
+
+
+class DeserializationError(ProtocolError):
+ """
+ A QMP message was not understood as JSON.
+
+ When this Exception is raised, ``__cause__`` will be set to the
+ `json.JSONDecodeError` Exception, which can be interrogated for
+ further details.
+
+ :param error_message: Human-readable string describing the error.
+ :param raw: The raw `bytes` that prompted the failure.
+ """
+ def __init__(self, error_message: str, raw: bytes):
+ super().__init__(error_message)
+ #: The raw `bytes` that were not understood as JSON.
+ self.raw: bytes = raw
+
+ def __str__(self) -> str:
+ return "\n".join([
+ super().__str__(),
+ f" raw bytes were: {str(self.raw)}",
+ ])
+
+
+class UnexpectedTypeError(ProtocolError):
+ """
+ A QMP message was JSON, but not a JSON object.
+
+ :param error_message: Human-readable string describing the error.
+ :param value: The deserialized JSON value that wasn't an object.
+ """
+ def __init__(self, error_message: str, value: object):
+ super().__init__(error_message)
+ #: The JSON value that was expected to be an object.
+ self.value: object = value
+
+ def __str__(self) -> str:
+ strval = json.dumps(self.value, indent=2)
+ return "\n".join([
+ super().__str__(),
+ f" json value was: {strval}",
+ ])
--
2.31.1
- [PULL 02/32] python/aqmp: add error classes, (continued)
- [PULL 02/32] python/aqmp: add error classes, John Snow, 2021/09/27
- [PULL 04/32] python/aqmp: add asyncio compatibility wrappers, John Snow, 2021/09/27
- [PULL 03/32] python/pylint: Add exception for TypeVar names ('T'), John Snow, 2021/09/27
- [PULL 07/32] python/aqmp: Add logging utility helpers, John Snow, 2021/09/27
- [PULL 05/32] python/aqmp: add generic async message-based protocol support, John Snow, 2021/09/27
- [PULL 06/32] python/aqmp: add runstate state machine to AsyncProtocol, John Snow, 2021/09/27
- [PULL 08/32] python/aqmp: add logging to AsyncProtocol, John Snow, 2021/09/27
- [PULL 10/32] python/aqmp: add configurable read buffer limit, John Snow, 2021/09/27
- [PULL 11/32] python/aqmp: add _cb_inbound and _cb_outbound logging hooks, John Snow, 2021/09/27
- [PULL 12/32] python/aqmp: add AsyncProtocol._readline() method, John Snow, 2021/09/27
- [PULL 13/32] python/aqmp: add QMP Message format,
John Snow <=
- [PULL 14/32] python/aqmp: add well-known QMP object models, John Snow, 2021/09/27
- [PULL 15/32] python/aqmp: add QMP event support, John Snow, 2021/09/27
- [PULL 16/32] python/pylint: disable too-many-function-args, John Snow, 2021/09/27
- [PULL 17/32] python/aqmp: add QMP protocol support, John Snow, 2021/09/27
- [PULL 18/32] python/pylint: disable no-member check, John Snow, 2021/09/27
- [PULL 19/32] python/aqmp: Add message routing to QMP protocol, John Snow, 2021/09/27
- [PULL 21/32] python/aqmp: add _raw() execution interface, John Snow, 2021/09/27
- [PULL 20/32] python/aqmp: add execute() interfaces, John Snow, 2021/09/27
- [PULL 22/32] python/aqmp: add asyncio_run compatibility wrapper, John Snow, 2021/09/27
- [PULL 23/32] python/aqmp: add scary message, John Snow, 2021/09/27