From nobody Wed Apr 1 22:11:56 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1771957146; cv=none; d=zohomail.com; s=zohoarc; b=OTFPx3futkOq677xvIfqMva2q3Y+c99tZvqDH/FGain0XR+RNOUYQGifbfMKbpqJMIkZh2hxmcWJuA7VjMwDqyS968jlYEjv7OTiY26beeQJL14lK+6f6N8732cHfRyvQ3zR3cqbzNNo5gaJ5ajwnHrhwAcXPA5IXkZTz8fAFQ0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1771957146; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=yDeGX1aJjGI3pOgX2jebP99BGCib0X/iSnfwWJTD2OE=; b=mF6BaZsU9j4bNvBVGPVL1sitjmLJUpu5gBB3AQGRq931wbVn8JniVDXyQxaxRU0fUyTh64w4QJFUPq2/biauNW++5zV91O0CG+HNcKJLbyC0cbYQfHCkIsk/4XsJW7XEotVHRaii3besvDm5hFyOb/PLSrY9RFDdaTdDknzcf0Q= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1771957146385376.8251512393193; Tue, 24 Feb 2026 10:19:06 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1vuwyW-0005yq-7j; Tue, 24 Feb 2026 13:17:36 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1vuwxk-0005KR-Vq for qemu-devel@nongnu.org; Tue, 24 Feb 2026 13:16:49 -0500 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1vuwxj-0002oU-A7 for qemu-devel@nongnu.org; Tue, 24 Feb 2026 13:16:48 -0500 Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-296-rh5k41cJPKCmXYhPuzYeDg-1; Tue, 24 Feb 2026 13:16:41 -0500 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 866C31955F24; Tue, 24 Feb 2026 18:16:39 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.89.212]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 5DAD51800666; Tue, 24 Feb 2026 18:16:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1771957006; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=yDeGX1aJjGI3pOgX2jebP99BGCib0X/iSnfwWJTD2OE=; b=KFKQUiAZ01JR/R4LGhERStO+M5Ia35nfLJVrW8CMkUQBQBbauRp+YFMnhy94VMSX6E5RPK IimLYsXvC7wNmVXjGcU/p7jYnhF8b2KUtC1KI8qUJrmqdojtEZIrjGzVg1h+ukyQKhiL7C 38X7GTSgMA2xMrDdP/J6exfYhoJX3G8= X-MC-Unique: rh5k41cJPKCmXYhPuzYeDg-1 X-Mimecast-MFC-AGG-ID: rh5k41cJPKCmXYhPuzYeDg_1771956999 From: John Snow To: qemu-devel@nongnu.org Cc: Vladimir Sementsov-Ogievskiy , Kyle Evans , Thomas Huth , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , John Snow , Warner Losh , Markus Armbruster , Michael Roth , Fabiano Rosas , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Maksim Davydov , Peter Maydell , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Peter Xu , Cleber Rosa , Ed Maste , qemu-block@nongnu.org, Li-Wen Hsu , Hanna Reitz , Mauro Carvalho Chehab , Kevin Wolf , Paolo Bonzini , Yonggang Luo , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Subject: [PULL v2 18/19] python: update README.rst to reflect qemu.qmp's removal Date: Tue, 24 Feb 2026 13:14:37 -0500 Message-ID: <20260224181440.832943-19-jsnow@redhat.com> In-Reply-To: <20260224181440.832943-1-jsnow@redhat.com> References: <20260224181440.832943-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -10 X-Spam_score: -1.1 X-Spam_bar: - X-Spam_report: (-1.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.358, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.659, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1771957148277158500 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. Reviewed-by: Thomas Huth Reviewed-by: Daniel P. Berrang=C3=A9 Message-ID: <20260218213416.674483-20-jsnow@redhat.com> Signed-off-by: John Snow --- python/README.rst | 52 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/python/README.rst b/python/README.rst index d62e71528d2..ec5cb5e971b 100644 --- a/python/README.rst +++ b/python/README.rst @@ -3,7 +3,17 @@ QEMU Python Tooling =20 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 in your build +directory is recommended. + +General structure +----------------- =20 ``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 configu= ration used by =20 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. =20 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 -------------------------------------------- =20 -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: =20 1. Set your PYTHONPATH environment variable to include this source directory, e.g. ``~/src/qemu/python``. See @@ -61,8 +81,26 @@ invoke them without installation, you can invoke e.g.: =20 ``> PYTHONPATH=3D~/src/qemu/python python3 -m qemu.qmp.qmp_shell`` =20 +**It is strongly advised to just use the configure-time venv instead.** +After running configure, simply use the run script available in the QEMU +build directory: + +``> $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`` =20 =20 Files in this directory --=20 2.53.0