On Wed, Mar 30, 2022 at 02:24:20PM -0400, John Snow wrote: > The README here will reflect both what is shown on GitLab and on the > PyPI landing page. Update it accordingly, and freshen it up. > > FIXME: Update URLs when pushing to the production repo. > > Suggested-by: Kashyap Chamarthy <kcham...@redhat.com> > Signed-off-by: John Snow <js...@redhat.com> > ---
Hi, This version reads good to me. :) [...] > + > +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 <https://libvirt.org/>`_, `virt-manager > +<https://virt-manager.org/>`_, `GNOME Boxes > +<https://wiki.gnome.org/Apps/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()) Tested the exmaple; this works! > +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 > +<https://jsnow.gitlab.io/qemu.qmp/>`_ 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 <https://gitlab.com/jsnow/qemu.qmp/-/issues>`_. 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 > + <https://gitlab.com/jsnow/qemu.qmp/-/issues>`_. This helps with > + generating Changelog text and staying organized. Thank you 🙇 /me didn't miss the Japanese bow. > +Developing > +^^^^^^^^^^ > + > +Optional packages necessary for running code quality analysis for this > +package can be installed with the optional dependency group "devel": > +``pip install qemu.qmp[devel]``. > + > +``make develop`` can be used to install this package in editable mode > +(to the current environment) *and* bring in testing dependencies in one > +command. > + > +``make check`` can be used to run the available tests. Consult ``make > +help`` for other targets and tests that make sense for different > +occasions. > + > +Before submitting a pull request, consider running ``make check-tox && > +make check-pipenv`` locally to spot any issues that will cause the CI to > +fail. These checks use their own virtual environments and won't pollute > +your working space. Nit: Consider hyper-linking "virtual environments" to: https://docs.python.org/3/library/venv.html#module-venv (I realize, within context people will recognize the term "virtual environment" is not a virtual guest environment, but a Python venv. I have a mild preference for being explicit here.) FWIW: Reviewed-by: Kashyap Chamarthy <kcham...@redhat.com> [...] -- /kashyap
