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

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 5319 bytes --]

On Fri, Apr 1, 2022, 12:40 PM Kashyap Chamarthy <kchamart@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 <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.)
>

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 <kchamart@redhat.com>


Thanks for your review prior to sending, and thanks for your re-review here
🙂


>
> [...]
>
>
> --
> /kashyap
>
>

[-- Attachment #2: Type: text/html, Size: 8015 bytes --]