Re: [qemu.qmp PATCH 09/13] [FIXME] move PACKAGE.rst to README.rst and update

[Kashyap Chamarthy <kchamart@redhat.com>]

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 <kchamart@redhat.com>
> Signed-off-by: John Snow <jsnow@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 <kchamart@redhat.com> 

[...]
 

-- 
/kashyap