qemu/python
John Snow 4176dbd8b5 python: README.rst touchups
Clarifying a few points; removing the reference to 'setuptools' because
it isn't referenced anywhere else in this document and doesn't really
provide any useful information to a Python newcomer.

Adjusting the language elsewhere to be less ambiguous and have fewer
run-on sentences.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Willian Rampazzo <willianr@redhat.com>
Reviewed-by: Wainer dos Santos Moschetta <wainersm@redhat.com>
Message-id: 20210629214323.1329806-6-jsnow@redhat.com
Signed-off-by: John Snow <jsnow@redhat.com>
2021-06-30 21:54:04 -04:00
..
qemu python: Remove global pylint suppressions 2021-06-30 21:54:04 -04:00
tests python: add avocado-framework and tests 2021-06-01 16:21:21 -04:00
.gitignore python: add tox support 2021-06-01 16:21:21 -04:00
avocado.cfg python: add avocado-framework and tests 2021-06-01 16:21:21 -04:00
Makefile python: add tox support 2021-06-01 16:21:21 -04:00
MANIFEST.in python: add MANIFEST.in 2021-06-01 16:21:21 -04:00
PACKAGE.rst python: add Makefile for some common tasks 2021-06-01 16:21:21 -04:00
Pipfile python: add devel package requirements to setuptools 2021-06-01 16:21:21 -04:00
Pipfile.lock python: Re-lock pipenv at *oldest* supported versions 2021-06-30 21:54:04 -04:00
README.rst python: README.rst touchups 2021-06-30 21:54:04 -04:00
setup.cfg python: Re-lock pipenv at *oldest* supported versions 2021-06-30 21:54:04 -04:00
setup.py python: add qemu package installer 2021-06-01 16:21:21 -04: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.


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.
- ``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 venv-check``.
- ``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.