Copy the docstrings out of qemu.qmp, adjusting them as necessary to
more accurately reflect the current state of this class.
Signed-off-by: John Snow <js...@redhat.com>
---
python/qemu/aqmp/legacy.py | 110 ++++++++++++++++++++++++++++++++++---
1 file changed, 102 insertions(+), 8 deletions(-)
diff --git a/python/qemu/aqmp/legacy.py b/python/qemu/aqmp/legacy.py
index 71f3d378db..5f7955ac5d 100644
--- a/python/qemu/aqmp/legacy.py
+++ b/python/qemu/aqmp/legacy.py
@@ -1,9 +1,23 @@
"""
-Sync QMP Wrapper
+(Legacy) Sync QMP Wrapper
-This class pretends to be qemu.qmp.QEMUMonitorProtocol.
+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.
"""
+# Copyright (C) 2009, 2010, 2021 Red Hat Inc.
+#
+# Authors:
+# Luiz Capitulino <lcapitul...@redhat.com>
+# John Snow <js...@redhat.com>
+#
+# This work is licensed under the terms of the GNU GPL, version 2.
+# See the COPYING file in the top-level directory.
+
+
import asyncio
from types import TracebackType
from typing import (
@@ -39,9 +53,6 @@
# {} is the QMPReturnValue.
-# pylint: disable=missing-docstring
-
-
class QMPBadPortError(AQMPError):
"""
Unable to parse socket address: Port was non-numerical.
@@ -49,6 +60,21 @@ class QMPBadPortError(AQMPError):
class QEMUMonitorProtocol:
+ """
+ Provide an API to connect to QEMU via QEMU Monitor Protocol (QMP)
+ and then allow to handle commands and events.
+
+ :param address: QEMU address, can be either a unix socket path (string)
+ or a tuple in the form ( address, port ) for a TCP
+ connection
+ :param server: Deprecated, ignored. (See 'accept')
+ :param nickname: Optional nickname used for logging.
+
+ ..note::
+ No connection is established during `__init__`, this is done by
+ the `connect()` or `accept()` methods.
+ """
+
def __init__(self, address: SocketAddrT,
server: bool = False, # pylint: disable=unused-argument
nickname: Optional[str] = None):
@@ -108,6 +134,12 @@ def parse_address(cls, address: str) -> SocketAddrT:
return address
def connect(self, negotiate: bool = True) -> Optional[QMPMessage]:
+ """
+ Connect to the QMP Monitor and perform capabilities negotiation.
+
+ :return: QMP greeting dict, or None if negotiate is false
+ :raise ConnectError: on connection errors
+ """
self._aqmp.await_greeting = negotiate
self._aqmp.negotiate = negotiate
@@ -117,6 +149,16 @@ def connect(self, negotiate: bool = True) ->
Optional[QMPMessage]:
return self._get_greeting()
def accept(self, timeout: Optional[float] = 15.0) -> QMPMessage:
+ """
+ Await connection from QMP Monitor and perform capabilities negotiation.
+
+ :param timeout:
+ timeout in seconds (nonnegative float number, or None).
+ If None, there is no timeout, and this may block forever.
+
+ :return: QMP greeting dict
+ :raise ConnectError: on connection errors
+ """
self._aqmp.await_greeting = True
self._aqmp.negotiate = True
@@ -130,6 +172,12 @@ def accept(self, timeout: Optional[float] = 15.0) ->
QMPMessage:
return ret
def cmd_obj(self, qmp_cmd: QMPMessage) -> QMPMessage:
+ """
+ Send a QMP command to the QMP Monitor.
+
+ :param qmp_cmd: QMP command to be sent as a Python dict
+ :return: QMP response as a Python dict
+ """
return dict(
self._sync(
# pylint: disable=protected-access
@@ -148,9 +196,9 @@ def cmd(self, name: str,
"""
Build a QMP command and send it to the QMP Monitor.
- @param name: command name (string)
- @param args: command arguments (dict)
- @param cmd_id: command id (dict, list, string or int)
+ :param name: command name (string)
+ :param args: command arguments (dict)
+ :param cmd_id: command id (dict, list, string or int)
"""
qmp_cmd: QMPMessage = {'execute': name}
if args:
@@ -160,6 +208,9 @@ def cmd(self, name: str,
return self.cmd_obj(qmp_cmd)
def command(self, cmd: str, **kwds: object) -> QMPReturnValue:
+ """
+ Build and send a QMP command to the monitor, report errors if any
+ """
return self._sync(
self._aqmp.execute(cmd, kwds),
self._timeout
@@ -167,6 +218,19 @@ def command(self, cmd: str, **kwds: object) ->
QMPReturnValue:
def pull_event(self,
wait: Union[bool, float] = False) -> Optional[QMPMessage]:
+ """
+ Pulls a single event.
+
+ :param 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.
+
+ :raise asyncio.TimeoutError:
+ When a timeout is requested and the timeout period elapses.
+
+ :return: The first available QMP event, or None.
+ """
if not wait:
# wait is False/0: "do not wait, do not except."
if self._aqmp.events.empty():
@@ -187,6 +251,20 @@ def pull_event(self,
)
def get_events(self, wait: Union[bool, float] = False) -> List[QMPMessage]:
+ """
+ Get a list of QMP events and clear all pending events.
+
+ :param 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.
+
+ :raise asyncio.TimeoutError:
+ When a timeout is requested and the timeout period elapses.
+
+ :return: A list of QMP events.
+ """
events = [dict(x) for x in self._aqmp.events.clear()]
if events:
return events
@@ -195,17 +273,33 @@ def get_events(self, wait: Union[bool, float] = False) ->
List[QMPMessage]:
return [event] if event is not None else []
def clear_events(self) -> None:
+ """Clear current list of pending events."""
self._aqmp.events.clear()
def close(self) -> None:
+ """Close the connection."""
self._sync(
self._aqmp.disconnect()
)
def settimeout(self, timeout: Optional[float]) -> None:
+ """
+ Set the timeout for QMP RPC execution.
+
+ This timeout affects the `cmd`, `cmd_obj`, and `command` methods.
+ The `accept`, `pull_event` and `get_event` methods have their
+ own configurable timeouts.
+
+ :param timeout:
+ timeout in seconds, or None.
+ None will wait indefinitely.
+ """
self._timeout = timeout
def send_fd_scm(self, fd: int) -> None:
+ """
+ Send a file descriptor to the remote via SCM_RIGHTS.
+ """
self._aqmp.send_fd_scm(fd)
def __del__(self) -> None:
--
2.31.1
