[RFC qemu.qmp PATCH 00/24] Python: Fork qemu.qmp Python lib into independent repo

[RFC qemu.qmp PATCH 00/24] Python: Fork qemu.qmp Python lib into independent repo

[John Snow]

Hi, this series is part of an effort to publish the qemu.qmp package on
PyPI. It is the second of three series to complete this work:

    (1) Switch the new Async QMP library in to python/qemu/qmp
--> (2) Fork python/qemu/qmp out into its own repository,
        with updated GitLab CI/CD targets to build packages.
    (3) Update qemu.git to install qemu.qmp from PyPI,
        and then delete python/qemu/qmp.

This series is not meant to apply to qemu.git, rather -- it's the series
that performs the split and would apply to a brand new repository.

I am submitting it to the QEMU mailing list for these reasons:

(1) To more broadly announce my intentions, and as reference alongside
series #1 and #3 detailed above.

(2) To ask for permission to become the maintainer of a
'qemu-project/qemu.qmp' repository, where I would like to host this
subproject.

(3) To ask for review on the README.rst file which details my intended
contribution guidelines for this subproject.

(4) To ask for review on the .gitlab-ci.d/ files and other repo-level
CI/CD ephemera, including and especially the docs-building process.  I
think the generated docs are still ugly, and I'd like to upload them to
readthedocs, among other things -- hence the RFC quality of this series.

Some review/RFC notes:

- I use jsnow/qemu.qmp as the repo name throughout the series; that will
  have to be changed eventually, but for the purposes of prototyping, it
  was nicer to have a fully working series.

- I'm planning on using gitlab issues and MRs for the subproject.

- I plan to version this lib independently, starting at 0.0.1 for the
  initial public release and bumping only the micro version for every
  last release. I plan to bump the minor version once it hits a "beta"
  state. There will be no cross-versioning against QEMU. I don't plan to
  publish new releases during QEMU freezes.

- Check out a completed pipeline here:
  https://gitlab.com/jsnow/qemu.qmp/-/pipelines/430528258

  It offers build artifacts, junit xml artifacts and GitLab
  test-level-view into the avocado unit tests. The build container is
  uploaded to GitLab's container registry and can be used to reproduce
  potential build/packaging errors.

  Every pipeline will produce built python packages and upload them to
  the GitLab package repository, see
  https://gitlab.com/jsnow/qemu.qmp/-/packages

Known problems:

- Sphinx output is still subjectively ugly, with too many layers of
  nesting

- Docs are not yet uploaded anywhere (GitLab pages, readthedocs?)

- Tags on a commit trigger two pipelines; this causes one of the package
  builds to fail as the version number will be duplicated in this
  case. Not entirely sure how I want to fix this yet ...

~ Happy Holidays ~, --js.

John Snow (24):
  Fork qemu.qmp from qemu.git
  Update VERSION to 0.0.0a1
  Update maintainer metadata
  Update project description
  Update project URLs
  Move README.rst to INDEX.rst and update
  Move PACKAGE.rst to README.rst and update
  Update Pipfile.lock
  Remove sub-dependency pins from Pipfile
  Add build and test container to gitlab CI configuration
  Add package build step to GitLab CI
  GitLab CI: Add check-dco script
  GitLab CI: Add pipenv and tox tests
  GitLab CI: Add avocado junit XML output to tests
  GitLab CI: Publish python packages to GitLab package repo
  Add setuptools_scm package versioning
  Makefile: add build and publish targets
  add Sphinx documentation config stub
  python: configure sphinx
  python: adjust apidoc stubs
  Fix doc cross-reference regressions
  docs: add Makefile target
  docs: add doc build to GitLab CI build step
  v0.0.1

 .gitignore                     |   2 +-
 .gitlab-ci.d/build.yml         |  14 ++
 .gitlab-ci.d/check-dco.py      |  98 ++++++++++
 .gitlab-ci.d/containers.yml    |  28 +++
 .gitlab-ci.d/index.yml         |  14 ++
 .gitlab-ci.d/publish.yml       |  11 ++
 .gitlab-ci.d/python.Dockerfile |  35 ++++
 .gitlab-ci.d/test.yml          |  74 ++++++++
 .gitlab-ci.yml                 |   3 +
 INDEX.rst                      |  64 +++++++
 MANIFEST.in                    |   4 +-
 Makefile                       |  54 +++++-
 PACKAGE.rst                    |  43 -----
 Pipfile                        |   4 +-
 Pipfile.lock                   | 314 ++++++++++++++++++---------------
 README.rst                     | 219 ++++++++++++++---------
 VERSION                        |   1 -
 avocado.cfg                    |   7 +
 docs/Makefile                  |  20 +++
 docs/conf.py                   | 107 +++++++++++
 docs/index.rst                 |  21 +++
 docs/make.bat                  |  35 ++++
 docs/qemu.qmp.error.rst        |   8 +
 docs/qemu.qmp.events.rst       |   7 +
 docs/qemu.qmp.legacy.rst       |   7 +
 docs/qemu.qmp.message.rst      |   8 +
 docs/qemu.qmp.models.rst       |   8 +
 docs/qemu.qmp.protocol.rst     |   9 +
 docs/qemu.qmp.qmp_client.rst   |   8 +
 docs/qemu.qmp.rst              |  24 +++
 docs/qemu.qmp.util.rst         |   8 +
 qemu/qmp/legacy.py             |   4 +-
 setup.cfg                      |  41 ++---
 setup.py                       |  13 +-
 34 files changed, 1000 insertions(+), 317 deletions(-)
 create mode 100644 .gitlab-ci.d/build.yml
 create mode 100755 .gitlab-ci.d/check-dco.py
 create mode 100644 .gitlab-ci.d/containers.yml
 create mode 100644 .gitlab-ci.d/index.yml
 create mode 100644 .gitlab-ci.d/publish.yml
 create mode 100644 .gitlab-ci.d/python.Dockerfile
 create mode 100644 .gitlab-ci.d/test.yml
 create mode 100644 .gitlab-ci.yml
 create mode 100644 INDEX.rst
 delete mode 100644 PACKAGE.rst
 delete mode 100644 VERSION
 create mode 100644 docs/Makefile
 create mode 100644 docs/conf.py
 create mode 100644 docs/index.rst
 create mode 100644 docs/make.bat
 create mode 100644 docs/qemu.qmp.error.rst
 create mode 100644 docs/qemu.qmp.events.rst
 create mode 100644 docs/qemu.qmp.legacy.rst
 create mode 100644 docs/qemu.qmp.message.rst
 create mode 100644 docs/qemu.qmp.models.rst
 create mode 100644 docs/qemu.qmp.protocol.rst
 create mode 100644 docs/qemu.qmp.qmp_client.rst
 create mode 100644 docs/qemu.qmp.rst
 create mode 100644 docs/qemu.qmp.util.rst

-- 
2.31.1

[RFC qemu.qmp PATCH 01/24] Fork qemu.qmp from qemu.git

[John Snow]

Split python/ from qemu.git, using these commands:

> git subtree split -P python/ -b python-split-v2
> mkdir ~/src/tmp
> cd ~/src/tmp
> git clone --no-local --branch python-split-v2 --single-branch ~/src/qemu
> cd qemu
> git filter-repo --path qemu/machine/           \
                  --path qemu/utils/             \
                  --path tests/iotests-mypy.sh   \
                  --path tests/iotests-pylint.sh \
                  --invert-paths

This commit performs some minimum cleanup to reflect the deletion of the
other subpackages. It is not intended to be exhaustive, and further
edits are made in forthcoming commits.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitignore |  2 +-
 Makefile   | 16 ++++++++--------
 setup.cfg  | 24 +-----------------------
 setup.py   |  2 +-
 4 files changed, 11 insertions(+), 33 deletions(-)

diff --git a/.gitignore b/.gitignore
index 904f324..b071f02 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,7 +5,7 @@
 # python packaging
 build/
 dist/
-qemu.egg-info/
+qemu.qmp.egg-info/
 
 # editor config
 .idea/
diff --git a/Makefile b/Makefile
index 3334311..a2d2f2c 100644
--- a/Makefile
+++ b/Makefile
@@ -30,7 +30,7 @@ help:
 	@echo ""
 	@echo "make develop:"
 	@echo "    Install deps needed for for 'make check',"
-	@echo "    and install the qemu package in editable mode."
+	@echo "    and install the qemu.qmp package in editable mode."
 	@echo "    (Can be used in or outside of a venv.)"
 	@echo ""
 	@echo "make pipenv"
@@ -43,7 +43,7 @@ help:
 	@echo "    Remove package build output."
 	@echo ""
 	@echo "make distclean:"
-	@echo "    remove pipenv/venv files, qemu package forwarder,"
+	@echo "    remove pipenv/venv files, qemu.qmp package forwarder,"
 	@echo "    built distribution files, and everything from 'make clean'."
 	@echo ""
 	@echo -e "Have a nice day ^_^\n"
@@ -64,11 +64,11 @@ dev-venv: $(QEMU_VENV_DIR) $(QEMU_VENV_DIR)/bin/activate
 $(QEMU_VENV_DIR) $(QEMU_VENV_DIR)/bin/activate: setup.cfg
 	@echo "VENV $(QEMU_VENV_DIR)"
 	@python3 -m venv $(QEMU_VENV_DIR)
-	@(							\
-		echo "ACTIVATE $(QEMU_VENV_DIR)";		\
-		. $(QEMU_VENV_DIR)/bin/activate;		\
-		echo "INSTALL qemu[devel] $(QEMU_VENV_DIR)";	\
-		make develop 1>/dev/null;			\
+	@(								\
+		echo "ACTIVATE $(QEMU_VENV_DIR)";			\
+		. $(QEMU_VENV_DIR)/bin/activate;			\
+		echo "INSTALL qemu.qmp[devel] $(QEMU_VENV_DIR)";	\
+		make develop 1>/dev/null;				\
 	)
 	@touch $(QEMU_VENV_DIR)
 
@@ -106,6 +106,6 @@ clean:
 
 .PHONY: distclean
 distclean: clean
-	rm -rf qemu.egg-info/ .venv/ .tox/ $(QEMU_VENV_DIR) dist/
+	rm -rf qemu.qmp.egg-info/ .venv/ .tox/ $(QEMU_VENV_DIR) dist/
 	rm -f .coverage .coverage.*
 	rm -rf htmlcov/
diff --git a/setup.cfg b/setup.cfg
index 911ae02..9999bca 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,5 +1,5 @@
 [metadata]
-name = qemu
+name = qemu.qmp
 version = file:VERSION
 maintainer = QEMU Developer Team
 maintainer_email = qemu-devel@nongnu.org
@@ -25,8 +25,6 @@ classifiers =
 python_requires = >= 3.6
 packages =
     qemu.qmp
-    qemu.machine
-    qemu.utils
 
 [options.package_data]
 * = py.typed
@@ -38,7 +36,6 @@ packages =
 devel =
     avocado-framework >= 90.0
     flake8 >= 3.6.0
-    fusepy >= 2.0.4
     isort >= 5.1.2
     mypy >= 0.770
     pylint >= 2.8.0
@@ -47,10 +44,6 @@ devel =
     urwid-readline >= 0.13
     Pygments >= 2.9.0
 
-# Provides qom-fuse functionality
-fuse =
-    fusepy >= 2.0.4
-
 # AQMP TUI dependencies
 tui =
     urwid >= 2.1.2
@@ -59,13 +52,6 @@ tui =
 
 [options.entry_points]
 console_scripts =
-    qom = qemu.utils.qom:main
-    qom-set = qemu.utils.qom:QOMSet.entry_point
-    qom-get = qemu.utils.qom:QOMGet.entry_point
-    qom-list = qemu.utils.qom:QOMList.entry_point
-    qom-tree = qemu.utils.qom:QOMTree.entry_point
-    qom-fuse = qemu.utils.qom_fuse:QOMFuse.entry_point [fuse]
-    qemu-ga-client = qemu.utils.qemu_ga_client:main
     qmp-shell = qemu.qmp.qmp_shell:main
     aqmp-tui = qemu.qmp.aqmp_tui:main [tui]
 
@@ -79,19 +65,12 @@ python_version = 3.6
 warn_unused_configs = True
 namespace_packages = True
 
-[mypy-qemu.utils.qom_fuse]
-# fusepy has no type stubs:
-allow_subclassing_any = True
-
 [mypy-qemu.qmp.aqmp_tui]
 # urwid and urwid_readline have no type stubs:
 allow_subclassing_any = True
 
 # The following missing import directives are because these libraries do not
 # provide type stubs. Allow them on an as-needed basis for mypy.
-[mypy-fuse]
-ignore_missing_imports = True
-
 [mypy-urwid]
 ignore_missing_imports = True
 
@@ -160,7 +139,6 @@ skip_missing_interpreters = true
 allowlist_externals = make
 deps =
     .[devel]
-    .[fuse]  # Workaround to trigger tox venv rebuild
     .[tui]   # Workaround to trigger tox venv rebuild
 commands =
     make check
diff --git a/setup.py b/setup.py
index 2014f81..cb9b9b6 100755
--- a/setup.py
+++ b/setup.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-QEMU tooling installer script
+QEMU QMP library installer script
 Copyright (c) 2020-2021 John Snow for Red Hat, Inc.
 """
 
-- 
2.31.1

[RFC qemu.qmp PATCH 02/24] Update VERSION to 0.0.0a1

[John Snow]

qemu.qmp will be independently versioned, without regard to QMP
version. While the repo is being established here, set the version to
something impossibly low.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 VERSION | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/VERSION b/VERSION
index c19f3b8..7741e1a 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.6.1.0a1
+0.0.0a1
-- 
2.31.1

[RFC qemu.qmp PATCH 03/24] Update maintainer metadata

[John Snow]

I'm the primary author of this particular component; update the metadata
accordingly.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 setup.cfg | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/setup.cfg b/setup.cfg
index 9999bca..7cd8470 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,7 +1,9 @@
 [metadata]
 name = qemu.qmp
 version = file:VERSION
-maintainer = QEMU Developer Team
+author = John Snow
+author_email = jsnow@redhat.com
+maintainer = QEMU Project
 maintainer_email = qemu-devel@nongnu.org
 url = https://www.qemu.org/
 download_url = https://www.qemu.org/download/
-- 
2.31.1

[RFC qemu.qmp PATCH 04/24] Update project description

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 setup.cfg | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup.cfg b/setup.cfg
index 7cd8470..9946875 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -7,7 +7,7 @@ maintainer = QEMU Project
 maintainer_email = qemu-devel@nongnu.org
 url = https://www.qemu.org/
 download_url = https://www.qemu.org/download/
-description = QEMU Python Build, Debug and SDK tooling.
+description = QEMU Monitor Protocol library.
 long_description = file:PACKAGE.rst
 long_description_content_type = text/x-rst
 classifiers =
-- 
2.31.1

[RFC qemu.qmp PATCH 05/24] Update project URLs

[John Snow]

Point to this library's URLs instead of the entire project's.

FIXME: In development, the URLs here are jsnow/qemu.qmp. It is intended
that the production version that gets pushed to qemu-project/qemu.qmp
will use URLs that reflect that repository appropriately.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 setup.cfg | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/setup.cfg b/setup.cfg
index 9946875..0f14bda 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -5,8 +5,10 @@ author = John Snow
 author_email = jsnow@redhat.com
 maintainer = QEMU Project
 maintainer_email = qemu-devel@nongnu.org
-url = https://www.qemu.org/
-download_url = https://www.qemu.org/download/
+# NOTE: Remember to update the commit message when changing these URLs.
+url = https://gitlab.com/jsnow/qemu.qmp
+download_url = https://gitlab.com/jsnow/qemu.qmp/-/packages
+# NOTE: Remember to update the commit message when changing these URLs.
 description = QEMU Monitor Protocol library.
 long_description = file:PACKAGE.rst
 long_description_content_type = text/x-rst
-- 
2.31.1

[RFC qemu.qmp PATCH 06/24] Move README.rst to INDEX.rst and update

[John Snow]

The intent is to use README.rst as the new package-level readme that
will be bundled with the source; so move the old "git level readme" over
to INDEX.rst instead, and update it accordingly.

This is primarily here to just document and explain what all the little
bits and pieces of files in the root are and what they do. I find this
stuff helpful when I wander over into other projects, so I'd like to
extend the same courtesy.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 README.rst => INDEX.rst | 49 +++++++++++------------------------------
 MANIFEST.in             |  1 -
 2 files changed, 13 insertions(+), 37 deletions(-)
 rename README.rst => INDEX.rst (64%)

diff --git a/README.rst b/INDEX.rst
similarity index 64%
rename from README.rst
rename to INDEX.rst
index 9c1fcea..45b0dbf 100644
--- a/README.rst
+++ b/INDEX.rst
@@ -1,9 +1,14 @@
-QEMU Python Tooling
+qemu.qmp File Index
 ===================
 
-This directory houses Python tooling used by the QEMU project to build,
-configure, and test QEMU. It is organized by namespace (``qemu``), and
-then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc).
+This file is here to explain the purpose of all the little bits and
+pieces of project files in the root directory and how they are
+used. It's useful info for those contributing to this project, but not
+so much for those who just want to use the library.
+
+
+Much ado about packaging
+------------------------
 
 ``setup.py`` is used by ``pip`` to install this tooling to the current
 environment. ``setup.cfg`` provides the packaging configuration used by
@@ -20,7 +25,7 @@ environment. ``setup.cfg`` provides the packaging configuration used by
 
 If you append the ``--editable`` or ``-e`` argument to either invocation
 above, pip will install in "editable" mode. This installs the package as
-a forwarder ("qemu.egg-link") that points to the source tree. In so
+a forwarder ("qemu.qmp.egg-link") that points to the source tree. In so
 doing, the installed package always reflects the latest version in your
 source tree.
 
@@ -37,34 +42,6 @@ See `Installing packages using pip and virtual environments
 for more information.
 
 
-Using these packages without installing them
---------------------------------------------
-
-These packages may be used without installing them first, by using one
-of two tricks:
-
-1. Set your PYTHONPATH environment variable to include this source
-   directory, e.g. ``~/src/qemu/python``. See
-   https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
-
-2. Inside a Python script, use ``sys.path`` to forcibly include a search
-   path prior to importing the ``qemu`` namespace. See
-   https://docs.python.org/3/library/sys.html#sys.path
-
-A strong downside to both approaches is that they generally interfere
-with static analysis tools being able to locate and analyze the code
-being imported.
-
-Package installation also normally provides executable console scripts,
-so that tools like ``qmp-shell`` are always available via $PATH. To
-invoke them without installation, you can invoke e.g.:
-
-``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell``
-
-The mappings between console script name and python module path can be
-found in ``setup.cfg``.
-
-
 Files in this directory
 -----------------------
 
@@ -72,6 +49,7 @@ Files in this directory
 - ``tests/`` Python package tests directory.
 - ``avocado.cfg`` Configuration for the Avocado test-runner.
   Used by ``make check`` et al.
+- ``INDEX.rst`` you are here!
 - ``Makefile`` provides some common testing/installation invocations.
   Try ``make help`` to see available targets.
 - ``MANIFEST.in`` is read by python setuptools, it specifies additional files
@@ -80,8 +58,7 @@ Files in this directory
 - ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``.
 - ``Pipfile.lock`` is a set of pinned package dependencies that this package
   is tested under in our CI suite. It is used by ``make check-pipenv``.
-- ``README.rst`` you are here!
-- ``VERSION`` contains the PEP-440 compliant version used to describe
-  this package; it is referenced by ``setup.cfg``.
 - ``setup.cfg`` houses setuptools package configuration.
 - ``setup.py`` is the setuptools installer used by pip; See above.
+- ``VERSION`` contains the PEP-440 compliant version used to describe
+  this package; it is referenced by ``setup.cfg``.
diff --git a/MANIFEST.in b/MANIFEST.in
index 7059ad2..639caae 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,2 @@
 include VERSION
 include PACKAGE.rst
-exclude README.rst
-- 
2.31.1

[RFC qemu.qmp PATCH 07/24] Move PACKAGE.rst to README.rst and update

[John Snow]

The README here will reflect both what is shown on GitLab and on the
PyPI landing page. Update it accordingly.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 INDEX.rst   |   2 +-
 MANIFEST.in |   2 +-
 PACKAGE.rst |  43 ------------------
 README.rst  | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 setup.cfg   |   2 +-
 5 files changed, 132 insertions(+), 46 deletions(-)
 delete mode 100644 PACKAGE.rst
 create mode 100644 README.rst

diff --git a/INDEX.rst b/INDEX.rst
index 45b0dbf..9c45740 100644
--- a/INDEX.rst
+++ b/INDEX.rst
@@ -54,10 +54,10 @@ Files in this directory
   Try ``make help`` to see available targets.
 - ``MANIFEST.in`` is read by python setuptools, it specifies additional files
   that should be included by a source distribution.
-- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org.
 - ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``.
 - ``Pipfile.lock`` is a set of pinned package dependencies that this package
   is tested under in our CI suite. It is used by ``make check-pipenv``.
+- ``README.rst`` is used as the README file that is visible on PyPI.org.
 - ``setup.cfg`` houses setuptools package configuration.
 - ``setup.py`` is the setuptools installer used by pip; See above.
 - ``VERSION`` contains the PEP-440 compliant version used to describe
diff --git a/MANIFEST.in b/MANIFEST.in
index 639caae..2a3fc58 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,2 +1,2 @@
 include VERSION
-include PACKAGE.rst
+include README.rst
diff --git a/PACKAGE.rst b/PACKAGE.rst
deleted file mode 100644
index b0b86cc..0000000
--- a/PACKAGE.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-QEMU Python Tooling
-===================
-
-This package provides QEMU tooling used by the QEMU project to build,
-configure, and test QEMU. It is not a fully-fledged SDK and it is subject
-to change at any time.
-
-Usage
------
-
-The ``qemu.qmp`` subpackage provides a library for communicating with
-QMP servers. The ``qemu.machine`` subpackage offers rudimentary
-facilities for launching and managing QEMU processes. Refer to each
-package's documentation
-(``>>> help(qemu.qmp)``, ``>>> help(qemu.machine)``)
-for more information.
-
-Contributing
-------------
-
-This package is maintained by John Snow <jsnow@redhat.com> as part of
-the QEMU source tree. Contributions are welcome and follow the `QEMU
-patch submission process
-<https://wiki.qemu.org/Contribute/SubmitAPatch>`_, which involves
-sending patches to the QEMU development mailing list.
-
-John maintains a `GitLab staging branch
-<https://gitlab.com/jsnow/qemu/-/tree/python>`_, and there is an
-official `GitLab mirror <https://gitlab.com/qemu-project/qemu>`_.
-
-Please report bugs on the `QEMU issue tracker
-<https://gitlab.com/qemu-project/qemu/-/issues>`_ and tag ``@jsnow`` in
-the report.
-
-Optional packages necessary for running code quality analysis for this
-package can be installed with the optional dependency group "devel":
-``pip install qemu[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.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..bd4a301
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,129 @@
+QEMU Monitor Protocol (QMP) Library
+===================================
+
+This package provides an asyncio library used for communicating with
+QEMU Monitor Protocol ("QMP") servers. It requires Python 3.6+ and has
+no other dependencies.
+
+This library can be used for communicating with QEMU emulators or with
+the QEMU Guest Agent (QGA), QEMU Storage Daemon (QSD) or any other
+utility or application that speaks QMP.
+
+This library makes as little assumptions as possible about the actual
+version or what type of endpoint it will be communicating with;
+i.e. this library does not contain command definitions and does not seek
+to be an SDK or a replacement for tools like libvirt/virsh. It is
+"simply" the protocol (QMP) and not the vocabulary (QAPI). It is up to
+the programmer (you!) to know which commands and arguments you want to
+send.
+
+
+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 VM management stacks that
+integrate QEMU+kvm can make developing, testing, and debugging features
+difficult and more 'raw' access is required. 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 is this library NOT 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 swiss army
+knife with 5,000 attachments. This library does not manage that
+complexity at all and is largely "QEMU ignorant", and so it is not a
+replacement for projects like libvirt, virtual machine manager, boxes,
+etc.
+
+
+Installing
+----------
+
+This package can be installed with pip using ``pip3 install qemu.qmp``.
+
+
+Usage
+-----
+
+At its simplest, script-style usage looks like this::
+
+  from qemu.qmp import QMPClient
+
+  qmp = QMPClient('my-vm-nickname')
+  await qmp.connect('/path/to/qmp.sockfile')
+
+  res = await qmp.execute('query-status')
+  print(f"VM status: {res['status']}")
+
+  await qmp.disconnect()
+
+
+The above script will connect to the UNIX socket located at
+``/path/to/qmp.sockfile`` and query the VM's runstate and print it out
+to the terminal.
+
+For more complex usages, especially those that make full advantage of
+monitoring asynchronous events; refer to the online documentation or
+type ``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. This helps with generating Changelog text and staying
+   organized. Thank you 🙇
+
+
+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. (Personally: I run ``make check-tox && make check-pipenv``
+locally before submitting to GitLab CI as my due diligence.)
+
+
+Changelog
+---------
+
+- No public release yet.
diff --git a/setup.cfg b/setup.cfg
index 0f14bda..f4a02d6 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -10,7 +10,7 @@ url = https://gitlab.com/jsnow/qemu.qmp
 download_url = https://gitlab.com/jsnow/qemu.qmp/-/packages
 # NOTE: Remember to update the commit message when changing these URLs.
 description = QEMU Monitor Protocol library.
-long_description = file:PACKAGE.rst
+long_description = file:README.rst
 long_description_content_type = text/x-rst
 classifiers =
     Development Status :: 3 - Alpha
-- 
2.31.1

[RFC qemu.qmp PATCH 08/24] Update Pipfile.lock

[John Snow]

The name of the package has changed, and the dependencies are different
now as well. Re-do the Pipfile.

This is a little annoying, but Python doesn't offer any tool that
behaves in a manner that gives you the *oldest* but still adequate
versions of dependencies.

So, I'm doing this manually: pin every version at the minimum that still
allows the tests to succeed.

Most of these follow from just observing the minimum stated requirements
for each package, manually, recursively. However, I observed that toml's
stated dependency of >= 0.9.4 in pylint actually needs to be >= 0.10.0.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 Pipfile      |  37 +++++-
 Pipfile.lock | 314 ++++++++++++++++++++++++++++-----------------------
 2 files changed, 210 insertions(+), 141 deletions(-)

diff --git a/Pipfile b/Pipfile
index e7acb8c..de498ad 100644
--- a/Pipfile
+++ b/Pipfile
@@ -4,10 +4,43 @@ url = "https://pypi.org/simple"
 verify_ssl = true
 
 [dev-packages]
-qemu = {editable = true, extras = ["devel"], path = "."}
+avocado-framework = "==90.0"
+isort = "==5.1.2"
+tox = "==3.18.0"
+toml = "==0.10.0"
+six = "==1.14.0"
+filelock = "==3.0.0"
+virtualenv = "==16.0.0"
+py = "==1.4.17"
+pluggy = "==0.12.0"
+pyparsing = "==2.0.2"
+"backports.entry-points-selectable" = "==1.0.4"
+platformdirs = "==2.0.0"
+distlib = "==0.3.1"
+importlib-metadata = "==0.12"
+zipp = "==0.5"
+pylint = "==2.8.0"
+astroid = "==2.5.4"
+mccabe = "==0.6"
+lazy-object-proxy = "==1.4.0"
+wrapt = "==1.11"
+flake8 = "==3.6.0"
+pycodestyle = "==2.4.0"
+pyflakes = "==2.0.0"
+mypy = "==0.770"
+typed-ast = "==1.4.0"
+typing-extensions = "==3.7.4"
+mypy-extensions = "==0.4.3"
+urwid = "==2.1.2"
+urwid-readline = "==0.13"
+Pygments = "==2.9.0"
+"qemu.qmp" = {editable = true, extras = ["devel"], path = "."}
 
 [packages]
-qemu = {editable = true,path = "."}
+urwid = "==2.1.2"
+urwid-readline = "==0.13"
+Pygments = "==2.9.0"
+"qemu.qmp" = {editable = true, extras = ["tui"], path = "."}
 
 [requires]
 python_version = "3.6"
diff --git a/Pipfile.lock b/Pipfile.lock
index d2a7dbd..9d1c2cc 100644
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "784b327272db32403d5a488507853b5afba850ba26a5948e5b6a90c1baef2d9c"
+            "sha256": "76bfa8e7ee1fd855ff03697a0bc7076f4ffda0897e21c94d202cf07b609d63cb"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -16,26 +16,51 @@
         ]
     },
     "default": {
-        "qemu": {
+        "pygments": {
+            "hashes": [
+                "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
+                "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
+            ],
+            "index": "pypi",
+            "version": "==2.9.0"
+        },
+        "qemu-qmp": {
             "editable": true,
+            "extras": [
+                "tui"
+            ],
             "path": "."
+        },
+        "qemu.qmp": {
+            "editable": true,
+            "extras": [
+                "tui"
+            ],
+            "path": "."
+        },
+        "urwid": {
+            "hashes": [
+                "sha256:588bee9c1cb208d0906a9f73c613d2bd32c3ed3702012f51efe318a3f2127eae"
+            ],
+            "index": "pypi",
+            "version": "==2.1.2"
+        },
+        "urwid-readline": {
+            "hashes": [
+                "sha256:018020cbc864bb5ed87be17dc26b069eae2755cb29f3a9c569aac3bded1efaf4"
+            ],
+            "index": "pypi",
+            "version": "==0.13"
         }
     },
     "develop": {
-        "appdirs": {
-            "hashes": [
-                "sha256:7d5d0167b2b1ba821647616af46a749d1c653740dd0d2415100fe26e27afdf41",
-                "sha256:a841dacd6b99318a741b166adb07e19ee71a274450e68237b4650ca1055ab128"
-            ],
-            "version": "==1.4.4"
-        },
         "astroid": {
             "hashes": [
-                "sha256:09bdb456e02564731f8b5957cdd0c98a7f01d2db5e90eb1d794c353c28bfd705",
-                "sha256:6a8a51f64dae307f6e0c9db752b66a7951e282389d8362cc1d39a56f3feeb31d"
+                "sha256:f040fe9c4a2a7699a8ec30c9ed10fb59067c97f64c36577f476c0953ba29847c",
+                "sha256:f9f472d4002d55199b1c151ef0570cf71d42aaa34aaa3d29c3e41c75f6f47564"
             ],
-            "markers": "python_version ~= '3.6'",
-            "version": "==2.6.0"
+            "index": "pypi",
+            "version": "==2.5.4"
         },
         "avocado-framework": {
             "hashes": [
@@ -45,19 +70,28 @@
             "index": "pypi",
             "version": "==90.0"
         },
+        "backports.entry-points-selectable": {
+            "hashes": [
+                "sha256:2a238e1d8b212b9cf50156b63cd748d54dc33df74e590d614507fc9ce57d0d4a",
+                "sha256:4acda84d96855beece3bf9aad9a1030aceb5f744b8ce9af7d5ee6dd672cdd3bd"
+            ],
+            "index": "pypi",
+            "version": "==1.0.4"
+        },
         "distlib": {
             "hashes": [
-                "sha256:106fef6dc37dd8c0e2c0a60d3fca3e77460a48907f335fa28420463a6f799736",
-                "sha256:23e223426b28491b1ced97dc3bbe183027419dfc7982b4fa2f05d5f3ff10711c"
+                "sha256:8c09de2c67b3e7deef7184574fc060ab8a793e7adbb183d942c389c8b13c52fb",
+                "sha256:edf6116872c863e1aa9d5bb7cb5e05a022c519a4594dc703843343a9ddd9bff1"
             ],
-            "version": "==0.3.2"
+            "index": "pypi",
+            "version": "==0.3.1"
         },
         "filelock": {
             "hashes": [
-                "sha256:18d82244ee114f543149c66a6e0c14e9c4f8a1044b5cdaadd0f82159d6a6ff59",
-                "sha256:929b7d63ec5b7d6b71b0fa5ac14e030b3f70b75747cef1b10da9b879fef15836"
+                "sha256:b3ad481724adfb2280773edd95ce501e497e88fa4489c6e41e637ab3fd9a456c"
             ],
-            "version": "==3.0.12"
+            "index": "pypi",
+            "version": "==3.0.0"
         },
         "flake8": {
             "hashes": [
@@ -67,29 +101,13 @@
             "index": "pypi",
             "version": "==3.6.0"
         },
-        "fusepy": {
-            "hashes": [
-                "sha256:10f5c7f5414241bffecdc333c4d3a725f1d6605cae6b4eaf86a838ff49cdaf6c",
-                "sha256:a9f3a3699080ddcf0919fd1eb2cf743e1f5859ca54c2018632f939bdfac269ee"
-            ],
-            "index": "pypi",
-            "version": "==2.0.4"
-        },
         "importlib-metadata": {
             "hashes": [
-                "sha256:90bb658cdbbf6d1735b6341ce708fc7024a3e14e99ffdc5783edea9f9b077f83",
-                "sha256:dc15b2969b4ce36305c51eebe62d418ac7791e9a157911d58bfb1f9ccd8e2070"
+                "sha256:2f2e54cbf6b06b16351e4c40a6adb0860cab6cfb95a0c0fcb58bb789c4b450f5",
+                "sha256:37bbea81dec44d1ff72d58a1b5c1599a9f3436537f33e9e26f276610064c4830"
             ],
-            "markers": "python_version < '3.8'",
-            "version": "==1.7.0"
-        },
-        "importlib-resources": {
-            "hashes": [
-                "sha256:54161657e8ffc76596c4ede7080ca68cb02962a2e074a2586b695a93a925d36e",
-                "sha256:e962bff7440364183203d179d7ae9ad90cb1f2b74dcb84300e88ecc42dca3351"
-            ],
-            "markers": "python_version < '3.7'",
-            "version": "==5.1.4"
+            "index": "pypi",
+            "version": "==0.12"
         },
         "isort": {
             "hashes": [
@@ -101,38 +119,35 @@
         },
         "lazy-object-proxy": {
             "hashes": [
-                "sha256:17e0967ba374fc24141738c69736da90e94419338fd4c7c7bef01ee26b339653",
-                "sha256:1fee665d2638491f4d6e55bd483e15ef21f6c8c2095f235fef72601021e64f61",
-                "sha256:22ddd618cefe54305df49e4c069fa65715be4ad0e78e8d252a33debf00f6ede2",
-                "sha256:24a5045889cc2729033b3e604d496c2b6f588c754f7a62027ad4437a7ecc4837",
-                "sha256:410283732af311b51b837894fa2f24f2c0039aa7f220135192b38fcc42bd43d3",
-                "sha256:4732c765372bd78a2d6b2150a6e99d00a78ec963375f236979c0626b97ed8e43",
-                "sha256:489000d368377571c6f982fba6497f2aa13c6d1facc40660963da62f5c379726",
-                "sha256:4f60460e9f1eb632584c9685bccea152f4ac2130e299784dbaf9fae9f49891b3",
-                "sha256:5743a5ab42ae40caa8421b320ebf3a998f89c85cdc8376d6b2e00bd12bd1b587",
-                "sha256:85fb7608121fd5621cc4377a8961d0b32ccf84a7285b4f1d21988b2eae2868e8",
-                "sha256:9698110e36e2df951c7c36b6729e96429c9c32b3331989ef19976592c5f3c77a",
-                "sha256:9d397bf41caad3f489e10774667310d73cb9c4258e9aed94b9ec734b34b495fd",
-                "sha256:b579f8acbf2bdd9ea200b1d5dea36abd93cabf56cf626ab9c744a432e15c815f",
-                "sha256:b865b01a2e7f96db0c5d12cfea590f98d8c5ba64ad222300d93ce6ff9138bcad",
-                "sha256:bf34e368e8dd976423396555078def5cfc3039ebc6fc06d1ae2c5a65eebbcde4",
-                "sha256:c6938967f8528b3668622a9ed3b31d145fab161a32f5891ea7b84f6b790be05b",
-                "sha256:d1c2676e3d840852a2de7c7d5d76407c772927addff8d742b9808fe0afccebdf",
-                "sha256:d7124f52f3bd259f510651450e18e0fd081ed82f3c08541dffc7b94b883aa981",
-                "sha256:d900d949b707778696fdf01036f58c9876a0d8bfe116e8d220cfd4b15f14e741",
-                "sha256:ebfd274dcd5133e0afae738e6d9da4323c3eb021b3e13052d8cbd0e457b1256e",
-                "sha256:ed361bb83436f117f9917d282a456f9e5009ea12fd6de8742d1a4752c3017e93",
-                "sha256:f5144c75445ae3ca2057faac03fda5a902eff196702b0a24daf1d6ce0650514b"
+                "sha256:118d53f8819f9457732dd0e418752f2850f395c5405b2e12485f52336e4ad0f5",
+                "sha256:495c583b363c3eded649e2c00177093f03f856f5c9f95b527420084a9ce17b9d",
+                "sha256:55fa9eab93482891ce97473e63610efdd9c8fa5c05cca9f60468c412e602e499",
+                "sha256:642fc0a9b61920669dab66e400f79f1b8b0e8f698dcde85f7e9ae5528dbcaf4a",
+                "sha256:7003959a170fde9b92936c38562810f94679c80608fb4b007e026b915bef8b27",
+                "sha256:7e63da94f5a1ddb0d2dcdb5d17ff4d1d33f51f3368bdf0475d5f56c0f3b99592",
+                "sha256:7fb11d33d99a374e4b0c3fb20128890b9cf784ca7e4b91ecbb191d34618bd9fe",
+                "sha256:8758715ea005afa293783797498d64f40ab14d1ded208b3e282760cde9512f1d",
+                "sha256:8995543f47a8b81962e384f12791114af9f4997be7a0db71abc40d2a2dfee961",
+                "sha256:91c7e1316116fedda36818ce7cd269378fffc4219781536eff441ea1e68e1caf",
+                "sha256:9b41ec246d31ca6a840dcf67673b2668adc5a095c64310d26d73292588563ea3",
+                "sha256:a8be3cfd7c3154e8d39276c627c5e7ee55d1f2094597b060ece99620ef9fe86b",
+                "sha256:afcab74f471652b643900e0862b31892ac5fe5a75e435b786a1825855f4effdf",
+                "sha256:d49a90c27074f44c8dc147d83e31140523948ee147b3248634c540e053caea58",
+                "sha256:d6957cadc9c079ef4697564af500d52fba6d14fb2f08d20ce92f52201fb77050",
+                "sha256:da7f2a6c82a11dc4e05bab73522f0d6dd4f3bbc8378cd4b0769137f342cdb3f0",
+                "sha256:f03a21f6f6e54778860122a620f70c8b148ec4ee175968782bcaaa94955a46f9",
+                "sha256:f6c718ffca055852479880debbe717da952fcfd60067a0ddb6fe3b053b1d4de0"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'",
-            "version": "==1.6.0"
+            "index": "pypi",
+            "version": "==1.4.0"
         },
         "mccabe": {
             "hashes": [
-                "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
-                "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"
+                "sha256:c6f88ac33667c89d6588e5189334d051f186f4dd3ae5139586af54677c36b5a8",
+                "sha256:de9bbfe5b771e4c11b1521f3e338fe265a12296b59302f43a3bbf3e02d4b98b1"
             ],
-            "version": "==0.6.1"
+            "index": "pypi",
+            "version": "==0.6"
         },
         "mypy": {
             "hashes": [
@@ -159,31 +174,39 @@
                 "sha256:090fedd75945a69ae91ce1303b5824f428daf5a028d2f6ab8a299250a846f15d",
                 "sha256:2d82818f5bb3e369420cb3c4060a7970edba416647068eb4c5343488a6c604a8"
             ],
+            "index": "pypi",
             "version": "==0.4.3"
         },
         "packaging": {
             "hashes": [
-                "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
-                "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
+                "sha256:dd47c42927d89ab911e606518907cc2d3a1f38bbd026385970643f9c5b8ecfeb",
+                "sha256:ef103e05f519cdc783ae24ea4e2e0f508a9c99b2d4969652eed6a2e1ea5bd522"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.9"
+            "markers": "python_version >= '3.6'",
+            "version": "==21.3"
+        },
+        "platformdirs": {
+            "hashes": [
+                "sha256:9fc2bc9a5f04bfd5b12c1edb64394f6108c17b2a5be0a461f9a8b08c8a7d8991",
+                "sha256:c4d969c6d051f37548994641338c74f3125b771e8fbbe4a45d60d4a976e34533"
+            ],
+            "index": "pypi",
+            "version": "==2.0.0"
         },
         "pluggy": {
             "hashes": [
-                "sha256:15b2acde666561e1298d71b523007ed7364de07029219b604cf808bfa1c765b0",
-                "sha256:966c145cd83c96502c3c3868f50408687b38434af77734af1e9ca461a4081d2d"
+                "sha256:0825a152ac059776623854c1543d65a4ad408eb3d33ee114dff91e57ec6ae6fc",
+                "sha256:b9817417e95936bf75d85d3f8767f7df6cdde751fc40aed3bb3074cbcb77757c"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==0.13.1"
+            "index": "pypi",
+            "version": "==0.12.0"
         },
         "py": {
             "hashes": [
-                "sha256:21b81bda15b66ef5e1a777a21c4dcd9c20ad3efd0b3f817e7a809035269e1bd3",
-                "sha256:3b80836aa6d1feeaa108e046da6423ab8f6ceda6468545ae8d02d9d58d18818a"
+                "sha256:45d74855a614c73f97b0cbbe5615e5be34fa623ecf5ee6b7a4417f9a52665fb7"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.10.0"
+            "index": "pypi",
+            "version": "==1.4.17"
         },
         "pycodestyle": {
             "hashes": [
@@ -191,6 +214,7 @@
                 "sha256:cbc619d09254895b0d12c2c691e237b2e91e9b2ecf5e84c26b35400f93dcfb83",
                 "sha256:cbfca99bd594a10f674d0cd97a3d802a1fdef635d4361e1a2658de47ed261e3a"
             ],
+            "index": "pypi",
             "version": "==2.4.0"
         },
         "pyflakes": {
@@ -198,6 +222,7 @@
                 "sha256:9a7662ec724d0120012f6e29d6248ae3727d821bba522a0e6b356eff19126a49",
                 "sha256:f661252913bc1dbe7fcfcbf0af0db3f42ab65aabd1a6ca68fe5d466bace94dae"
             ],
+            "index": "pypi",
             "version": "==2.0.0"
         },
         "pygments": {
@@ -205,7 +230,7 @@
                 "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
                 "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
             ],
-            "markers": "python_version >= '3.5'",
+            "index": "pypi",
             "version": "==2.9.0"
         },
         "pylint": {
@@ -218,31 +243,49 @@
         },
         "pyparsing": {
             "hashes": [
-                "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
-                "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
+                "sha256:1039385c4702ba1834f1d5d6a832c3acdb499c7a8ffdd460ba6d381df3c30cda",
+                "sha256:1584a093537c6f0add04a514b91b55fda93e2331de7e5140f835d7d8662ea291",
+                "sha256:17e43d6b17588ed5968735575b3983a952133ec4082596d214d7090b56d48a06",
+                "sha256:3a203a88fc0f0b3c21909de3367ade6b51b2f32abb4e6932bcbf197273593f72",
+                "sha256:4dda9208817b3a1fe7d500408e4d5ebbb8e4549ba377e6a259ab2552e1275b0b",
+                "sha256:7145b41ff85f2428e365f2b9bd16b69bd68f1150c3f8d05528273505ede15abe",
+                "sha256:8e395e5c5c7d95e62b4a6a5311afbf8644b6d5f8280e033aebfca38d1f637486",
+                "sha256:a4c2134b09d85dc250422cdd1ab1c4bc4603dd5016f881c2a987c472778a9a14",
+                "sha256:d61cce2ef4bc4eb27d99bc5130e30be1bfbe59fe41e804255f06061cbec0388f"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==2.4.7"
+            "index": "pypi",
+            "version": "==2.0.2"
         },
-        "qemu": {
+        "qemu-qmp": {
             "editable": true,
+            "extras": [
+                "tui"
+            ],
+            "path": "."
+        },
+        "qemu.qmp": {
+            "editable": true,
+            "extras": [
+                "tui"
+            ],
             "path": "."
         },
         "six": {
             "hashes": [
-                "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
-                "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
+                "sha256:236bdbdce46e6e6a3d61a337c0f8b763ca1e8717c03b369e87a7ec7ce1319c0a",
+                "sha256:8f3cd2e254d8f793e7f3d6d9df77b92252b52637291d0f0da013c76ea2724b6c"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==1.16.0"
+            "index": "pypi",
+            "version": "==1.14.0"
         },
         "toml": {
             "hashes": [
-                "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
-                "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
+                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c",
+                "sha256:235682dd292d5899d361a811df37e04a8828a5b1da3115886b73cf81ebc9100e",
+                "sha256:f1db651f9657708513243e61e6cc67d101a39bad662eaa9b5546f789338e07a3"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==0.10.2"
+            "index": "pypi",
+            "version": "==0.10.0"
         },
         "tox": {
             "hashes": [
@@ -254,82 +297,75 @@
         },
         "typed-ast": {
             "hashes": [
-                "sha256:01ae5f73431d21eead5015997ab41afa53aa1fbe252f9da060be5dad2c730ace",
-                "sha256:067a74454df670dcaa4e59349a2e5c81e567d8d65458d480a5b3dfecec08c5ff",
-                "sha256:0fb71b8c643187d7492c1f8352f2c15b4c4af3f6338f21681d3681b3dc31a266",
-                "sha256:1b3ead4a96c9101bef08f9f7d1217c096f31667617b58de957f690c92378b528",
-                "sha256:2068531575a125b87a41802130fa7e29f26c09a2833fea68d9a40cf33902eba6",
-                "sha256:209596a4ec71d990d71d5e0d312ac935d86930e6eecff6ccc7007fe54d703808",
-                "sha256:2c726c276d09fc5c414693a2de063f521052d9ea7c240ce553316f70656c84d4",
-                "sha256:398e44cd480f4d2b7ee8d98385ca104e35c81525dd98c519acff1b79bdaac363",
-                "sha256:52b1eb8c83f178ab787f3a4283f68258525f8d70f778a2f6dd54d3b5e5fb4341",
-                "sha256:5feca99c17af94057417d744607b82dd0a664fd5e4ca98061480fd8b14b18d04",
-                "sha256:7538e495704e2ccda9b234b82423a4038f324f3a10c43bc088a1636180f11a41",
-                "sha256:760ad187b1041a154f0e4d0f6aae3e40fdb51d6de16e5c99aedadd9246450e9e",
-                "sha256:777a26c84bea6cd934422ac2e3b78863a37017618b6e5c08f92ef69853e765d3",
-                "sha256:95431a26309a21874005845c21118c83991c63ea800dd44843e42a916aec5899",
-                "sha256:9ad2c92ec681e02baf81fdfa056fe0d818645efa9af1f1cd5fd6f1bd2bdfd805",
-                "sha256:9c6d1a54552b5330bc657b7ef0eae25d00ba7ffe85d9ea8ae6540d2197a3788c",
-                "sha256:aee0c1256be6c07bd3e1263ff920c325b59849dc95392a05f258bb9b259cf39c",
-                "sha256:af3d4a73793725138d6b334d9d247ce7e5f084d96284ed23f22ee626a7b88e39",
-                "sha256:b36b4f3920103a25e1d5d024d155c504080959582b928e91cb608a65c3a49e1a",
-                "sha256:b9574c6f03f685070d859e75c7f9eeca02d6933273b5e69572e5ff9d5e3931c3",
-                "sha256:bff6ad71c81b3bba8fa35f0f1921fb24ff4476235a6e94a26ada2e54370e6da7",
-                "sha256:c190f0899e9f9f8b6b7863debfb739abcb21a5c054f911ca3596d12b8a4c4c7f",
-                "sha256:c907f561b1e83e93fad565bac5ba9c22d96a54e7ea0267c708bffe863cbe4075",
-                "sha256:cae53c389825d3b46fb37538441f75d6aecc4174f615d048321b716df2757fb0",
-                "sha256:dd4a21253f42b8d2b48410cb31fe501d32f8b9fbeb1f55063ad102fe9c425e40",
-                "sha256:dde816ca9dac1d9c01dd504ea5967821606f02e510438120091b84e852367428",
-                "sha256:f2362f3cb0f3172c42938946dbc5b7843c2a28aec307c49100c8b38764eb6927",
-                "sha256:f328adcfebed9f11301eaedfa48e15bdece9b519fb27e6a8c01aa52a17ec31b3",
-                "sha256:f8afcf15cc511ada719a88e013cec87c11aff7b91f019295eb4530f96fe5ef2f",
-                "sha256:fb1bbeac803adea29cedd70781399c99138358c26d05fcbd23c13016b7f5ec65"
+                "sha256:1170afa46a3799e18b4c977777ce137bb53c7485379d9706af8a59f2ea1aa161",
+                "sha256:18511a0b3e7922276346bcb47e2ef9f38fb90fd31cb9223eed42c85d1312344e",
+                "sha256:262c247a82d005e43b5b7f69aff746370538e176131c32dda9cb0f324d27141e",
+                "sha256:2b907eb046d049bcd9892e3076c7a6456c93a25bebfe554e931620c90e6a25b0",
+                "sha256:354c16e5babd09f5cb0ee000d54cfa38401d8b8891eefa878ac772f827181a3c",
+                "sha256:48e5b1e71f25cfdef98b013263a88d7145879fbb2d5185f2a0c79fa7ebbeae47",
+                "sha256:4e0b70c6fc4d010f8107726af5fd37921b666f5b31d9331f0bd24ad9a088e631",
+                "sha256:630968c5cdee51a11c05a30453f8cd65e0cc1d2ad0d9192819df9978984529f4",
+                "sha256:66480f95b8167c9c5c5c87f32cf437d585937970f3fc24386f313a4c97b44e34",
+                "sha256:71211d26ffd12d63a83e079ff258ac9d56a1376a25bc80b1cdcdf601b855b90b",
+                "sha256:7954560051331d003b4e2b3eb822d9dd2e376fa4f6d98fee32f452f52dd6ebb2",
+                "sha256:838997f4310012cf2e1ad3803bce2f3402e9ffb71ded61b5ee22617b3a7f6b6e",
+                "sha256:95bd11af7eafc16e829af2d3df510cecfd4387f6453355188342c3e79a2ec87a",
+                "sha256:bc6c7d3fa1325a0c6613512a093bc2a2a15aeec350451cbdf9e1d4bffe3e3233",
+                "sha256:cc34a6f5b426748a507dd5d1de4c1978f2eb5626d51326e43280941206c209e1",
+                "sha256:d755f03c1e4a51e9b24d899561fec4ccaf51f210d52abdf8c07ee2849b212a36",
+                "sha256:d7c45933b1bdfaf9f36c579671fec15d25b06c8398f113dab64c18ed1adda01d",
+                "sha256:d896919306dd0aa22d0132f62a1b78d11aaf4c9fc5b3410d3c666b818191630a",
+                "sha256:fdc1c9bbf79510b76408840e009ed65958feba92a88833cdceecff93ae8fff66",
+                "sha256:ffde2fbfad571af120fcbfbbc61c72469e72f550d676c3342492a9dfdefb8f12"
             ],
-            "markers": "python_version < '3.8' and implementation_name == 'cpython'",
-            "version": "==1.4.3"
+            "index": "pypi",
+            "version": "==1.4.0"
         },
         "typing-extensions": {
             "hashes": [
-                "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
-                "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
-                "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
+                "sha256:2ed632b30bb54fc3941c382decfd0ee4148f5c591651c9272473fea2c6397d95",
+                "sha256:b1edbbf0652660e32ae780ac9433f4231e7339c7f9a8057d0f042fcbcea49b87",
+                "sha256:d8179012ec2c620d3791ca6fe2bf7979d979acdbef1fca0bc56b37411db682ed"
             ],
-            "markers": "python_version < '3.8'",
-            "version": "==3.10.0.0"
+            "index": "pypi",
+            "version": "==3.7.4"
         },
         "urwid": {
             "hashes": [
                 "sha256:588bee9c1cb208d0906a9f73c613d2bd32c3ed3702012f51efe318a3f2127eae"
             ],
+            "index": "pypi",
             "version": "==2.1.2"
         },
         "urwid-readline": {
             "hashes": [
                 "sha256:018020cbc864bb5ed87be17dc26b069eae2755cb29f3a9c569aac3bded1efaf4"
             ],
+            "index": "pypi",
             "version": "==0.13"
         },
         "virtualenv": {
             "hashes": [
-                "sha256:14fdf849f80dbb29a4eb6caa9875d476ee2a5cf76a5f5415fa2f1606010ab467",
-                "sha256:2b0126166ea7c9c3661f5b8e06773d28f83322de7a3ff7d06f0aed18c9de6a76"
+                "sha256:2ce32cd126117ce2c539f0134eb89de91a8413a29baac49cbab3eb50e2026669",
+                "sha256:ca07b4c0b54e14a91af9f34d0919790b016923d157afda5efdde55c96718f752"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
-            "version": "==20.4.7"
+            "index": "pypi",
+            "version": "==16.0.0"
         },
         "wrapt": {
             "hashes": [
-                "sha256:b62ffa81fb85f4332a4f609cab4ac40709470da05643a082ec1eb88e6d9b97d7"
+                "sha256:e03f19f64d81d0a3099518ca26b04550026f131eced2e76ced7b85c6b8d32128"
             ],
-            "version": "==1.12.1"
+            "index": "pypi",
+            "version": "==1.11"
         },
         "zipp": {
             "hashes": [
-                "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76",
-                "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098"
+                "sha256:46dfd547d9ccbf8bdc26ecea52818046bb28509f12bb6a0de1cd66ab06e9a9be",
+                "sha256:d7ac25f895fb65bff937b381353c14eb1fa23d35f40abd72a5342cd57eb57fd1"
             ],
-            "markers": "python_version < '3.10'",
-            "version": "==3.4.1"
+            "index": "pypi",
+            "version": "==0.5"
         }
     }
 }
-- 
2.31.1

[RFC qemu.qmp PATCH 09/24] Remove sub-dependency pins from Pipfile

[John Snow]

Now that we've got a Pipfile.lock generated that works, we can remove
the static pins from the Pipfile to allow various dependencies to be
added or removed as necessary when updating our direct dependencies in
the future.

So long as --keep-outdated is always passed to Pipenv, items that aren't
absolutely necessary to update will not be, which will help keep our
requirements more at the very oldest possible versions that still work.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 Pipfile | 33 ---------------------------------
 1 file changed, 33 deletions(-)

diff --git a/Pipfile b/Pipfile
index de498ad..f44fd1e 100644
--- a/Pipfile
+++ b/Pipfile
@@ -4,42 +4,9 @@ url = "https://pypi.org/simple"
 verify_ssl = true
 
 [dev-packages]
-avocado-framework = "==90.0"
-isort = "==5.1.2"
-tox = "==3.18.0"
-toml = "==0.10.0"
-six = "==1.14.0"
-filelock = "==3.0.0"
-virtualenv = "==16.0.0"
-py = "==1.4.17"
-pluggy = "==0.12.0"
-pyparsing = "==2.0.2"
-"backports.entry-points-selectable" = "==1.0.4"
-platformdirs = "==2.0.0"
-distlib = "==0.3.1"
-importlib-metadata = "==0.12"
-zipp = "==0.5"
-pylint = "==2.8.0"
-astroid = "==2.5.4"
-mccabe = "==0.6"
-lazy-object-proxy = "==1.4.0"
-wrapt = "==1.11"
-flake8 = "==3.6.0"
-pycodestyle = "==2.4.0"
-pyflakes = "==2.0.0"
-mypy = "==0.770"
-typed-ast = "==1.4.0"
-typing-extensions = "==3.7.4"
-mypy-extensions = "==0.4.3"
-urwid = "==2.1.2"
-urwid-readline = "==0.13"
-Pygments = "==2.9.0"
 "qemu.qmp" = {editable = true, extras = ["devel"], path = "."}
 
 [packages]
-urwid = "==2.1.2"
-urwid-readline = "==0.13"
-Pygments = "==2.9.0"
 "qemu.qmp" = {editable = true, extras = ["tui"], path = "."}
 
 [requires]
-- 
2.31.1

[RFC qemu.qmp PATCH 10/24] Add build and test container to gitlab CI configuration

[John Snow]

Heavily copy-pasted from the QEMU source tree, with bits and pieces not
needed for this repository trimmed down.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab-ci.d/containers.yml    | 28 ++++++++++++++++++++++++++++
 .gitlab-ci.d/index.yml         |  8 ++++++++
 .gitlab-ci.d/python.Dockerfile | 31 +++++++++++++++++++++++++++++++
 .gitlab-ci.yml                 |  3 +++
 INDEX.rst                      |  2 ++
 5 files changed, 72 insertions(+)
 create mode 100644 .gitlab-ci.d/containers.yml
 create mode 100644 .gitlab-ci.d/index.yml
 create mode 100644 .gitlab-ci.d/python.Dockerfile
 create mode 100644 .gitlab-ci.yml

diff --git a/.gitlab-ci.d/containers.yml b/.gitlab-ci.d/containers.yml
new file mode 100644
index 0000000..fdcbbe4
--- /dev/null
+++ b/.gitlab-ci.d/containers.yml
@@ -0,0 +1,28 @@
+# Heavily inspired-by/copy-pasted-from the
+# container template from the QEMU source tree.
+
+.container_job_template:
+  image: docker:stable
+  stage: containers
+  services:
+    - docker:dind
+  before_script:
+    - export TAG="$NAME"
+    - export FQTAG="$CI_REGISTRY_IMAGE/$TAG:latest"
+    - docker info
+    - docker login $CI_REGISTRY -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD"
+  script:
+    - echo "TAG:$TAG"
+    - echo "FQTAG:$FQTAG"
+    - cd .gitlab-ci.d
+    - docker pull "$FQTAG"
+    - docker build --cache-from "$FQTAG" -t "$TAG" -f "$NAME.Dockerfile" .
+    - docker tag "$TAG" "$FQTAG"
+    - docker push "$FQTAG"
+  after_script:
+    - docker logout
+
+python-container:
+  extends: .container_job_template
+  variables:
+    NAME: python
diff --git a/.gitlab-ci.d/index.yml b/.gitlab-ci.d/index.yml
new file mode 100644
index 0000000..5ef8fcf
--- /dev/null
+++ b/.gitlab-ci.d/index.yml
@@ -0,0 +1,8 @@
+# This file contains the set of jobs run by this project:
+# https://gitlab.com/jsnow/qemu.qmp/-/pipelines
+
+stages:
+  - containers
+
+include:
+  - local: '/.gitlab-ci.d/containers.yml'
diff --git a/.gitlab-ci.d/python.Dockerfile b/.gitlab-ci.d/python.Dockerfile
new file mode 100644
index 0000000..9501ed4
--- /dev/null
+++ b/.gitlab-ci.d/python.Dockerfile
@@ -0,0 +1,31 @@
+# Python library build & testing environment.
+
+# Fedora is convenient, as it allows us to easily access multiple
+# versions of the python interpreter, which is great for tox testing.
+FROM fedora:latest
+
+# 「はじめまして！」
+MAINTAINER John Snow <jsnow@redhat.com>
+
+# Please keep the packages sorted alphabetically.
+RUN dnf --setopt=install_weak_deps=False install -y \
+        gcc \
+        git \
+        make \
+        pipenv \
+        python3 \
+        python3-pip \
+        python3-tox \
+        python3-virtualenv \
+        python3.10 \
+        python3.6 \
+        python3.7 \
+        python3.8 \
+        python3.9 \
+    && python3 -m pip install --upgrade \
+        build \
+        pip \
+    && dnf clean all \
+    && rm -rf ~/.cache/pip \
+    && rm -rf /var/cache/dnf \
+    ;
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
new file mode 100644
index 0000000..f93a1e1
--- /dev/null
+++ b/.gitlab-ci.yml
@@ -0,0 +1,3 @@
+# Hello, is it me you're looking for?
+include:
+  - local: '/.gitlab-ci.d/index.yml'
diff --git a/INDEX.rst b/INDEX.rst
index 9c45740..8b7a56a 100644
--- a/INDEX.rst
+++ b/INDEX.rst
@@ -47,6 +47,8 @@ Files in this directory
 
 - ``qemu/`` Python 'qemu' namespace package source directory.
 - ``tests/`` Python package tests directory.
+- ``.gitlab-ci.d/`` Files used for GitLab CI configuration.
+- ``.gitlab-ci.yml`` Primary GitLab CI configuration file.
 - ``avocado.cfg`` Configuration for the Avocado test-runner.
   Used by ``make check`` et al.
 - ``INDEX.rst`` you are here!
-- 
2.31.1

[RFC qemu.qmp PATCH 11/24] Add package build step to GitLab CI

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab-ci.d/build.yml | 13 +++++++++++++
 .gitlab-ci.d/index.yml |  2 ++
 2 files changed, 15 insertions(+)
 create mode 100644 .gitlab-ci.d/build.yml

diff --git a/.gitlab-ci.d/build.yml b/.gitlab-ci.d/build.yml
new file mode 100644
index 0000000..6a68408
--- /dev/null
+++ b/.gitlab-ci.d/build.yml
@@ -0,0 +1,13 @@
+build-package:
+  stage: build
+  image: $CI_REGISTRY_IMAGE/python:latest
+  needs:
+    job: python-container
+  script:
+    - python3 -m build
+  artifacts:
+    name: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG-$CI_COMMIT_SHORT_SHA"
+    paths:
+      - dist/*
+  variables:
+    GIT_DEPTH: 1
diff --git a/.gitlab-ci.d/index.yml b/.gitlab-ci.d/index.yml
index 5ef8fcf..cf61dec 100644
--- a/.gitlab-ci.d/index.yml
+++ b/.gitlab-ci.d/index.yml
@@ -3,6 +3,8 @@
 
 stages:
   - containers
+  - build
 
 include:
   - local: '/.gitlab-ci.d/containers.yml'
+  - local: '/.gitlab-ci.d/build.yml'
-- 
2.31.1

[RFC qemu.qmp PATCH 12/24] GitLab CI: Add check-dco script

[John Snow]

Borrowed with minor modifications from qemu.git.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab-ci.d/check-dco.py | 98 +++++++++++++++++++++++++++++++++++++++
 .gitlab-ci.d/index.yml    |  2 +
 .gitlab-ci.d/test.yml     | 15 ++++++
 3 files changed, 115 insertions(+)
 create mode 100755 .gitlab-ci.d/check-dco.py
 create mode 100644 .gitlab-ci.d/test.yml

diff --git a/.gitlab-ci.d/check-dco.py b/.gitlab-ci.d/check-dco.py
new file mode 100755
index 0000000..747cd54
--- /dev/null
+++ b/.gitlab-ci.d/check-dco.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+#
+# check-dco.py: validate all commits are signed off
+#
+# Copyright (C) 2020 Red Hat, Inc.
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import argparse
+import os
+import os.path
+import sys
+import subprocess
+
+parser = argparse.ArgumentParser("check-dco")
+parser.add_argument(
+    "repourl",
+    help="upstream repo URL"
+)
+parser.add_argument(
+    "refspec",
+    help="upstream's default branch (or other refspec)"
+)
+args = parser.parse_args()
+
+
+subprocess.check_call(["git", "remote", "add", "check-dco", args.repourl])
+subprocess.check_call(["git", "fetch", "check-dco", args.refspec],
+                      stdout=subprocess.DEVNULL,
+                      stderr=subprocess.DEVNULL)
+
+ancestor = subprocess.check_output(
+    ["git", "merge-base", f"check-dco/{args.refspec}", "HEAD"],
+    universal_newlines=True)
+ancestor = ancestor.strip()
+
+subprocess.check_call(["git", "remote", "rm", "check-dco"])
+
+errors = False
+
+print("\nChecking for 'Signed-off-by: NAME <EMAIL>' " +
+      "on all commits since %s...\n" % ancestor)
+
+log = subprocess.check_output(["git", "log", "--format=%H %s",
+                               ancestor + "..."],
+                              universal_newlines=True)
+
+if log == "":
+    commits = []
+else:
+    commits = [[c[0:40], c[41:]] for c in log.strip().split("\n")]
+
+for sha, subject in commits:
+
+    msg = subprocess.check_output(["git", "show", "-s", sha],
+                                  universal_newlines=True)
+    lines = msg.strip().split("\n")
+
+    print("🔍 %s %s" % (sha, subject))
+    sob = False
+    for line in lines:
+        if "Signed-off-by:" in line:
+            sob = True
+            if "localhost" in line:
+                print("    ❌ FAIL: bad email in %s" % line)
+                errors = True
+
+    if not sob:
+        print("    ❌ FAIL missing Signed-off-by tag")
+        errors = True
+
+if errors:
+    print("""
+
+❌ ERROR: One or more commits are missing a valid Signed-off-By tag.
+
+
+This project requires all contributors to assert that their contributions
+are provided in compliance with the terms of the Developer's Certificate
+of Origin 1.1 (DCO):
+
+  https://developercertificate.org/
+
+To indicate acceptance of the DCO every commit must have a tag
+
+  Signed-off-by: REAL NAME <EMAIL>
+
+This can be achieved by passing the "-s" flag to the "git commit" command.
+
+To bulk update all commits on current branch "git rebase" can be used:
+
+  git rebase -i master -x 'git commit --amend --no-edit -s'
+
+""")
+
+    sys.exit(1)
+
+sys.exit(0)
diff --git a/.gitlab-ci.d/index.yml b/.gitlab-ci.d/index.yml
index cf61dec..cd6a65e 100644
--- a/.gitlab-ci.d/index.yml
+++ b/.gitlab-ci.d/index.yml
@@ -4,7 +4,9 @@
 stages:
   - containers
   - build
+  - test
 
 include:
   - local: '/.gitlab-ci.d/containers.yml'
   - local: '/.gitlab-ci.d/build.yml'
+  - local: '/.gitlab-ci.d/test.yml'
diff --git a/.gitlab-ci.d/test.yml b/.gitlab-ci.d/test.yml
new file mode 100644
index 0000000..35fa105
--- /dev/null
+++ b/.gitlab-ci.d/test.yml
@@ -0,0 +1,15 @@
+check-dco:
+  stage: test
+  image: $CI_REGISTRY_IMAGE/python:latest
+  needs:
+    job: python-container
+  script:
+    - .gitlab-ci.d/check-dco.py
+      "https://gitlab.com/jsnow/qemu.qmp.git"
+      "main"
+  variables:
+    GIT_DEPTH: 1000
+  rules:
+    - if: '$CI_PROJECT_NAMESPACE == "jsnow" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+      when: never
+    - when: on_success
-- 
2.31.1

[RFC qemu.qmp PATCH 13/24] GitLab CI: Add pipenv and tox tests

[John Snow]

FIXME: For testing purposes, this patch is still using my personal
GitLab URLs, which will have to be changed before this is pushed to
production.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab-ci.d/test.yml | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/.gitlab-ci.d/test.yml b/.gitlab-ci.d/test.yml
index 35fa105..19e0c37 100644
--- a/.gitlab-ci.d/test.yml
+++ b/.gitlab-ci.d/test.yml
@@ -13,3 +13,46 @@ check-dco:
     - if: '$CI_PROJECT_NAMESPACE == "jsnow" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
       when: never
     - when: on_success
+
+.python_test:
+  stage: test
+  image: $CI_REGISTRY_IMAGE/python:latest
+  variables:
+    GIT_DEPTH: 1
+  needs:
+    job: python-container
+
+check-python-pipenv:
+  extends: .python_test
+  script:
+    - make check-pipenv
+
+check-python-36:
+  extends: .python_test
+  script:
+    - QEMU_TOX_EXTRA_ARGS="-e py36" make check-tox
+  allow_failure: true
+
+check-python-37:
+  extends: .python_test
+  script:
+    - QEMU_TOX_EXTRA_ARGS="-e py37" make check-tox
+  allow_failure: true
+
+check-python-38:
+  extends: .python_test
+  script:
+    - QEMU_TOX_EXTRA_ARGS="-e py38" make check-tox
+  allow_failure: true
+
+check-python-39:
+  extends: .python_test
+  script:
+    - QEMU_TOX_EXTRA_ARGS="-e py39" make check-tox
+  allow_failure: true
+
+check-python-310:
+  extends: .python_test
+  script:
+    - QEMU_TOX_EXTRA_ARGS="-e py310" make check-tox
+  allow_failure: true
-- 
2.31.1

[RFC qemu.qmp PATCH 14/24] GitLab CI: Add avocado junit XML output to tests

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab-ci.d/test.yml | 16 ++++++++++++++++
 Makefile              |  1 +
 avocado.cfg           |  7 +++++++
 3 files changed, 24 insertions(+)

diff --git a/.gitlab-ci.d/test.yml b/.gitlab-ci.d/test.yml
index 19e0c37..3b2a142 100644
--- a/.gitlab-ci.d/test.yml
+++ b/.gitlab-ci.d/test.yml
@@ -14,7 +14,23 @@ check-dco:
       when: never
     - when: on_success
 
+.avocado:
+  before_script:
+    - echo "" >> avocado.cfg
+    - echo "[datadir.paths]" >> avocado.cfg
+    - echo "logs_dir = ./test-results/" >> avocado.cfg
+  artifacts:
+    name: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG-$CI_COMMIT_SHORT_SHA"
+    when: always
+    expire_in: 7 days
+    paths:
+      - test-results/latest/results.xml
+      - test-results/latest/test-results
+    reports:
+      junit: test-results/latest/results.xml
+
 .python_test:
+  extends: .avocado
   stage: test
   image: $CI_REGISTRY_IMAGE/python:latest
   variables:
diff --git a/Makefile b/Makefile
index a2d2f2c..97d737a 100644
--- a/Makefile
+++ b/Makefile
@@ -109,3 +109,4 @@ distclean: clean
 	rm -rf qemu.qmp.egg-info/ .venv/ .tox/ $(QEMU_VENV_DIR) dist/
 	rm -f .coverage .coverage.*
 	rm -rf htmlcov/
+	rm -rf test-results/
diff --git a/avocado.cfg b/avocado.cfg
index c7722e7..a7b9935 100644
--- a/avocado.cfg
+++ b/avocado.cfg
@@ -11,3 +11,10 @@ output.testlogs.logfiles = ['stdout', 'stderr']
 
 # Show full stdout/stderr only on tests that FAIL
 output.testlogs.statuses = ['FAIL']
+
+# NOTE: Various gitlab CI jobs will append configuration
+# similar to the following, in order to keep test output
+# inside of the project root:
+#
+# [datadir.paths]
+# logs_dir = ./test-results/
-- 
2.31.1

[RFC qemu.qmp PATCH 15/24] GitLab CI: Publish python packages to GitLab package repo

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab-ci.d/index.yml         |  2 ++
 .gitlab-ci.d/publish.yml       | 11 +++++++++++
 .gitlab-ci.d/python.Dockerfile |  1 +
 3 files changed, 14 insertions(+)
 create mode 100644 .gitlab-ci.d/publish.yml

diff --git a/.gitlab-ci.d/index.yml b/.gitlab-ci.d/index.yml
index cd6a65e..564308c 100644
--- a/.gitlab-ci.d/index.yml
+++ b/.gitlab-ci.d/index.yml
@@ -5,8 +5,10 @@ stages:
   - containers
   - build
   - test
+  - publish
 
 include:
   - local: '/.gitlab-ci.d/containers.yml'
   - local: '/.gitlab-ci.d/build.yml'
   - local: '/.gitlab-ci.d/test.yml'
+  - local: '/.gitlab-ci.d/publish.yml'
\ No newline at end of file
diff --git a/.gitlab-ci.d/publish.yml b/.gitlab-ci.d/publish.yml
new file mode 100644
index 0000000..8d05e05
--- /dev/null
+++ b/.gitlab-ci.d/publish.yml
@@ -0,0 +1,11 @@
+publish-package:
+  stage: publish
+  image: $CI_REGISTRY_IMAGE/python:latest
+  needs:
+    job: build-package
+  script:
+    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token
+      python3 -m twine upload
+      --verbose
+      --repository-url "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi"
+      dist/*
diff --git a/.gitlab-ci.d/python.Dockerfile b/.gitlab-ci.d/python.Dockerfile
index 9501ed4..35d84f3 100644
--- a/.gitlab-ci.d/python.Dockerfile
+++ b/.gitlab-ci.d/python.Dockerfile
@@ -25,6 +25,7 @@ RUN dnf --setopt=install_weak_deps=False install -y \
     && python3 -m pip install --upgrade \
         build \
         pip \
+        twine \
     && dnf clean all \
     && rm -rf ~/.cache/pip \
     && rm -rf /var/cache/dnf \
-- 
2.31.1

[RFC qemu.qmp PATCH 16/24] Add setuptools_scm package versioning

[John Snow]

The version number will now be generated using the setuptools_scm
package, which pulls the version number from git tags.

As PEP660 is not yet usable with pyproject.toml style packages, we will
be sticking to setup.py style installation for now.

"version = 0.0.0" exists as a fallback in the event that the
build/installation environment does not have setuptools_scm
installed. Further, if setuptools_scm *is* installed but we are trying
to install directly from a source tarball (instead of from a python
source distribution), 'fallback_version': '0.0.0' will be utilized as
the fallback.

Lastly, tag this release as v0.0.0 to give setuptools_scm something to
work with and establish precedent for future releases.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab-ci.d/build.yml         |  2 +-
 .gitlab-ci.d/python.Dockerfile |  1 +
 INDEX.rst                      |  2 --
 MANIFEST.in                    |  1 -
 VERSION                        |  1 -
 setup.cfg                      |  3 ++-
 setup.py                       | 11 ++++++++++-
 7 files changed, 14 insertions(+), 7 deletions(-)
 delete mode 100644 VERSION

diff --git a/.gitlab-ci.d/build.yml b/.gitlab-ci.d/build.yml
index 6a68408..bf2d487 100644
--- a/.gitlab-ci.d/build.yml
+++ b/.gitlab-ci.d/build.yml
@@ -10,4 +10,4 @@ build-package:
     paths:
       - dist/*
   variables:
-    GIT_DEPTH: 1
+    GIT_DEPTH: 0
\ No newline at end of file
diff --git a/.gitlab-ci.d/python.Dockerfile b/.gitlab-ci.d/python.Dockerfile
index 35d84f3..93661b2 100644
--- a/.gitlab-ci.d/python.Dockerfile
+++ b/.gitlab-ci.d/python.Dockerfile
@@ -25,6 +25,7 @@ RUN dnf --setopt=install_weak_deps=False install -y \
     && python3 -m pip install --upgrade \
         build \
         pip \
+        setuptools_scm \
         twine \
     && dnf clean all \
     && rm -rf ~/.cache/pip \
diff --git a/INDEX.rst b/INDEX.rst
index 8b7a56a..dddfcde 100644
--- a/INDEX.rst
+++ b/INDEX.rst
@@ -62,5 +62,3 @@ Files in this directory
 - ``README.rst`` is used as the README file that is visible on PyPI.org.
 - ``setup.cfg`` houses setuptools package configuration.
 - ``setup.py`` is the setuptools installer used by pip; See above.
-- ``VERSION`` contains the PEP-440 compliant version used to describe
-  this package; it is referenced by ``setup.cfg``.
diff --git a/MANIFEST.in b/MANIFEST.in
index 2a3fc58..9561fb1 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,2 +1 @@
-include VERSION
 include README.rst
diff --git a/VERSION b/VERSION
deleted file mode 100644
index 7741e1a..0000000
--- a/VERSION
+++ /dev/null
@@ -1 +0,0 @@
-0.0.0a1
diff --git a/setup.cfg b/setup.cfg
index f4a02d6..03dd4f0 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,6 +1,6 @@
 [metadata]
 name = qemu.qmp
-version = file:VERSION
+version = 0.0.0
 author = John Snow
 author_email = jsnow@redhat.com
 maintainer = QEMU Project
@@ -26,6 +26,7 @@ classifiers =
     Typing :: Typed
 
 [options]
+setup_requires = setuptools_scm
 python_requires = >= 3.6
 packages =
     qemu.qmp
diff --git a/setup.py b/setup.py
index cb9b9b6..5904d07 100755
--- a/setup.py
+++ b/setup.py
@@ -7,6 +7,12 @@ Copyright (c) 2020-2021 John Snow for Red Hat, Inc.
 import setuptools
 import pkg_resources
 
+try:
+    import setuptools_scm
+    _HAVE_SCM = True
+except ModuleNotFoundError:
+    _HAVE_SCM = False
+
 
 def main():
     """
@@ -16,7 +22,10 @@ def main():
     # https://medium.com/@daveshawley/safely-using-setup-cfg-for-metadata-1babbe54c108
     pkg_resources.require('setuptools>=39.2')
 
-    setuptools.setup()
+    if _HAVE_SCM:
+        setuptools.setup(use_scm_version={'fallback_version': '0.0.0'})
+    else:
+        setuptools.setup()
 
 
 if __name__ == '__main__':
-- 
2.31.1

[RFC qemu.qmp PATCH 17/24] Makefile: add build and publish targets

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 Makefile | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/Makefile b/Makefile
index 97d737a..81bfca8 100644
--- a/Makefile
+++ b/Makefile
@@ -110,3 +110,35 @@ distclean: clean
 	rm -f .coverage .coverage.*
 	rm -rf htmlcov/
 	rm -rf test-results/
+
+.PHONY: pristine
+pristine:
+	@git diff-files --quiet --ignore-submodules -- || \
+		(echo "You have unstaged changes."; exit 1)
+	@git diff-index --cached --quiet HEAD --ignore-submodules -- || \
+		(echo "Your index contains uncommitted changes."; exit 1)
+	@[ -z "$(shell git ls-files -o)" ] || \
+		(echo "You have untracked files: $(shell git ls-files -o)"; exit 1)
+
+dist: setup.cfg setup.py Makefile README.rst
+	python3 -m build
+	@touch dist
+
+.PHONY: pre-publish
+pre-publish: pristine dist
+	@git describe --exact-match 2>/dev/null || \
+		(echo -e "\033[0;31mThere is no annotated tag for this commit.\033[0m"; exit 1)
+	python3 -m twine check --strict dist/*
+	git push -v --atomic --follow-tags --dry-run
+
+.PHONY: publish
+publish: pre-publish
+	# Set the username via TWINE_USERNAME.
+	# Set the password via TWINE_PASSWORD.
+	# Set the pkg repository via TWINE_REPOSITORY.
+	python3 -m twine upload --verbose dist/*
+	git push -v --atomic --follow-tags
+
+.PHONY: publish-test
+publish-test: pre-publish
+	python3 -m twine upload --verbose -r testpypi dist/*
-- 
2.31.1

[RFC qemu.qmp PATCH 18/24] add Sphinx documentation config stub

[John Snow]

This is the result of this command:

sphinx-apidoc --separate \
              --no-toc \
              --module-first \
              --implicit-namespaces \
              --full \
              --ext-intersphinx \
              --ext-coverage \
              --ext-viewcode \
              -o docs/ \
              qemu/

(And `touch docs/_static/.gitignore`, to create an "empty" directory.)

This configuration is not yet functional, but I wanted to distinguish
between automatically generated boilerplate and intentional
configuration changes so as to document the entire process of getting
sphinx doc generation up, running, and fully configured.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/Makefile                | 20 +++++++++
 docs/conf.py                 | 80 ++++++++++++++++++++++++++++++++++++
 docs/index.rst               | 21 ++++++++++
 docs/make.bat                | 35 ++++++++++++++++
 docs/qemu.qmp.aqmp_tui.rst   |  7 ++++
 docs/qemu.qmp.error.rst      |  7 ++++
 docs/qemu.qmp.events.rst     |  7 ++++
 docs/qemu.qmp.legacy.rst     |  7 ++++
 docs/qemu.qmp.message.rst    |  7 ++++
 docs/qemu.qmp.models.rst     |  7 ++++
 docs/qemu.qmp.protocol.rst   |  7 ++++
 docs/qemu.qmp.qmp_client.rst |  7 ++++
 docs/qemu.qmp.qmp_shell.rst  |  7 ++++
 docs/qemu.qmp.rst            | 24 +++++++++++
 docs/qemu.qmp.util.rst       |  7 ++++
 docs/qemu.rst                | 10 +++++
 16 files changed, 260 insertions(+)
 create mode 100644 docs/Makefile
 create mode 100644 docs/conf.py
 create mode 100644 docs/index.rst
 create mode 100644 docs/make.bat
 create mode 100644 docs/qemu.qmp.aqmp_tui.rst
 create mode 100644 docs/qemu.qmp.error.rst
 create mode 100644 docs/qemu.qmp.events.rst
 create mode 100644 docs/qemu.qmp.legacy.rst
 create mode 100644 docs/qemu.qmp.message.rst
 create mode 100644 docs/qemu.qmp.models.rst
 create mode 100644 docs/qemu.qmp.protocol.rst
 create mode 100644 docs/qemu.qmp.qmp_client.rst
 create mode 100644 docs/qemu.qmp.qmp_shell.rst
 create mode 100644 docs/qemu.qmp.rst
 create mode 100644 docs/qemu.qmp.util.rst
 create mode 100644 docs/qemu.rst

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d4bb2cb
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..c7ce779
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,80 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, '/home/jsnow/src/tmp/qemu.qmp/qemu')
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'qemu'
+copyright = '2021, Author'
+author = 'Author'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.todo',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+
+# -- Extension configuration -------------------------------------------------
+
+# -- Options for intersphinx extension ---------------------------------------
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..bff786a
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,21 @@
+.. qemu documentation master file, created by
+   sphinx-quickstart on Mon Dec 13 16:50:29 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to qemu's documentation!
+================================
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+
+   qemu
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..2119f51
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/qemu.qmp.aqmp_tui.rst b/docs/qemu.qmp.aqmp_tui.rst
new file mode 100644
index 0000000..a5c55f9
--- /dev/null
+++ b/docs/qemu.qmp.aqmp_tui.rst
@@ -0,0 +1,7 @@
+qemu.qmp.aqmp\_tui module
+=========================
+
+.. automodule:: qemu.qmp.aqmp_tui
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.error.rst b/docs/qemu.qmp.error.rst
new file mode 100644
index 0000000..89f069d
--- /dev/null
+++ b/docs/qemu.qmp.error.rst
@@ -0,0 +1,7 @@
+qemu.qmp.error module
+=====================
+
+.. automodule:: qemu.qmp.error
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.events.rst b/docs/qemu.qmp.events.rst
new file mode 100644
index 0000000..a4b9fd3
--- /dev/null
+++ b/docs/qemu.qmp.events.rst
@@ -0,0 +1,7 @@
+qemu.qmp.events module
+======================
+
+.. automodule:: qemu.qmp.events
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.legacy.rst b/docs/qemu.qmp.legacy.rst
new file mode 100644
index 0000000..83abd38
--- /dev/null
+++ b/docs/qemu.qmp.legacy.rst
@@ -0,0 +1,7 @@
+qemu.qmp.legacy module
+======================
+
+.. automodule:: qemu.qmp.legacy
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.message.rst b/docs/qemu.qmp.message.rst
new file mode 100644
index 0000000..765ae63
--- /dev/null
+++ b/docs/qemu.qmp.message.rst
@@ -0,0 +1,7 @@
+qemu.qmp.message module
+=======================
+
+.. automodule:: qemu.qmp.message
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.models.rst b/docs/qemu.qmp.models.rst
new file mode 100644
index 0000000..55585b7
--- /dev/null
+++ b/docs/qemu.qmp.models.rst
@@ -0,0 +1,7 @@
+qemu.qmp.models module
+======================
+
+.. automodule:: qemu.qmp.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.protocol.rst b/docs/qemu.qmp.protocol.rst
new file mode 100644
index 0000000..fca55ad
--- /dev/null
+++ b/docs/qemu.qmp.protocol.rst
@@ -0,0 +1,7 @@
+qemu.qmp.protocol module
+========================
+
+.. automodule:: qemu.qmp.protocol
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.qmp_client.rst b/docs/qemu.qmp.qmp_client.rst
new file mode 100644
index 0000000..1d5beda
--- /dev/null
+++ b/docs/qemu.qmp.qmp_client.rst
@@ -0,0 +1,7 @@
+qemu.qmp.qmp\_client module
+===========================
+
+.. automodule:: qemu.qmp.qmp_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.qmp_shell.rst b/docs/qemu.qmp.qmp_shell.rst
new file mode 100644
index 0000000..0510cd3
--- /dev/null
+++ b/docs/qemu.qmp.qmp_shell.rst
@@ -0,0 +1,7 @@
+qemu.qmp.qmp\_shell module
+==========================
+
+.. automodule:: qemu.qmp.qmp_shell
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.qmp.rst b/docs/qemu.qmp.rst
new file mode 100644
index 0000000..305e5b0
--- /dev/null
+++ b/docs/qemu.qmp.rst
@@ -0,0 +1,24 @@
+qemu.qmp package
+================
+
+.. automodule:: qemu.qmp
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   qemu.qmp.aqmp_tui
+   qemu.qmp.error
+   qemu.qmp.events
+   qemu.qmp.legacy
+   qemu.qmp.message
+   qemu.qmp.models
+   qemu.qmp.protocol
+   qemu.qmp.qmp_client
+   qemu.qmp.qmp_shell
+   qemu.qmp.util
diff --git a/docs/qemu.qmp.util.rst b/docs/qemu.qmp.util.rst
new file mode 100644
index 0000000..8f2ac87
--- /dev/null
+++ b/docs/qemu.qmp.util.rst
@@ -0,0 +1,7 @@
+qemu.qmp.util module
+====================
+
+.. automodule:: qemu.qmp.util
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/qemu.rst b/docs/qemu.rst
new file mode 100644
index 0000000..f33a4f4
--- /dev/null
+++ b/docs/qemu.rst
@@ -0,0 +1,10 @@
+qemu namespace
+==============
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   qemu.qmp
-- 
2.31.1

[RFC qemu.qmp PATCH 19/24] python: configure sphinx

[John Snow]

With a Sphinx project auto-generated, configure it to be something a bit
more useful. And pretty.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/conf.py | 45 ++++++++++++++++++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 9 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index c7ce779..7db99c2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,18 +9,28 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, '/home/jsnow/src/tmp/qemu.qmp/qemu')
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'qemu'
-copyright = '2021, Author'
-author = 'Author'
+project = 'QEMU Monitor Protocol (QMP) Library'
+copyright = '2009-2021, QEMU Project'
+author = 'John Snow'
 
+try:
+    import setuptools_scm
+    extracted_version = setuptools_scm.get_version()
+except:
+    extracted_version = None
+finally:
+    if extracted_version:
+        version = release = extracted_version
+    else:
+        version = release = "unknown version"
 
 # -- General configuration ---------------------------------------------------
 
@@ -51,13 +61,30 @@ language = 'en'
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# Interpret `this` to be a cross-reference to "anything".
+default_role = 'any'
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+# https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#theme-options
+html_theme_options = {
+    'collapse_navigation': False,
+    'display_version': True,
+    'prev_next_buttons_location': 'both',
+}
+
+html_context = {
+    "display_gitlab": True,
+    "gitlab_user": "jsnow",
+    "gitlab_repo": "qemu.qmp",
+    "gitlab_version": "main",
+    "conf_py_path": "/docs/",
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -77,4 +104,4 @@ intersphinx_mapping = {
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
\ No newline at end of file
+todo_include_todos = True
-- 
2.31.1

[RFC qemu.qmp PATCH 20/24] python: adjust apidoc stubs

[John Snow]

Change the configuration for the generated apidoc stubs.

Some of the changes, as a summary:

- Collapse the hierarchy to omit the QEMU namespace page
- Add more meaningful titles to the subpackages
- Prefer source ordering in most places
- Do not index pages that do not define their own symbols (via __all__)
- Show hidden members for qemu.aqmp.protocol, since this interface is
  designed to be extended.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/index.rst               |  6 +++---
 docs/qemu.qmp.aqmp_tui.rst   |  7 -------
 docs/qemu.qmp.error.rst      |  1 +
 docs/qemu.qmp.message.rst    |  1 +
 docs/qemu.qmp.models.rst     |  1 +
 docs/qemu.qmp.protocol.rst   |  2 ++
 docs/qemu.qmp.qmp_client.rst |  1 +
 docs/qemu.qmp.qmp_shell.rst  |  7 -------
 docs/qemu.qmp.rst            |  8 ++++----
 docs/qemu.qmp.util.rst       |  1 +
 docs/qemu.rst                | 10 ----------
 11 files changed, 14 insertions(+), 31 deletions(-)
 delete mode 100644 docs/qemu.qmp.aqmp_tui.rst
 delete mode 100644 docs/qemu.qmp.qmp_shell.rst
 delete mode 100644 docs/qemu.rst

diff --git a/docs/index.rst b/docs/index.rst
index bff786a..2c7ccdb 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,14 +3,14 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to qemu's documentation!
-================================
+qemu.qmp library documentation
+==============================
 
 .. toctree::
    :maxdepth: 4
    :caption: Contents:
 
-   qemu
+   qemu.qmp
 
 
 Indices and tables
diff --git a/docs/qemu.qmp.aqmp_tui.rst b/docs/qemu.qmp.aqmp_tui.rst
deleted file mode 100644
index a5c55f9..0000000
--- a/docs/qemu.qmp.aqmp_tui.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-qemu.qmp.aqmp\_tui module
-=========================
-
-.. automodule:: qemu.qmp.aqmp_tui
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/qemu.qmp.error.rst b/docs/qemu.qmp.error.rst
index 89f069d..5105330 100644
--- a/docs/qemu.qmp.error.rst
+++ b/docs/qemu.qmp.error.rst
@@ -5,3 +5,4 @@ qemu.qmp.error module
    :members:
    :undoc-members:
    :show-inheritance:
+   :member-order: bysource
diff --git a/docs/qemu.qmp.message.rst b/docs/qemu.qmp.message.rst
index 765ae63..b824dc6 100644
--- a/docs/qemu.qmp.message.rst
+++ b/docs/qemu.qmp.message.rst
@@ -5,3 +5,4 @@ qemu.qmp.message module
    :members:
    :undoc-members:
    :show-inheritance:
+   :member-order: bysource
diff --git a/docs/qemu.qmp.models.rst b/docs/qemu.qmp.models.rst
index 55585b7..1e2f608 100644
--- a/docs/qemu.qmp.models.rst
+++ b/docs/qemu.qmp.models.rst
@@ -5,3 +5,4 @@ qemu.qmp.models module
    :members:
    :undoc-members:
    :show-inheritance:
+   :member-order: bysource
diff --git a/docs/qemu.qmp.protocol.rst b/docs/qemu.qmp.protocol.rst
index fca55ad..947e15f 100644
--- a/docs/qemu.qmp.protocol.rst
+++ b/docs/qemu.qmp.protocol.rst
@@ -5,3 +5,5 @@ qemu.qmp.protocol module
    :members:
    :undoc-members:
    :show-inheritance:
+   :private-members:
+   :member-order: bysource
diff --git a/docs/qemu.qmp.qmp_client.rst b/docs/qemu.qmp.qmp_client.rst
index 1d5beda..83b8101 100644
--- a/docs/qemu.qmp.qmp_client.rst
+++ b/docs/qemu.qmp.qmp_client.rst
@@ -5,3 +5,4 @@ qemu.qmp.qmp\_client module
    :members:
    :undoc-members:
    :show-inheritance:
+   :member-order: bysource
diff --git a/docs/qemu.qmp.qmp_shell.rst b/docs/qemu.qmp.qmp_shell.rst
deleted file mode 100644
index 0510cd3..0000000
--- a/docs/qemu.qmp.qmp_shell.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-qemu.qmp.qmp\_shell module
-==========================
-
-.. automodule:: qemu.qmp.qmp_shell
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/qemu.qmp.rst b/docs/qemu.qmp.rst
index 305e5b0..d1d2cd3 100644
--- a/docs/qemu.qmp.rst
+++ b/docs/qemu.qmp.rst
@@ -1,10 +1,12 @@
-qemu.qmp package
-================
+qemu.qmp - Asynchronous QEMU Monitor Protocol (QMP) library
+===========================================================
 
 .. automodule:: qemu.qmp
    :members:
    :undoc-members:
    :show-inheritance:
+   :noindex:
+   :member-order: bysource
 
 Submodules
 ----------
@@ -12,7 +14,6 @@ Submodules
 .. toctree::
    :maxdepth: 4
 
-   qemu.qmp.aqmp_tui
    qemu.qmp.error
    qemu.qmp.events
    qemu.qmp.legacy
@@ -20,5 +21,4 @@ Submodules
    qemu.qmp.models
    qemu.qmp.protocol
    qemu.qmp.qmp_client
-   qemu.qmp.qmp_shell
    qemu.qmp.util
diff --git a/docs/qemu.qmp.util.rst b/docs/qemu.qmp.util.rst
index 8f2ac87..24a6f82 100644
--- a/docs/qemu.qmp.util.rst
+++ b/docs/qemu.qmp.util.rst
@@ -5,3 +5,4 @@ qemu.qmp.util module
    :members:
    :undoc-members:
    :show-inheritance:
+   :member-order: bysource
diff --git a/docs/qemu.rst b/docs/qemu.rst
deleted file mode 100644
index f33a4f4..0000000
--- a/docs/qemu.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-qemu namespace
-==============
-
-Subpackages
------------
-
-.. toctree::
-   :maxdepth: 4
-
-   qemu.qmp
-- 
2.31.1

[RFC qemu.qmp PATCH 21/24] Fix doc cross-reference regressions

[John Snow]

Before enabling docs building as a CI step, lingering cross-reference
failures need to be addressed.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qemu/qmp/legacy.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qemu/qmp/legacy.py b/qemu/qmp/legacy.py
index 6c250cd..8e976f9 100644
--- a/qemu/qmp/legacy.py
+++ b/qemu/qmp/legacy.py
@@ -71,7 +71,7 @@ class QEMUMonitorProtocol:
     :param nickname: Optional nickname used for logging.
 
     ..note::
-        No connection is established during `__init__`, this is done by
+        No connection is established during ``__init__``, this is done by
         the `connect()` or `accept()` methods.
     """
 
@@ -287,7 +287,7 @@ class QEMUMonitorProtocol:
         Set the timeout for QMP RPC execution.
 
         This timeout affects the `cmd`, `cmd_obj`, and `command` methods.
-        The `accept`, `pull_event` and `get_event` methods have their
+        The `accept`, `pull_event` and `get_events` methods have their
         own configurable timeouts.
 
         :param timeout:
-- 
2.31.1

[RFC qemu.qmp PATCH 22/24] docs: add Makefile target

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 Makefile | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Makefile b/Makefile
index 81bfca8..029a824 100644
--- a/Makefile
+++ b/Makefile
@@ -103,6 +103,7 @@ check-coverage:
 clean:
 	python3 setup.py clean --all
 	rm -f pyproject.toml
+	make -C docs clean
 
 .PHONY: distclean
 distclean: clean
@@ -142,3 +143,7 @@ publish: pre-publish
 .PHONY: publish-test
 publish-test: pre-publish
 	python3 -m twine upload --verbose -r testpypi dist/*
+
+.PHONY: docs
+docs:
+	make -C docs html
-- 
2.31.1

[RFC qemu.qmp PATCH 23/24] docs: add doc build to GitLab CI build step

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 .gitlab-ci.d/build.yml         | 1 +
 .gitlab-ci.d/python.Dockerfile | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/.gitlab-ci.d/build.yml b/.gitlab-ci.d/build.yml
index bf2d487..5634173 100644
--- a/.gitlab-ci.d/build.yml
+++ b/.gitlab-ci.d/build.yml
@@ -4,6 +4,7 @@ build-package:
   needs:
     job: python-container
   script:
+    - make docs
     - python3 -m build
   artifacts:
     name: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG-$CI_COMMIT_SHORT_SHA"
diff --git a/.gitlab-ci.d/python.Dockerfile b/.gitlab-ci.d/python.Dockerfile
index 93661b2..728d8d8 100644
--- a/.gitlab-ci.d/python.Dockerfile
+++ b/.gitlab-ci.d/python.Dockerfile
@@ -15,6 +15,8 @@ RUN dnf --setopt=install_weak_deps=False install -y \
         pipenv \
         python3 \
         python3-pip \
+        python3-sphinx \
+        python3-sphinx_rtd_theme \
         python3-tox \
         python3-virtualenv \
         python3.10 \
-- 
2.31.1

[RFC qemu.qmp PATCH 24/24] v0.0.1

[John Snow]

Add v0.0.1 tag, marking the first public alpha release of the qemu.qmp
package.
---
 README.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/README.rst b/README.rst
index bd4a301..e82ac03 100644
--- a/README.rst
+++ b/README.rst
@@ -126,4 +126,7 @@ locally before submitting to GitLab CI as my due diligence.)
 Changelog
 ---------
 
-- No public release yet.
+0.0.1 (2022-xx-xx)
+^^^^^^^^^^^^^^^^^^
+
+- Initial public release.
-- 
2.31.1

Re: [RFC qemu.qmp PATCH 00/24] Python: Fork qemu.qmp Python lib into independent repo

[Daniel P. Berrangé]

On Wed, Dec 15, 2021 at 04:06:10PM -0500, John Snow wrote:
> Hi, this series is part of an effort to publish the qemu.qmp package on
> PyPI. It is the second of three series to complete this work:
> 
>     (1) Switch the new Async QMP library in to python/qemu/qmp
> --> (2) Fork python/qemu/qmp out into its own repository,
>         with updated GitLab CI/CD targets to build packages.
>     (3) Update qemu.git to install qemu.qmp from PyPI,
>         and then delete python/qemu/qmp.
> 
> This series is not meant to apply to qemu.git, rather -- it's the series
> that performs the split and would apply to a brand new repository.
> 
> I am submitting it to the QEMU mailing list for these reasons:
> 
> (1) To more broadly announce my intentions, and as reference alongside
> series #1 and #3 detailed above.
> 
> (2) To ask for permission to become the maintainer of a
> 'qemu-project/qemu.qmp' repository, where I would like to host this
> subproject.

I'd say we need 3 designated maintainers as a minimum for redundancy.

> (3) To ask for review on the README.rst file which details my intended
> contribution guidelines for this subproject.
> 
> (4) To ask for review on the .gitlab-ci.d/ files and other repo-level
> CI/CD ephemera, including and especially the docs-building process.  I
> think the generated docs are still ugly, and I'd like to upload them to
> readthedocs, among other things -- hence the RFC quality of this series.

> Some review/RFC notes:
> 
> - I use jsnow/qemu.qmp as the repo name throughout the series; that will
>   have to be changed eventually, but for the purposes of prototyping, it
>   was nicer to have a fully working series.
> 
> - I'm planning on using gitlab issues and MRs for the subproject.

Great !

> - I plan to version this lib independently, starting at 0.0.1 for the
>   initial public release and bumping only the micro version for every
>   last release. I plan to bump the minor version once it hits a "beta"
>   state. There will be no cross-versioning against QEMU. I don't plan to
>   publish new releases during QEMU freezes.

IMHO if we're saying that QEMU is going to use this library straight
from PyPI from the start, then we're defacto considering it staable
from the start too. We can't accept changes published to PyPI that
are going to be incompatible with existing QEMU.

If that isn't acceptable, then QEMU is going to have to be pinned to
a very specific version from PyPi, and explicitly not pull the
latest.

> - Docs are not yet uploaded anywhere (GitLab pages, readthedocs?)

Since we're already using gitlab, personally I'd just setup a 'pages'
job and assign a qemu.org sub-domain to gitlab pages service.

> - Tags on a commit trigger two pipelines; this causes one of the package
>   builds to fail as the version number will be duplicated in this
>   case. Not entirely sure how I want to fix this yet ...

If you dont have any 'rules:' stanza gitlab creates a pipeline
for any 'push' event - this means pushes of branch commits or
pushes of tags.

To remove the duplicates we need to filter based on certain
standard variables - CI_COMMIT_BRANCH or CI_COMMIT_TAG

  rules:
    - if '$CI_PIPELINE_SOURCE != "push"'
      when: never
    - if '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'
      when: never
    - if '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'
      when: on_success
    - when: never
    

will cull jobs for pushes of branch commit, leaving pipelines
for tag pushes. It can get arbitrarily more complicated depending
on what you need to achieve.


Since we're going to use merge requests, we should be aiming to
*NOT* run pipelines on branch commit pushes for forks. We only
want pipelines attached to the merge request.

You'll need pipelines on pushes of tags for the post-merge publishing
jobs potentially, unless you want todo that on a nightly schedule

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [RFC qemu.qmp PATCH 03/24] Update maintainer metadata

[Daniel P. Berrangé]

On Wed, Dec 15, 2021 at 04:06:13PM -0500, John Snow wrote:
> I'm the primary author of this particular component; update the metadata
> accordingly.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  setup.cfg | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/setup.cfg b/setup.cfg
> index 9999bca..7cd8470 100644
> --- a/setup.cfg
> +++ b/setup.cfg
> @@ -1,7 +1,9 @@
>  [metadata]
>  name = qemu.qmp
>  version = file:VERSION
> -maintainer = QEMU Developer Team
> +author = John Snow
> +author_email = jsnow@redhat.com

Isn't the authorship of this more of a collaborative effort ?
IOW, shouldn't it just be "The QEMU Project" as for the
maintainer.

> +maintainer = QEMU Project
>  maintainer_email = qemu-devel@nongnu.org
>  url = https://www.qemu.org/
>  download_url = https://www.qemu.org/download/

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [RFC qemu.qmp PATCH 17/24] Makefile: add build and publish targets

[Daniel P. Berrangé]

On Wed, Dec 15, 2021 at 04:06:27PM -0500, John Snow wrote:
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  Makefile | 32 ++++++++++++++++++++++++++++++++
>  1 file changed, 32 insertions(+)
> 
> diff --git a/Makefile b/Makefile
> index 97d737a..81bfca8 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -110,3 +110,35 @@ distclean: clean
>  	rm -f .coverage .coverage.*
>  	rm -rf htmlcov/
>  	rm -rf test-results/
> +
> +.PHONY: pristine
> +pristine:
> +	@git diff-files --quiet --ignore-submodules -- || \
> +		(echo "You have unstaged changes."; exit 1)
> +	@git diff-index --cached --quiet HEAD --ignore-submodules -- || \
> +		(echo "Your index contains uncommitted changes."; exit 1)
> +	@[ -z "$(shell git ls-files -o)" ] || \
> +		(echo "You have untracked files: $(shell git ls-files -o)"; exit 1)
> +
> +dist: setup.cfg setup.py Makefile README.rst
> +	python3 -m build
> +	@touch dist
> +
> +.PHONY: pre-publish
> +pre-publish: pristine dist
> +	@git describe --exact-match 2>/dev/null || \
> +		(echo -e "\033[0;31mThere is no annotated tag for this commit.\033[0m"; exit 1)
> +	python3 -m twine check --strict dist/*
> +	git push -v --atomic --follow-tags --dry-run
> +
> +.PHONY: publish
> +publish: pre-publish
> +	# Set the username via TWINE_USERNAME.
> +	# Set the password via TWINE_PASSWORD.
> +	# Set the pkg repository via TWINE_REPOSITORY.
> +	python3 -m twine upload --verbose dist/*
> +	git push -v --atomic --follow-tags
> +
> +.PHONY: publish-test
> +publish-test: pre-publish
> +	python3 -m twine upload --verbose -r testpypi dist/*

It doesn't feel very pythonic to have a makefile in the project.

If we want some helpers for publishing releases, I would have
expected to see a python script  eg scripts/publish.py 

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [RFC qemu.qmp PATCH 00/24] Python: Fork qemu.qmp Python lib into independent repo

[John Snow]

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

On Thu, Dec 16, 2021 at 5:41 AM Daniel P. Berrangé <berrange@redhat.com>
wrote:

> On Wed, Dec 15, 2021 at 04:06:10PM -0500, John Snow wrote:
> > Hi, this series is part of an effort to publish the qemu.qmp package on
> > PyPI. It is the second of three series to complete this work:
> >
> >     (1) Switch the new Async QMP library in to python/qemu/qmp
> > --> (2) Fork python/qemu/qmp out into its own repository,
> >         with updated GitLab CI/CD targets to build packages.
> >     (3) Update qemu.git to install qemu.qmp from PyPI,
> >         and then delete python/qemu/qmp.
> >
> > This series is not meant to apply to qemu.git, rather -- it's the series
> > that performs the split and would apply to a brand new repository.
> >
> > I am submitting it to the QEMU mailing list for these reasons:
> >
> > (1) To more broadly announce my intentions, and as reference alongside
> > series #1 and #3 detailed above.
> >
> > (2) To ask for permission to become the maintainer of a
> > 'qemu-project/qemu.qmp' repository, where I would like to host this
> > subproject.
>
> I'd say we need 3 designated maintainers as a minimum for redundancy.
>

Fine by me -- I'd like to nominate Cleber as my current co-maintainer of
python/, but that leaves a third spot open. Cleber may decide to nominate
someone else who is working on Avocado, too -- that'd be good too. If there
was a third person who wasn't @redhat.com, that'd be nice, but nobody comes
to mind right away. Any volunteers?

Also, I can hand over control of the PyPI project(s) to the conservancy and
use revocable auth tokens to perform releases. We'll cross that bridge when
we get there, but I've looked into it.


>
> > (3) To ask for review on the README.rst file which details my intended
> > contribution guidelines for this subproject.
> >
> > (4) To ask for review on the .gitlab-ci.d/ files and other repo-level
> > CI/CD ephemera, including and especially the docs-building process.  I
> > think the generated docs are still ugly, and I'd like to upload them to
> > readthedocs, among other things -- hence the RFC quality of this series.
>
> > Some review/RFC notes:
> >
> > - I use jsnow/qemu.qmp as the repo name throughout the series; that will
> >   have to be changed eventually, but for the purposes of prototyping, it
> >   was nicer to have a fully working series.
> >
> > - I'm planning on using gitlab issues and MRs for the subproject.
>
> Great !
>
>
It's just easier for me, and I suspect it would be easier for non-QEMU
contributors to use. I'm starting to try and target people that sit a
little further out from our core project, so it seemed like it'd make the
most sense.

I'll have to work out how to announce changes to the list, though ... maybe
I'll have a bot announce merge requests to the mailing list, I'm not sure.


> > - I plan to version this lib independently, starting at 0.0.1 for the
> >   initial public release and bumping only the micro version for every
> >   last release. I plan to bump the minor version once it hits a "beta"
> >   state. There will be no cross-versioning against QEMU. I don't plan to
> >   publish new releases during QEMU freezes.
>
> IMHO if we're saying that QEMU is going to use this library straight
> from PyPI from the start, then we're defacto considering it staable
> from the start too. We can't accept changes published to PyPI that
> are going to be incompatible with existing QEMU.
>
> If that isn't acceptable, then QEMU is going to have to be pinned to
> a very specific version from PyPi, and explicitly not pull the
> latest.
>
>
Right, I was thinking of pinning against a specific version. I want to
retain the freedom to change the API for a little while. I was worried that
if I tried to make it perfect before publishing it, that I'd never actually
make it perfect OR publish it.
My plan is something like this:

- Increment the micro version for any change during the "alpha" period
- Once I remove legacy.py and add a proper sync layer (Which may involve
some rework of how the event listeners are factored) I want to version at
0.1.0 and call it "beta". From there, compatible changes and extensions
will bump the micro and incompatible changes will bump the minor.
- After a QEMU release or two with the beta version and no major problems,
I'll probably bump it to 1.0.0, call it stable, and then use semver "as
normal" for all future releases.


> > - Docs are not yet uploaded anywhere (GitLab pages, readthedocs?)
>
> Since we're already using gitlab, personally I'd just setup a 'pages'
> job and assign a qemu.org sub-domain to gitlab pages service.
>
>
I'll work on a pages job at least, then. I'll look at what you've written
for qemu and qemu-web and do some copy-pasting.


> > - Tags on a commit trigger two pipelines; this causes one of the package
> >   builds to fail as the version number will be duplicated in this
> >   case. Not entirely sure how I want to fix this yet ...
>
> If you dont have any 'rules:' stanza gitlab creates a pipeline
> for any 'push' event - this means pushes of branch commits or
> pushes of tags.
>
> To remove the duplicates we need to filter based on certain
> standard variables - CI_COMMIT_BRANCH or CI_COMMIT_TAG
>
>   rules:
>     - if '$CI_PIPELINE_SOURCE != "push"'
>       when: never
>     - if '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'
>       when: never
>     - if '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'
>       when: on_success
>     - when: never
>
>
> will cull jobs for pushes of branch commit, leaving pipelines
> for tag pushes. It can get arbitrarily more complicated depending
> on what you need to achieve.
>

OK, I'll play around with it -- thanks


> Since we're going to use merge requests, we should be aiming to
> *NOT* run pipelines on branch commit pushes for forks. We only
> want pipelines attached to the merge request.
>
> You'll need pipelines on pushes of tags for the post-merge publishing
> jobs potentially, unless you want todo that on a nightly schedule
>
> Regards,
> Daniel
>
>
Thanks for taking a peek!

(looks at email inbox ... well, this is gonna take a second to unpack ...!)

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

Re: [RFC qemu.qmp PATCH 03/24] Update maintainer metadata

[John Snow]

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

On Thu, Dec 16, 2021 at 5:43 AM Daniel P. Berrangé <berrange@redhat.com>
wrote:

> On Wed, Dec 15, 2021 at 04:06:13PM -0500, John Snow wrote:
> > I'm the primary author of this particular component; update the metadata
> > accordingly.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  setup.cfg | 4 +++-
> >  1 file changed, 3 insertions(+), 1 deletion(-)
> >
> > diff --git a/setup.cfg b/setup.cfg
> > index 9999bca..7cd8470 100644
> > --- a/setup.cfg
> > +++ b/setup.cfg
> > @@ -1,7 +1,9 @@
> >  [metadata]
> >  name = qemu.qmp
> >  version = file:VERSION
> > -maintainer = QEMU Developer Team
> > +author = John Snow
> > +author_email = jsnow@redhat.com
>
> Isn't the authorship of this more of a collaborative effort ?
> IOW, shouldn't it just be "The QEMU Project" as for the
> maintainer.
>

Sorta. The code in this specific package is > 95% written by me, so I felt
the authorship credit here was roughly appropriate. So, I put myself as the
"Author" but "QEMU Project" as the "maintainer". I put a lot of work into
this, so it felt weird to say that it was authored by a mailing list.

I also wanted to avoid not listing my own name at all, since this has
largely been my initiative to polish it up, write docs, and split it out --
it feels rude to just dump responsibility straight back on the list and
pretend I'm not the point of contact for it.

>
> > +maintainer = QEMU Project
> >  maintainer_email = qemu-devel@nongnu.org
> >  url = https://www.qemu.org/
> >  download_url = https://www.qemu.org/download/
>
> Regards,
> Daniel
> --
> |: https://berrange.com      -o-
> https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org         -o-
> https://fstop138.berrange.com :|
> |: https://entangle-photo.org    -o-
> https://www.instagram.com/dberrange :|
>
>

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

Re: [RFC qemu.qmp PATCH 17/24] Makefile: add build and publish targets

[John Snow]

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

On Thu, Dec 16, 2021 at 5:48 AM Daniel P. Berrangé <berrange@redhat.com>
wrote:

> On Wed, Dec 15, 2021 at 04:06:27PM -0500, John Snow wrote:
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  Makefile | 32 ++++++++++++++++++++++++++++++++
> >  1 file changed, 32 insertions(+)
> >
> > diff --git a/Makefile b/Makefile
> > index 97d737a..81bfca8 100644
> > --- a/Makefile
> > +++ b/Makefile
> > @@ -110,3 +110,35 @@ distclean: clean
> >       rm -f .coverage .coverage.*
> >       rm -rf htmlcov/
> >       rm -rf test-results/
> > +
> > +.PHONY: pristine
> > +pristine:
> > +     @git diff-files --quiet --ignore-submodules -- || \
> > +             (echo "You have unstaged changes."; exit 1)
> > +     @git diff-index --cached --quiet HEAD --ignore-submodules -- || \
> > +             (echo "Your index contains uncommitted changes."; exit 1)
> > +     @[ -z "$(shell git ls-files -o)" ] || \
> > +             (echo "You have untracked files: $(shell git ls-files
> -o)"; exit 1)
> > +
> > +dist: setup.cfg setup.py Makefile README.rst
> > +     python3 -m build
> > +     @touch dist
> > +
> > +.PHONY: pre-publish
> > +pre-publish: pristine dist
> > +     @git describe --exact-match 2>/dev/null || \
> > +             (echo -e "\033[0;31mThere is no annotated tag for this
> commit.\033[0m"; exit 1)
> > +     python3 -m twine check --strict dist/*
> > +     git push -v --atomic --follow-tags --dry-run
> > +
> > +.PHONY: publish
> > +publish: pre-publish
> > +     # Set the username via TWINE_USERNAME.
> > +     # Set the password via TWINE_PASSWORD.
> > +     # Set the pkg repository via TWINE_REPOSITORY.
> > +     python3 -m twine upload --verbose dist/*
> > +     git push -v --atomic --follow-tags
> > +
> > +.PHONY: publish-test
> > +publish-test: pre-publish
> > +     python3 -m twine upload --verbose -r testpypi dist/*
>
> It doesn't feel very pythonic to have a makefile in the project.
>
> If we want some helpers for publishing releases, I would have
> expected to see a python script  eg scripts/publish.py
>
>
Eh, Python folks use Makefiles too. I've been using these little Makefile
targets for hobby things for a while and I had them laying around and ready
to go. I have no strong need to "upgrade" to python scripts for these right
now, unless there's some extra features you want to see.

--js

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

Re: [RFC qemu.qmp PATCH 17/24] Makefile: add build and publish targets

[Daniel P. Berrangé]

On Thu, Dec 16, 2021 at 06:35:23PM -0500, John Snow wrote:
> On Thu, Dec 16, 2021 at 5:48 AM Daniel P. Berrangé <berrange@redhat.com>
> wrote:
> 
> > On Wed, Dec 15, 2021 at 04:06:27PM -0500, John Snow wrote:
> > > Signed-off-by: John Snow <jsnow@redhat.com>
> > > ---
> > >  Makefile | 32 ++++++++++++++++++++++++++++++++
> > >  1 file changed, 32 insertions(+)
> > >
> > > diff --git a/Makefile b/Makefile
> > > index 97d737a..81bfca8 100644
> > > --- a/Makefile
> > > +++ b/Makefile
> > > @@ -110,3 +110,35 @@ distclean: clean
> > >       rm -f .coverage .coverage.*
> > >       rm -rf htmlcov/
> > >       rm -rf test-results/
> > > +
> > > +.PHONY: pristine
> > > +pristine:
> > > +     @git diff-files --quiet --ignore-submodules -- || \
> > > +             (echo "You have unstaged changes."; exit 1)
> > > +     @git diff-index --cached --quiet HEAD --ignore-submodules -- || \
> > > +             (echo "Your index contains uncommitted changes."; exit 1)
> > > +     @[ -z "$(shell git ls-files -o)" ] || \
> > > +             (echo "You have untracked files: $(shell git ls-files
> > -o)"; exit 1)
> > > +
> > > +dist: setup.cfg setup.py Makefile README.rst
> > > +     python3 -m build
> > > +     @touch dist
> > > +
> > > +.PHONY: pre-publish
> > > +pre-publish: pristine dist
> > > +     @git describe --exact-match 2>/dev/null || \
> > > +             (echo -e "\033[0;31mThere is no annotated tag for this
> > commit.\033[0m"; exit 1)
> > > +     python3 -m twine check --strict dist/*
> > > +     git push -v --atomic --follow-tags --dry-run
> > > +
> > > +.PHONY: publish
> > > +publish: pre-publish
> > > +     # Set the username via TWINE_USERNAME.
> > > +     # Set the password via TWINE_PASSWORD.
> > > +     # Set the pkg repository via TWINE_REPOSITORY.
> > > +     python3 -m twine upload --verbose dist/*
> > > +     git push -v --atomic --follow-tags
> > > +
> > > +.PHONY: publish-test
> > > +publish-test: pre-publish
> > > +     python3 -m twine upload --verbose -r testpypi dist/*
> >
> > It doesn't feel very pythonic to have a makefile in the project.
> >
> > If we want some helpers for publishing releases, I would have
> > expected to see a python script  eg scripts/publish.py
> >
> >
> Eh, Python folks use Makefiles too. I've been using these little Makefile
> targets for hobby things for a while and I had them laying around and ready
> to go. I have no strong need to "upgrade" to python scripts for these right
> now, unless there's some extra features you want to see.

Using make means you have to worry about portability across different
impls of make and different impls of shell. Using python means your
python project is portable to anywhere that python runs.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [RFC qemu.qmp PATCH 17/24] Makefile: add build and publish targets

[John Snow]

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

On Fri, Dec 17, 2021 at 8:46 AM Daniel P. Berrangé <berrange@redhat.com>
wrote:

> On Thu, Dec 16, 2021 at 06:35:23PM -0500, John Snow wrote:
> > On Thu, Dec 16, 2021 at 5:48 AM Daniel P. Berrangé <berrange@redhat.com>
> > wrote:
> >
> > > On Wed, Dec 15, 2021 at 04:06:27PM -0500, John Snow wrote:
> > > > Signed-off-by: John Snow <jsnow@redhat.com>
> > > > ---
> > > >  Makefile | 32 ++++++++++++++++++++++++++++++++
> > > >  1 file changed, 32 insertions(+)
> > > >
> > > > diff --git a/Makefile b/Makefile
> > > > index 97d737a..81bfca8 100644
> > > > --- a/Makefile
> > > > +++ b/Makefile
> > > > @@ -110,3 +110,35 @@ distclean: clean
> > > >       rm -f .coverage .coverage.*
> > > >       rm -rf htmlcov/
> > > >       rm -rf test-results/
> > > > +
> > > > +.PHONY: pristine
> > > > +pristine:
> > > > +     @git diff-files --quiet --ignore-submodules -- || \
> > > > +             (echo "You have unstaged changes."; exit 1)
> > > > +     @git diff-index --cached --quiet HEAD --ignore-submodules --
> || \
> > > > +             (echo "Your index contains uncommitted changes."; exit
> 1)
> > > > +     @[ -z "$(shell git ls-files -o)" ] || \
> > > > +             (echo "You have untracked files: $(shell git ls-files
> > > -o)"; exit 1)
> > > > +
> > > > +dist: setup.cfg setup.py Makefile README.rst
> > > > +     python3 -m build
> > > > +     @touch dist
> > > > +
> > > > +.PHONY: pre-publish
> > > > +pre-publish: pristine dist
> > > > +     @git describe --exact-match 2>/dev/null || \
> > > > +             (echo -e "\033[0;31mThere is no annotated tag for this
> > > commit.\033[0m"; exit 1)
> > > > +     python3 -m twine check --strict dist/*
> > > > +     git push -v --atomic --follow-tags --dry-run
> > > > +
> > > > +.PHONY: publish
> > > > +publish: pre-publish
> > > > +     # Set the username via TWINE_USERNAME.
> > > > +     # Set the password via TWINE_PASSWORD.
> > > > +     # Set the pkg repository via TWINE_REPOSITORY.
> > > > +     python3 -m twine upload --verbose dist/*
> > > > +     git push -v --atomic --follow-tags
> > > > +
> > > > +.PHONY: publish-test
> > > > +publish-test: pre-publish
> > > > +     python3 -m twine upload --verbose -r testpypi dist/*
> > >
> > > It doesn't feel very pythonic to have a makefile in the project.
> > >
> > > If we want some helpers for publishing releases, I would have
> > > expected to see a python script  eg scripts/publish.py
> > >
> > >
> > Eh, Python folks use Makefiles too. I've been using these little Makefile
> > targets for hobby things for a while and I had them laying around and
> ready
> > to go. I have no strong need to "upgrade" to python scripts for these
> right
> > now, unless there's some extra features you want to see.
>
> Using make means you have to worry about portability across different
> impls of make and different impls of shell. Using python means your
> python project is portable to anywhere that python runs.


I still like the idea of using a Makefile as a "canonical menu of things
you can do in this directory", but there's probably room for interactive
error checking and so on with the TWINE_USERNAME / TWINE_PASSWORD /
TWINE_REPOSITORY environment variables in a python script. I'll look into
it as a follow-up, if that's fine. (I'm worried it's a lot of polish and
effort on a maintainers-only interface that only I will likely use for at
least the next year or two.)

Ultimately, what's likely to happen here is that I will generate some oauth
tokens with publish permissions and a hypothetical user would set e.g.
TWINE_USERNAME to "__token__", and the password would be
"pypi-tokengoeshere". Using the "keyring" python package, we could attempt
to fetch stored values from a session keyring, falling back to an
interactive prompt if they're unset.

--js

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

Re: [RFC qemu.qmp PATCH 17/24] Makefile: add build and publish targets

[Daniel P. Berrangé]

On Tue, Jan 11, 2022 at 02:48:55PM -0500, John Snow wrote:
> On Fri, Dec 17, 2021 at 8:46 AM Daniel P. Berrangé <berrange@redhat.com>
> wrote:
> 
> > On Thu, Dec 16, 2021 at 06:35:23PM -0500, John Snow wrote:
> > > On Thu, Dec 16, 2021 at 5:48 AM Daniel P. Berrangé <berrange@redhat.com>
> > > wrote:
> > >
> > > > On Wed, Dec 15, 2021 at 04:06:27PM -0500, John Snow wrote:
> > > > > Signed-off-by: John Snow <jsnow@redhat.com>
> > > > > ---
> > > > >  Makefile | 32 ++++++++++++++++++++++++++++++++
> > > > >  1 file changed, 32 insertions(+)
> > > > >
> > > > > diff --git a/Makefile b/Makefile
> > > > > index 97d737a..81bfca8 100644
> > > > > --- a/Makefile
> > > > > +++ b/Makefile
> > > > > @@ -110,3 +110,35 @@ distclean: clean
> > > > >       rm -f .coverage .coverage.*
> > > > >       rm -rf htmlcov/
> > > > >       rm -rf test-results/
> > > > > +
> > > > > +.PHONY: pristine
> > > > > +pristine:
> > > > > +     @git diff-files --quiet --ignore-submodules -- || \
> > > > > +             (echo "You have unstaged changes."; exit 1)
> > > > > +     @git diff-index --cached --quiet HEAD --ignore-submodules --
> > || \
> > > > > +             (echo "Your index contains uncommitted changes."; exit
> > 1)
> > > > > +     @[ -z "$(shell git ls-files -o)" ] || \
> > > > > +             (echo "You have untracked files: $(shell git ls-files
> > > > -o)"; exit 1)
> > > > > +
> > > > > +dist: setup.cfg setup.py Makefile README.rst
> > > > > +     python3 -m build
> > > > > +     @touch dist
> > > > > +
> > > > > +.PHONY: pre-publish
> > > > > +pre-publish: pristine dist
> > > > > +     @git describe --exact-match 2>/dev/null || \
> > > > > +             (echo -e "\033[0;31mThere is no annotated tag for this
> > > > commit.\033[0m"; exit 1)
> > > > > +     python3 -m twine check --strict dist/*
> > > > > +     git push -v --atomic --follow-tags --dry-run
> > > > > +
> > > > > +.PHONY: publish
> > > > > +publish: pre-publish
> > > > > +     # Set the username via TWINE_USERNAME.
> > > > > +     # Set the password via TWINE_PASSWORD.
> > > > > +     # Set the pkg repository via TWINE_REPOSITORY.
> > > > > +     python3 -m twine upload --verbose dist/*
> > > > > +     git push -v --atomic --follow-tags
> > > > > +
> > > > > +.PHONY: publish-test
> > > > > +publish-test: pre-publish
> > > > > +     python3 -m twine upload --verbose -r testpypi dist/*
> > > >
> > > > It doesn't feel very pythonic to have a makefile in the project.
> > > >
> > > > If we want some helpers for publishing releases, I would have
> > > > expected to see a python script  eg scripts/publish.py
> > > >
> > > >
> > > Eh, Python folks use Makefiles too. I've been using these little Makefile
> > > targets for hobby things for a while and I had them laying around and
> > ready
> > > to go. I have no strong need to "upgrade" to python scripts for these
> > right
> > > now, unless there's some extra features you want to see.
> >
> > Using make means you have to worry about portability across different
> > impls of make and different impls of shell. Using python means your
> > python project is portable to anywhere that python runs.
> 
> 
> I still like the idea of using a Makefile as a "canonical menu of things
> you can do in this directory", but there's probably room for interactive
> error checking and so on with the TWINE_USERNAME / TWINE_PASSWORD /
> TWINE_REPOSITORY environment variables in a python script. I'll look into
> it as a follow-up, if that's fine. (I'm worried it's a lot of polish and
> effort on a maintainers-only interface that only I will likely use for at
> least the next year or two.)
> 
> Ultimately, what's likely to happen here is that I will generate some oauth
> tokens with publish permissions and a hypothetical user would set e.g.
> TWINE_USERNAME to "__token__", and the password would be
> "pypi-tokengoeshere". Using the "keyring" python package, we could attempt
> to fetch stored values from a session keyring, falling back to an
> interactive prompt if they're unset.

FWIW, don't consider this original comment of mine to be a technical
blocker, rather it is more of a conceptual observation.  If you don't
think it matters, I won't mind.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [RFC qemu.qmp PATCH 17/24] Makefile: add build and publish targets

[John Snow]

On Wed, Jan 12, 2022 at 5:07 AM Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Tue, Jan 11, 2022 at 02:48:55PM -0500, John Snow wrote:
> > On Fri, Dec 17, 2021 at 8:46 AM Daniel P. Berrangé <berrange@redhat.com>
> > wrote:
> >
> > > On Thu, Dec 16, 2021 at 06:35:23PM -0500, John Snow wrote:
> > > > On Thu, Dec 16, 2021 at 5:48 AM Daniel P. Berrangé <berrange@redhat.com>
> > > > wrote:
> > > >
> > > > > On Wed, Dec 15, 2021 at 04:06:27PM -0500, John Snow wrote:
> > > > > > Signed-off-by: John Snow <jsnow@redhat.com>
> > > > > > ---
> > > > > >  Makefile | 32 ++++++++++++++++++++++++++++++++
> > > > > >  1 file changed, 32 insertions(+)
> > > > > >
> > > > > > diff --git a/Makefile b/Makefile
> > > > > > index 97d737a..81bfca8 100644
> > > > > > --- a/Makefile
> > > > > > +++ b/Makefile
> > > > > > @@ -110,3 +110,35 @@ distclean: clean
> > > > > >       rm -f .coverage .coverage.*
> > > > > >       rm -rf htmlcov/
> > > > > >       rm -rf test-results/
> > > > > > +
> > > > > > +.PHONY: pristine
> > > > > > +pristine:
> > > > > > +     @git diff-files --quiet --ignore-submodules -- || \
> > > > > > +             (echo "You have unstaged changes."; exit 1)
> > > > > > +     @git diff-index --cached --quiet HEAD --ignore-submodules --
> > > || \
> > > > > > +             (echo "Your index contains uncommitted changes."; exit
> > > 1)
> > > > > > +     @[ -z "$(shell git ls-files -o)" ] || \
> > > > > > +             (echo "You have untracked files: $(shell git ls-files
> > > > > -o)"; exit 1)
> > > > > > +
> > > > > > +dist: setup.cfg setup.py Makefile README.rst
> > > > > > +     python3 -m build
> > > > > > +     @touch dist
> > > > > > +
> > > > > > +.PHONY: pre-publish
> > > > > > +pre-publish: pristine dist
> > > > > > +     @git describe --exact-match 2>/dev/null || \
> > > > > > +             (echo -e "\033[0;31mThere is no annotated tag for this
> > > > > commit.\033[0m"; exit 1)
> > > > > > +     python3 -m twine check --strict dist/*
> > > > > > +     git push -v --atomic --follow-tags --dry-run
> > > > > > +
> > > > > > +.PHONY: publish
> > > > > > +publish: pre-publish
> > > > > > +     # Set the username via TWINE_USERNAME.
> > > > > > +     # Set the password via TWINE_PASSWORD.
> > > > > > +     # Set the pkg repository via TWINE_REPOSITORY.
> > > > > > +     python3 -m twine upload --verbose dist/*
> > > > > > +     git push -v --atomic --follow-tags
> > > > > > +
> > > > > > +.PHONY: publish-test
> > > > > > +publish-test: pre-publish
> > > > > > +     python3 -m twine upload --verbose -r testpypi dist/*
> > > > >
> > > > > It doesn't feel very pythonic to have a makefile in the project.
> > > > >
> > > > > If we want some helpers for publishing releases, I would have
> > > > > expected to see a python script  eg scripts/publish.py
> > > > >
> > > > >
> > > > Eh, Python folks use Makefiles too. I've been using these little Makefile
> > > > targets for hobby things for a while and I had them laying around and
> > > ready
> > > > to go. I have no strong need to "upgrade" to python scripts for these
> > > right
> > > > now, unless there's some extra features you want to see.
> > >
> > > Using make means you have to worry about portability across different
> > > impls of make and different impls of shell. Using python means your
> > > python project is portable to anywhere that python runs.
> >
> >
> > I still like the idea of using a Makefile as a "canonical menu of things
> > you can do in this directory", but there's probably room for interactive
> > error checking and so on with the TWINE_USERNAME / TWINE_PASSWORD /
> > TWINE_REPOSITORY environment variables in a python script. I'll look into
> > it as a follow-up, if that's fine. (I'm worried it's a lot of polish and
> > effort on a maintainers-only interface that only I will likely use for at
> > least the next year or two.)
> >
> > Ultimately, what's likely to happen here is that I will generate some oauth
> > tokens with publish permissions and a hypothetical user would set e.g.
> > TWINE_USERNAME to "__token__", and the password would be
> > "pypi-tokengoeshere". Using the "keyring" python package, we could attempt
> > to fetch stored values from a session keyring, falling back to an
> > interactive prompt if they're unset.
>
> FWIW, don't consider this original comment of mine to be a technical
> blocker, rather it is more of a conceptual observation.  If you don't
> think it matters, I won't mind.
>

OK, thanks -- just didn't want to give the impression I was just
simply ignoring it, since I appreciate the look-over.

--js

Re: [RFC qemu.qmp PATCH 00/24] Python: Fork qemu.qmp Python lib into independent repo

[John Snow]

On Thu, Dec 16, 2021 at 5:41 AM Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Wed, Dec 15, 2021 at 04:06:10PM -0500, John Snow wrote:

> > (2) To ask for permission to become the maintainer of a
> > 'qemu-project/qemu.qmp' repository, where I would like to host this
> > subproject.
>
> I'd say we need 3 designated maintainers as a minimum for redundancy.

Let's see how many people we can get to volunteer. If it's part of the
qemu-project umbrella, I assume anyone with access to the entire
project as a whole can step in and re-assign permissions and do
emergency actions as needed, including stsquad, stefanha, etc. That
ought to be enough to get moving. If we want to add anyone for
operational redundancy, I'd be happy to add as many people that
volunteer :)

So: any volunteers? Cleber, Beraldo, Wainer? Anyone else?

I anticipate this to be extremely low traffic after the churn of
splitting it out is done with, it shouldn't be a big daily cost -- but
having some familiarity with the code would be good in case you need
to accept some urgent patches here and there.

--js