qemu.qmp 0.0.6

Who is this library for?

It is firstly for developers of QEMU themselves; as the test infrastructure of QEMU itself needs a convenient and scriptable interface for testing QEMU. This library was split out of the QEMU source tree in order to share a reference version of a QMP library that was usable both within and outside of the QEMU source tree.

Second, it’s for those who are developing for QEMU by adding new architectures, devices, or functionality; as well as targeting those who are developing with QEMU, i.e. developers working on integrating QEMU features into other projects such as libvirt, KubeVirt, Kata Containers, etc. Occasionally, using existing virtual-machine (VM) management stacks that integrate QEMU+KVM can make developing, testing, and debugging features difficult. In these cases, having more ‘raw’ access to QEMU is beneficial. This library is for you.

Lastly, it’s for power users who already use QEMU directly without the aid of libvirt because they require the raw control and power this affords them.

Who isn’t this library for?

It is not designed for anyone looking for a turn-key solution for VM management. QEMU is a low-level component that resembles a particularly impressive Swiss Army knife. This library does not manage that complexity and is largely “VM-ignorant”. It’s not a replacement for projects like libvirt, virt-manager, GNOME Boxes, etc.

Installing

This package can be installed from PyPI with pip:

> pip3 install qemu.qmp

Usage

Launch QEMU with a monitor, e.g.:

> qemu-system-x86_64 -qmp unix:qmp.sock,server=on,wait=off

Then, at its simplest, script-style usage looks like this:

import asyncio
from qemu.qmp import QMPClient

async def main():
    qmp = QMPClient('my-vm-nickname')
    await qmp.connect('qmp.sock')

    res = await qmp.execute('query-status')
    print(f"VM status: {res['status']}")

    await qmp.disconnect()

asyncio.run(main())

The above script will connect to the UNIX socket located at qmp.sock, query the VM’s runstate, then print it out to the terminal:

> python3 example.py
VM status: running

For more complex usages, especially those that make full advantage of monitoring asynchronous events, refer to the online documentation or type import qemu.qmp; help(qemu.qmp) in your Python terminal of choice.

Contributing

Contributions are quite welcome! Please file bugs using the GitLab issue tracker. This project will accept GitLab merge requests, but due to the close association with the QEMU project, there are some additional guidelines:

1. Please use the “Signed-off-by” tag in your commit messages. See https://wiki.linuxfoundation.org/dco for more information on this requirement.

2. This repository won’t squash merge requests into a single commit on pull; each commit should seek to be self-contained (within reason).

3. Owing to the above, each commit sent as part of a merge request should not introduce any temporary regressions, even if fixed later in the same merge request. This is done to preserve bisectability.

4. Please associate every merge request with at least one GitLab issue. This helps with generating Changelog text and staying organized. Thank you 🙇

Stability and Versioning

This package uses a major.minor.micro SemVer versioning, with the following additional semantics during the alpha/beta period (Major version 0):

This package treats 0.0.z versions as “alpha” versions. Each micro version update may change the API incompatibly. Early users are advised to pin against explicit versions, but check for updates often.

A planned 0.1.z version will introduce the first “beta”, whereafter each micro update will be backwards compatible, but each minor update will not be. The first beta version will be released after legacy.py is removed, and the API is tentatively “stable”.

Thereafter, normal SemVer / PEP440 rules will apply; micro updates will always be bugfixes, and minor updates will be reserved for backwards compatible feature changes.

Changelog