maqet 0.0.1.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

qemu/qmp/legacy.py

@@ -1,319 +0,0 @@
-"""
-(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.
-"""
-
-#
-# Copyright (C) 2009-2022 Red Hat Inc.
-#
-# Authors:
-#  Luiz Capitulino <lcapitulino@redhat.com>
-#  John Snow <jsnow@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
-import socket
-from types import TracebackType
-from typing import (
-    Any,
-    Awaitable,
-    Dict,
-    List,
-    Optional,
-    Type,
-    TypeVar,
-    Union,
-)
-
-from .error import QMPError
-from .protocol import Runstate, SocketAddrT
-from .qmp_client import QMPClient
-
-
-#: QMPMessage is an entire QMP message of any kind.
-QMPMessage = Dict[str, Any]
-
-#: QMPReturnValue is the 'return' value of a command.
-QMPReturnValue = object
-
-#: QMPObject is any object in a QMP message.
-QMPObject = Dict[str, object]
-
-# QMPMessage can be outgoing commands or incoming events/returns.
-# QMPReturnValue is usually a dict/json object, but due to QAPI's
-# 'command-returns-exceptions', it can actually be anything.
-#
-# {'return': {}} is a QMPMessage,
-# {} is the QMPReturnValue.
-
-
-class QMPBadPortError(QMPError):
-    """
-    Unable to parse socket address: Port was non-numerical.
-    """
-
-
-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 a unix socket path (string), a tuple
-                     in the form ( address, port ) for a TCP connection, or an
-                     existing `socket.socket` object.
-    :param server:   Act as the socket server. (See 'accept')
-                     Not applicable when passing a socket directly.
-    :param nickname: Optional nickname used for logging.
-    """
-
-    def __init__(self,
-                 address: Union[SocketAddrT, socket.socket],
-                 server: bool = False,
-                 nickname: Optional[str] = None):
-
-        if server and isinstance(address, socket.socket):
-            raise ValueError(
-                "server argument should be False when passing a socket")
-
-        self._qmp = QMPClient(nickname)
-        self._aloop = asyncio.get_event_loop()
-        self._address = address
-        self._timeout: Optional[float] = None
-
-        if server:
-            assert not isinstance(self._address, socket.socket)
-            self._sync(self._qmp.start_server(self._address))
-
-    _T = TypeVar('_T')
-
-    def _sync(
-            self, future: Awaitable[_T], timeout: Optional[float] = None
-    ) -> _T:
-        return self._aloop.run_until_complete(
-            asyncio.wait_for(future, timeout=timeout)
-        )
-
-    def _get_greeting(self) -> Optional[QMPMessage]:
-        if self._qmp.greeting is not None:
-            # pylint: disable=protected-access
-            return self._qmp.greeting._asdict()
-        return None
-
-    def __enter__(self: _T) -> _T:
-        # Implement context manager enter function.
-        return self
-
-    def __exit__(self,
-                 exc_type: Optional[Type[BaseException]],
-                 exc_val: Optional[BaseException],
-                 exc_tb: Optional[TracebackType]) -> None:
-        # Implement context manager exit function.
-        self.close()
-
-    @classmethod
-    def parse_address(cls, address: str) -> SocketAddrT:
-        """
-        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.
-        """
-        components = address.split(':')
-        if len(components) == 2:
-            try:
-                port = int(components[1])
-            except ValueError:
-                msg = f"Bad port: '{components[1]}' in '{address}'."
-                raise QMPBadPortError(msg) from None
-            return (components[0], port)
-
-        # Treat as filepath.
-        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._qmp.await_greeting = negotiate
-        self._qmp.negotiate = negotiate
-
-        self._sync(
-            self._qmp.connect(self._address)
-        )
-        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._qmp.await_greeting = True
-        self._qmp.negotiate = True
-
-        self._sync(self._qmp.accept(), timeout)
-
-        ret = self._get_greeting()
-        assert ret is not None
-        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
-
-                # _raw() isn't a public API, because turning off
-                # automatic ID assignment is discouraged. For
-                # compatibility with iotests *only*, do it anyway.
-                self._qmp._raw(qmp_cmd, assign_id=False),
-                self._timeout
-            )
-        )
-
-    def cmd_raw(self, name: str,
-                args: Optional[Dict[str, object]] = None) -> QMPMessage:
-        """
-        Build a QMP command and send it to the QMP Monitor.
-
-        :param name: command name (string)
-        :param args: command arguments (dict)
-        """
-        qmp_cmd: QMPMessage = {'execute': name}
-        if args:
-            qmp_cmd['arguments'] = args
-        return self.cmd_obj(qmp_cmd)
-
-    def cmd(self, cmd: str, **kwds: object) -> QMPReturnValue:
-        """
-        Build and send a QMP command to the monitor, report errors if any
-        """
-        return self._sync(
-            self._qmp.execute(cmd, kwds),
-            self._timeout
-        )
-
-    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._qmp.events.empty():
-                return None
-
-        # If wait is 'True', wait forever. If wait is False/0, the events
-        # queue must not be empty; but it still needs some real amount
-        # of time to complete.
-        timeout = None
-        if wait and isinstance(wait, float):
-            timeout = wait
-
-        return dict(
-            self._sync(
-                self._qmp.events.get(),
-                timeout
-            )
-        )
-
-    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._qmp.events.clear()]
-        if events:
-            return events
-
-        event = self.pull_event(wait)
-        return [event] if event is not None else []
-
-    def clear_events(self) -> None:
-        """Clear current list of pending events."""
-        self._qmp.events.clear()
-
-    def close(self) -> None:
-        """Close the connection."""
-        self._sync(
-            self._qmp.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._qmp.send_fd_scm(fd)
-
-    def __del__(self) -> None:
-        if self._qmp.runstate == Runstate.IDLE:
-            return
-
-        if not self._aloop.is_running():
-            self.close()
-        else:
-            # Garbage collection ran while the event loop was running.
-            # Nothing we can do about it now, but if we don't raise our
-            # own error, the user will be treated to a lot of traceback
-            # they might not understand.
-            raise QMPError(
-                "QEMUMonitorProtocol.close()"
-                " was not called before object was garbage collected"
-            )

qemu/qmp/message.py

@@ -1,209 +0,0 @@
-"""
-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}",
-        ])

qemu/qmp/models.py

@@ -1,146 +0,0 @@
-"""
-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.
-"""
-# pylint: disable=too-few-public-methods
-
-from collections import abc
-import copy
-from typing import (
-    Any,
-    Dict,
-    Mapping,
-    Optional,
-    Sequence,
-)
-
-
-class Model:
-    """
-    Abstract data model, representing some QMP object of some kind.
-
-    :param raw: The raw object to be validated.
-    :raise KeyError: If any required fields are absent.
-    :raise TypeError: If any required fields have the wrong type.
-    """
-    def __init__(self, raw: Mapping[str, Any]):
-        self._raw = raw
-
-    def _check_key(self, key: str) -> None:
-        if key not in self._raw:
-            raise KeyError(f"'{self._name}' object requires '{key}' member")
-
-    def _check_value(self, key: str, type_: type, typestr: str) -> None:
-        assert key in self._raw
-        if not isinstance(self._raw[key], type_):
-            raise TypeError(
-                f"'{self._name}' member '{key}' must be a {typestr}"
-            )
-
-    def _check_member(self, key: str, type_: type, typestr: str) -> None:
-        self._check_key(key)
-        self._check_value(key, type_, typestr)
-
-    @property
-    def _name(self) -> str:
-        return type(self).__name__
-
-    def __repr__(self) -> str:
-        return f"{self._name}({self._raw!r})"
-
-
-class Greeting(Model):
-    """
-    Defined in qmp-spec.rst, section "Server Greeting".
-
-    :param raw: The raw Greeting object.
-    :raise KeyError: If any required fields are absent.
-    :raise TypeError: If any required fields have the wrong type.
-    """
-    def __init__(self, raw: Mapping[str, Any]):
-        super().__init__(raw)
-        #: 'QMP' member
-        self.QMP: QMPGreeting  # pylint: disable=invalid-name
-
-        self._check_member('QMP', abc.Mapping, "JSON object")
-        self.QMP = QMPGreeting(self._raw['QMP'])
-
-    def _asdict(self) -> Dict[str, object]:
-        """
-        For compatibility with the iotests sync QMP wrapper.
-
-        The legacy QMP interface needs Greetings as a garden-variety Dict.
-
-        This interface is private in the hopes that it will be able to
-        be dropped again in the near-future. Caller beware!
-        """
-        return dict(copy.deepcopy(self._raw))
-
-
-class QMPGreeting(Model):
-    """
-    Defined in qmp-spec.rst, section "Server Greeting".
-
-    :param raw: The raw QMPGreeting object.
-    :raise KeyError: If any required fields are absent.
-    :raise TypeError: If any required fields have the wrong type.
-    """
-    def __init__(self, raw: Mapping[str, Any]):
-        super().__init__(raw)
-        #: 'version' member
-        self.version: Mapping[str, object]
-        #: 'capabilities' member
-        self.capabilities: Sequence[object]
-
-        self._check_member('version', abc.Mapping, "JSON object")
-        self.version = self._raw['version']
-
-        self._check_member('capabilities', abc.Sequence, "JSON array")
-        self.capabilities = self._raw['capabilities']
-
-
-class ErrorResponse(Model):
-    """
-    Defined in qmp-spec.rst, section "Error".
-
-    :param raw: The raw ErrorResponse object.
-    :raise KeyError: If any required fields are absent.
-    :raise TypeError: If any required fields have the wrong type.
-    """
-    def __init__(self, raw: Mapping[str, Any]):
-        super().__init__(raw)
-        #: 'error' member
-        self.error: ErrorInfo
-        #: 'id' member
-        self.id: Optional[object] = None  # pylint: disable=invalid-name
-
-        self._check_member('error', abc.Mapping, "JSON object")
-        self.error = ErrorInfo(self._raw['error'])
-
-        if 'id' in raw:
-            self.id = raw['id']
-
-
-class ErrorInfo(Model):
-    """
-    Defined in qmp-spec.rst, section "Error".
-
-    :param raw: The raw ErrorInfo object.
-    :raise KeyError: If any required fields are absent.
-    :raise TypeError: If any required fields have the wrong type.
-    """
-    def __init__(self, raw: Mapping[str, Any]):
-        super().__init__(raw)
-        #: 'class' member, with an underscore to avoid conflicts in Python.
-        self.class_: str
-        #: 'desc' member
-        self.desc: str
-
-        self._check_member('class', str, "string")
-        self.class_ = self._raw['class']
-
-        self._check_member('desc', str, "string")
-        self.desc = self._raw['desc']