Legacy API

(Legacy) Sync QMP Wrapper

This module provides the QEMUMonitorProtocol class, which is a synchronous wrapper around QMPClient.

Its design closely resembles that of the original QEMUMonitorProtocol class, originally written by Luiz Capitulino. It is provided here for compatibility with scripts inside the QEMU source tree that expect the old interface.

class qemu.qmp.legacy.QEMUMonitorProtocol(address: Union[str, Tuple[str, int]], server: bool = False, nickname: Optional[str] = None)[source]

Bases: object

Provide an API to connect to QEMU via QEMU Monitor Protocol (QMP) and then allow to handle commands and events.

Parameters
  • address – QEMU address, can be either a unix socket path (string) or a tuple in the form ( address, port ) for a TCP connection

  • server – Act as the socket server. (See ‘accept’)

  • nickname – Optional nickname used for logging.

accept(timeout: Optional[float] = 15.0) → Dict[str, Any][source]

Await connection from QMP Monitor and perform capabilities negotiation.

Parameters

timeout – timeout in seconds (nonnegative float number, or None). If None, there is no timeout, and this may block forever.

Returns

QMP greeting dict

Raises

ConnectError – on connection errors

clear_events() → None[source]

Clear current list of pending events.

close() → None[source]

Close the connection.

cmd(name: str, args: Optional[Dict[str, object]] = None, cmd_id: Optional[object] = None) → Dict[str, Any][source]

Build a QMP command and send it to the QMP Monitor.

Parameters
  • name – command name (string)

  • args – command arguments (dict)

  • cmd_id – command id (dict, list, string or int)

cmd_obj(qmp_cmd: Dict[str, Any]) → Dict[str, Any][source]

Send a QMP command to the QMP Monitor.

Parameters

qmp_cmd – QMP command to be sent as a Python dict

Returns

QMP response as a Python dict

command(cmd: str, **kwds: object) → object[source]

Build and send a QMP command to the monitor, report errors if any

connect(negotiate: bool = True) → Optional[Dict[str, Any]][source]

Connect to the QMP Monitor and perform capabilities negotiation.

Returns

QMP greeting dict, or None if negotiate is false

Raises

ConnectError – on connection errors

get_events(wait: Union[bool, float] = False) → List[Dict[str, Any]][source]

Get a list of QMP events and clear all pending events.

Parameters

wait – If False or 0, do not wait. Return None if no events ready. If True, wait until we have at least one event. Otherwise, wait for up to the specified number of seconds for at least one event.

Raises

asyncio.TimeoutError – When a timeout is requested and the timeout period elapses.

Returns

A list of QMP events.

classmethod parse_address(address: str) → Union[str, Tuple[str, int]][source]

Parse a string into a QMP address.

Figure out if the argument is in the port:host form. If it’s not, it’s probably a file path.

pull_event(wait: Union[bool, float] = False) → Optional[Dict[str, Any]][source]

Pulls a single event.

Parameters

wait – If False or 0, do not wait. Return None if no events ready. If True, wait forever until the next event. Otherwise, wait for the specified number of seconds.

Raises

asyncio.TimeoutError – When a timeout is requested and the timeout period elapses.

Returns

The first available QMP event, or None.

send_fd_scm(fd: int) → None[source]

Send a file descriptor to the remote via SCM_RIGHTS.

settimeout(timeout: Optional[float]) → None[source]

Set the timeout for QMP RPC execution.

This timeout affects the cmd, cmd_obj, and command methods. The accept, pull_event and get_events methods have their own configurable timeouts.

Parameters

timeout – timeout in seconds, or None. None will wait indefinitely.

exception qemu.qmp.legacy.QMPBadPortError[source]

Bases: qemu.qmp.error.QMPError

Unable to parse socket address: Port was non-numerical.

qemu.qmp.legacy.QMPMessage

QMPMessage is an entire QMP message of any kind.

alias of Dict[str, Any]

qemu.qmp.legacy.QMPObject

QMPObject is any object in a QMP message.

alias of Dict[str, object]

qemu.qmp.legacy.QMPReturnValue

alias of object