qemu/python
Paolo Bonzini 71ed611cd4 python: mkvenv: add ensuregroup command
Introduce a new subcommand that retrieves the packages to be installed
from a TOML file. This allows being more flexible in using the system
version of a package, while at the same time using a known-good version
when installing the package.  This is important for packages that
sometimes have backwards-incompatible changes or that depend on
specific versions of their dependencies.

Compared to JSON, TOML is more human readable and easier to edit.  A
parser is available in 3.11 but also available as a small (12k) package
for older versions, tomli.  While tomli is bundled with pip, this is only
true of recent versions of pip.  Of all the supported OSes pretty much
only FreeBSD has a recent enough version of pip while staying on Python
<3.11.  So we cannot use the same trick that is in place for distlib.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2023-08-28 09:55:36 +02:00
..
qemu python: bump minimum requirements so they are compatible with 3.12 2023-07-07 12:49:22 +02:00
scripts python: mkvenv: add ensuregroup command 2023-08-28 09:55:36 +02:00
tests python: bump minimum requirements so they are compatible with 3.12 2023-07-07 12:49:22 +02:00
wheels meson: require 0.63.0 2023-05-18 08:53:51 +02:00
.gitignore python: drop pipenv 2023-02-22 23:35:03 -05:00
avocado.cfg python: use avocado's "new" runner 2022-01-21 16:01:13 -05:00
Makefile Python: Drop support for Python 3.6 2023-05-18 08:53:51 +02:00
MANIFEST.in python: add MANIFEST.in 2021-06-01 16:21:21 -04:00
PACKAGE.rst python: rename qemu.aqmp to qemu.qmp 2022-04-21 11:01:00 -04:00
README.rst python: drop pipenv 2023-02-22 23:35:03 -05:00
setup.cfg python: mkvenv: add ensuregroup command 2023-08-28 09:55:36 +02:00
setup.py Python: discourage direct setup.py install 2022-02-23 17:07:26 -05:00
VERSION python: add VERSION file 2021-06-01 16:21:21 -04:00

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).

``setup.py`` is used by ``pip`` to install this tooling to the current
environment. ``setup.cfg`` provides the packaging configuration used by
``setup.py``. You will generally invoke it by doing one of the following:

1. ``pip3 install .`` will install these packages to your current
   environment. If you are inside a virtual environment, they will
   install there. If you are not, it will attempt to install to the
   global environment, which is **not recommended**.

2. ``pip3 install --user .`` will install these packages to your user's
   local python packages. If you are inside of a virtual environment,
   this will fail; you want the first invocation above.

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.

Installing ".[devel]" instead of "." will additionally pull in required
packages for testing this package. They are not runtime requirements,
and are not needed to simply use these libraries.

Running ``make develop`` will pull in all testing dependencies and
install QEMU in editable mode to the current environment.
(It is a shortcut for ``pip3 install -e .[devel]``.)

See `Installing packages using pip and virtual environments
<https://packaging.python.org/guides/installing-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
-----------------------

- ``qemu/`` Python 'qemu' namespace package source directory.
- ``tests/`` Python package tests directory.
- ``avocado.cfg`` Configuration for the Avocado test-runner.
  Used by ``make check`` et al.
- ``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
  that should be included by a source distribution.
- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org.
- ``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.