QMP Messages

QMP Message Format

This module provides the Message class, which represents a single QMP message sent to or from the server.

class qemu.qmp.message.Message(value: bytes | Mapping[str, object] = b'{}', *, eager: bool = True)[source]

Bases: MutableMapping[str, object]

Represents a single QMP protocol message.

QMP uses JSON objects as its basic communicative unit; so this Python object is a 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'}

Or pretty-printed:

>>> print(str(msg))
{
  "hello": "world"
}

Parameters:

value – Initial value, if any.
eager – When True, attempt to serialize or deserialize the initial value immediately, so that conversion exceptions are raised during the call to __init__().

exception qemu.qmp.message.DeserializationError(error_message: str, raw: bytes)[source]

Bases: 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.

Parameters:

error_message – Human-readable string describing the error.
raw – The raw bytes that prompted the failure.

raw: bytes: The raw bytes that were not understood as JSON.

exception qemu.qmp.message.UnexpectedTypeError(error_message: str, value: object)[source]

Bases: ProtocolError

A QMP message was JSON, but not a JSON object.

Parameters:

error_message – Human-readable string describing the error.
value – The deserialized JSON value that wasn’t an object.

value: object: The JSON value that was expected to be an object.

QMP Data Models

QMP Data Models

This module provides simplistic data classes that represent the few structures that the QMP spec mandates; they are used to verify incoming data to make sure it conforms to spec.

class qemu.qmp.models.Model(raw: Mapping[str, Any])[source]

Bases: object

Abstract data model, representing some QMP object of some kind.

Parameters:

raw – The raw object to be validated.

Raises:

KeyError – If any required fields are absent.
TypeError – If any required fields have the wrong type.

class qemu.qmp.models.Greeting(raw: Mapping[str, Any])[source]

Bases: Model

Defined in interop/qmp-spec, “Server Greeting” section.

Parameters:

raw – The raw Greeting object.

Raises:

KeyError – If any required fields are absent.
TypeError – If any required fields have the wrong type.

QMP: QMPGreeting: ‘QMP’ member

class qemu.qmp.models.QMPGreeting(raw: Mapping[str, Any])[source]

Bases: Model

Defined in interop/qmp-spec, “Server Greeting” section.

Parameters:

raw – The raw QMPGreeting object.

Raises:

KeyError – If any required fields are absent.
TypeError – If any required fields have the wrong type.

version: Mapping[str, object]: ‘version’ member

capabilities: Sequence[object]: ‘capabilities’ member

class qemu.qmp.models.ErrorResponse(raw: Mapping[str, Any])[source]

Bases: Model

Defined in interop/qmp-spec, “Error” section.

Parameters:

raw – The raw ErrorResponse object.

Raises:

KeyError – If any required fields are absent.
TypeError – If any required fields have the wrong type.

error: ErrorInfo: ‘error’ member

id: object | None: ‘id’ member

class qemu.qmp.models.ErrorInfo(raw: Mapping[str, Any])[source]

Bases: Model

Defined in interop/qmp-spec, “Error” section.

Parameters:

raw – The raw ErrorInfo object.

Raises:

KeyError – If any required fields are absent.
TypeError – If any required fields have the wrong type.

class_: str: ‘class’ member, with an underscore to avoid conflicts in Python.

desc: str: ‘desc’ member