On Fri, Apr 1, 2022, 12:40 PM Kashyap Chamarthy <kcham...@redhat.com> wrote:
> 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.) > OK. it's tough: there's a dual audience in mind here. People who are familiar with Python development and QEMU devs who are not! A link would suffice, but how to install, develop, and use python packages can get a little complex. Longer than a paragraph, anyway. Hard to know which complexities to omit and which to front-load. ¯\_(ツ)_/¯ > FWIW: > > Reviewed-by: Kashyap Chamarthy <kcham...@redhat.com> Thanks for your review prior to sending, and thanks for your re-review here 🙂 > > [...] > > > -- > /kashyap > >
