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
-
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.
-
settimeout
(timeout: Optional[float]) → None[source]¶ Set the timeout for QMP RPC execution.
This timeout affects the
cmd
,cmd_obj
, andcommand
methods. Theaccept
,pull_event
andget_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