From d2ae942984ef6bee864e4cfddc1adcc3d4a31e42 Mon Sep 17 00:00:00 2001 From: John Snow Date: Tue, 29 Jun 2021 17:43:14 -0400 Subject: [PATCH] python: Add no-install usage instructions It's not encouraged, but it's legitimate to want to know how to do. Signed-off-by: John Snow Reviewed-by: Willian Rampazzo Reviewed-by: Wainer dos Santos Moschetta Message-id: 20210629214323.1329806-7-jsnow@redhat.com Signed-off-by: John Snow --- python/README.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/python/README.rst b/python/README.rst index 107786ffdc..d4502fdb60 100644 --- a/python/README.rst +++ b/python/README.rst @@ -37,6 +37,34 @@ 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 -----------------------