It is no longer simply possible to just use this directory as if it were
an installed package now that it has dependencies, so update the README
to reflect this.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 python/README.rst | 50 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 43 insertions(+), 7 deletions(-)

diff --git a/python/README.rst b/python/README.rst
index d62e71528d2..2accfd7760e 100644
--- a/python/README.rst
+++ b/python/README.rst
@@ -3,7 +3,17 @@ QEMU Python Tooling
 
 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).
+then by package (e.g. ``qemu/machine``, ``qemu/utils``, etc).
+
+These tools and libraries are installed to the QEMU configure-time
+Python virtual environment by default (see qemu.git/pythondeps.toml
+"tooling" group), and are available for use by any Python script
+executed by the build system. To have these libraries available for
+manual invocations of scripts, use of the "run" script executable in
+your build directory is recommended.
+
+General structure
+-----------------
 
 ``setup.py`` is used by ``pip`` to install this tooling to the current
 environment. ``setup.cfg`` provides the packaging configuration used by
@@ -20,9 +30,9 @@ 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
-doing, the installed package always reflects the latest version in your
-source tree.
+a forwarder that points to the source tree. In so doing, the installed
+package always reflects the latest version in your source tree. This is
+the mode used to install these packages at configure time.
 
 Installing ".[devel]" instead of "." will additionally pull in required
 packages for testing this package. They are not runtime requirements,
@@ -40,8 +50,18 @@ for more information.
 Using these packages without installing them
 --------------------------------------------
 
-These packages may be used without installing them first, by using one
-of two tricks:
+It is no longer recommended to try to use these packages without
+installing them to a virtual environment, but depending on your use
+case, it may still be possible to do.
+
+The "qemu.qmp" library is now hosted outside of the qemu.git repository,
+and the "qemu.machine" library that remains in-tree here has qemu.qmp as
+a dependency. It is possible to install "qemu.qmp" independently and
+then use the rest of these packages without installing them, but be
+advised that if future dependencies are introduced, bypassing the
+installation phase may introduce breakages to your script in the future.
+
+That said, you can use these packages without installing them by either:
 
 1. Set your PYTHONPATH environment variable to include this source
    directory, e.g. ``~/src/qemu/python``. See
@@ -61,8 +81,24 @@ invoke them without installation, you can invoke e.g.:
 
 ``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell``
 
+Or, with the runscript available in the QEMU build directory, simply:
+
+``> $builddir/run qmp-shell``
+
 The mappings between console script name and python module path can be
-found in ``setup.cfg``.
+found in ``setup.cfg``, but the console scripts available are listed
+here for reference:
+
+* ``qemu-ga-client``
+* ``qmp-shell``
+* ``qmp-shell-wrap``
+* ``qmp-tui`` (prototype urwid interface for async QMP)
+* ``qom``
+* ``qom-fuse`` (requires fusepy to be installed!)
+* ``qom-get``
+* ``qom-list``
+* ``qom-set``
+* ``qom-tree``
 
 
 Files in this directory
-- 
2.52.0

On Mon, Jan 19, 2026 at 04:27:42PM -0500, John Snow wrote:
> It is no longer simply possible to just use this directory as if it were
> an installed package now that it has dependencies, so update the README
> to reflect this.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  python/README.rst | 50 ++++++++++++++++++++++++++++++++++++++++-------
>  1 file changed, 43 insertions(+), 7 deletions(-)
> 
> diff --git a/python/README.rst b/python/README.rst
> index d62e71528d2..2accfd7760e 100644
> --- a/python/README.rst
> +++ b/python/README.rst
> @@ -3,7 +3,17 @@ QEMU Python Tooling
>  
>  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).
> +then by package (e.g. ``qemu/machine``, ``qemu/utils``, etc).
> +
> +These tools and libraries are installed to the QEMU configure-time
> +Python virtual environment by default (see qemu.git/pythondeps.toml
> +"tooling" group), and are available for use by any Python script
> +executed by the build system. To have these libraries available for
> +manual invocations of scripts, use of the "run" script executable in
> +your build directory is recommended.

s/executable//, it is just a "script"

> @@ -61,8 +81,24 @@ invoke them without installation, you can invoke e.g.:
>  
>  ``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell``
>  
> +Or, with the runscript available in the QEMU build directory, simply:

s/runscript/run script/

> +
> +``> $builddir/run qmp-shell``
> +
>  The mappings between console script name and python module path can be
> -found in ``setup.cfg``.
> +found in ``setup.cfg``, but the console scripts available are listed
> +here for reference:
> +
> +* ``qemu-ga-client``
> +* ``qmp-shell``
> +* ``qmp-shell-wrap``
> +* ``qmp-tui`` (prototype urwid interface for async QMP)
> +* ``qom``
> +* ``qom-fuse`` (requires fusepy to be installed!)
> +* ``qom-get``
> +* ``qom-list``
> +* ``qom-set``
> +* ``qom-tree``

Those scripts all exist in $GIT/scripts/qmp/.  Are you saying that
they get installed into the venv now ? If so, should this series
also delete scripts/qmp ?

With 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 :|

On Tue, Jan 20, 2026 at 4:05 AM Daniel P. Berrangé <berrange@redhat.com> wrote:
>
> On Mon, Jan 19, 2026 at 04:27:42PM -0500, John Snow wrote:
> > It is no longer simply possible to just use this directory as if it were
> > an installed package now that it has dependencies, so update the README
> > to reflect this.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  python/README.rst | 50 ++++++++++++++++++++++++++++++++++++++++-------
> >  1 file changed, 43 insertions(+), 7 deletions(-)
> >
> > diff --git a/python/README.rst b/python/README.rst
> > index d62e71528d2..2accfd7760e 100644
> > --- a/python/README.rst
> > +++ b/python/README.rst
> > @@ -3,7 +3,17 @@ QEMU Python Tooling
> >
> >  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).
> > +then by package (e.g. ``qemu/machine``, ``qemu/utils``, etc).
> > +
> > +These tools and libraries are installed to the QEMU configure-time
> > +Python virtual environment by default (see qemu.git/pythondeps.toml
> > +"tooling" group), and are available for use by any Python script
> > +executed by the build system. To have these libraries available for
> > +manual invocations of scripts, use of the "run" script executable in
> > +your build directory is recommended.
>
> s/executable//, it is just a "script"

ATM machine, HIV virus, LCD display ... (oops)

>
> > @@ -61,8 +81,24 @@ invoke them without installation, you can invoke e.g.:
> >
> >  ``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell``
> >
> > +Or, with the runscript available in the QEMU build directory, simply:
>
> s/runscript/run script/
>
> > +
> > +``> $builddir/run qmp-shell``
> > +
> >  The mappings between console script name and python module path can be
> > -found in ``setup.cfg``.
> > +found in ``setup.cfg``, but the console scripts available are listed
> > +here for reference:
> > +
> > +* ``qemu-ga-client``
> > +* ``qmp-shell``
> > +* ``qmp-shell-wrap``
> > +* ``qmp-tui`` (prototype urwid interface for async QMP)
> > +* ``qom``
> > +* ``qom-fuse`` (requires fusepy to be installed!)
> > +* ``qom-get``
> > +* ``qom-list``
> > +* ``qom-set``
> > +* ``qom-tree``
>
> Those scripts all exist in $GIT/scripts/qmp/.  Are you saying that
> they get installed into the venv now ? If so, should this series
> also delete scripts/qmp ?

Right, those files are all long since obsolete. For the past several
years, they've been simple forwarders to the real scripts. However, I
thought it was good to leave the stubs there for a little while to
teach people where they now live as a bid to increase discoverability
of the scripts. I was afraid that if I deleted them outright, they'd
become functionally invisible to most people. After all, we only JUST
added that run script, so it may not yet be established knowledge that
the meson development venv comes with various "goodies" that we
promise will work, so I was concerned people may not know how to find
them.

>
> With 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 :|
>