From: John Snow <jsnow@redhat.com>
To: Cleber Rosa <crosa@redhat.com>
Cc: "Kevin Wolf" <kwolf@redhat.com>, "Fam Zheng" <fam@euphon.net>,
"Thomas Huth" <thuth@redhat.com>,
"Eduardo Habkost" <ehabkost@redhat.com>,
qemu-block@nongnu.org,
"Philippe Mathieu-Daudé" <philmd@redhat.com>,
qemu-devel@nongnu.org,
"Wainer dos Santos Moschetta" <wainersm@redhat.com>,
"Philippe Mathieu-Daudé" <f4bug@amsat.org>,
"Willian Rampazzo" <willianr@redhat.com>,
"Willian Rampazzo" <wrampazz@redhat.com>,
"Max Reitz" <mreitz@redhat.com>,
"Alex Bennée" <alex.bennee@linaro.org>,
"Beraldo Leal" <bleal@redhat.com>
Subject: Re: [PATCH v6 06/25] python: add directory structure README.rst files
Date: Tue, 25 May 2021 13:14:50 -0400 [thread overview]
Message-ID: <359a6fd3-995d-08e9-e78b-0f3e38ee34ae@redhat.com> (raw)
In-Reply-To: <YKxh6/mwCEqRLIvH@localhost.localdomain>
On 5/24/21 10:33 PM, Cleber Rosa wrote:
> On Wed, May 12, 2021 at 07:12:22PM -0400, John Snow wrote:
>> Add short readmes to python/, python/qemu/, python/qemu/machine,
>> python/qemu/qmp, and python/qemu/utils that explain the directory
>> hierarchy. These readmes are visible when browsing the source on
>> e.g. gitlab/github and are designed to help new developers/users quickly
>> make sense of the source tree.
>>
>> They are not designed for inclusion in a published manual.
>>
>> Signed-off-by: John Snow <jsnow@redhat.com>
>> ---
>> python/README.rst | 41 ++++++++++++++++++++++++++++++++++
>> python/qemu/README.rst | 8 +++++++
>> python/qemu/machine/README.rst | 9 ++++++++
>> python/qemu/qmp/README.rst | 9 ++++++++
>> python/qemu/utils/README.rst | 7 ++++++
>> 5 files changed, 74 insertions(+)
>> create mode 100644 python/README.rst
>> create mode 100644 python/qemu/README.rst
>> create mode 100644 python/qemu/machine/README.rst
>> create mode 100644 python/qemu/qmp/README.rst
>> create mode 100644 python/qemu/utils/README.rst
>>
>> diff --git a/python/README.rst b/python/README.rst
>> new file mode 100644
>> index 00000000000..7a0dc5dff4a
>> --- /dev/null
>> +++ b/python/README.rst
>> @@ -0,0 +1,41 @@
>> +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 in a setuptools specific format. You will generally invoke it
>
> For consistency, ``setup.py`` here? Also, I guess ``setuptools`` as it
> falls in the same category of ``pip``.
>
Kinda-sorta, but `pip` is a command line executable and setuptools
isn't. Along those lines I'll fix setup.py but leave setuptools as-is.
>> +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.
>
> Maybe some **emphasis** on **not**?
>
Sure :)
>> +
>> +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.
>> +
>
> Maybe note that, if you are inside of a virtual environment, option #1
> will probably be what users doing "--user" in a venv actually want.
>
Yes. It's frequently annoying how this works, because it's hard to relay
succinctly :)
I think at least newer versions of pip give you good warnings when you
use --user for virtual environments at least.
>> +If you append the ``-e`` argument, pip will install in "editable" mode;
>> +which installs a version of the package that installs a forwarder
>> +pointing to these files, such that the package always reflects the
>> +latest version in your git tree.
>> +
>> +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 package source directory.
>> +- ``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.
>
> Not only used by pip... but I understand the reason for limiting the
> amount of information given here.
>
Yes ... suggesting broadly that I don't really support using
setuptools/setup.py alone to install the package, but instead expect and
consider 'pip' to be the canonical/supported interface.
There are sometimes minor differences between how they handle things, so
I wanted less emphasis on setuptools et al.
>> diff --git a/python/qemu/README.rst b/python/qemu/README.rst
>> new file mode 100644
>> index 00000000000..d04943f526c
>> --- /dev/null
>> +++ b/python/qemu/README.rst
>> @@ -0,0 +1,8 @@
>> +QEMU Python Namespace
>> +=====================
>> +
>> +This directory serves as the root of a `Python PEP 420 implicit
>> +namespace package <https://www.python.org/dev/peps/pep-0420/>`_.
>> +
>> +Each directory below is assumed to be an installable Python package that
>> +is available under the ``qemu.<package>`` namespace.
>> diff --git a/python/qemu/machine/README.rst b/python/qemu/machine/README.rst
>> new file mode 100644
>> index 00000000000..ac2b4fffb42
>> --- /dev/null
>> +++ b/python/qemu/machine/README.rst
>> @@ -0,0 +1,9 @@
>> +qemu.machine package
>> +====================
>> +
>> +This package provides core utilities used for testing and debugging
>> +QEMU. It is used by the iotests, vm tests, acceptance tests, and several
>> +other utilities in the ./scripts directory. It is not a fully-fledged
>> +SDK and it is subject to change at any time.
>> +
>> +See the documentation in ``__init__.py`` for more information.
>> diff --git a/python/qemu/qmp/README.rst b/python/qemu/qmp/README.rst
>> new file mode 100644
>> index 00000000000..c21951491cf
>> --- /dev/null
>> +++ b/python/qemu/qmp/README.rst
>> @@ -0,0 +1,9 @@
>> +qemu.qmp package
>> +================
>> +
>> +This package provides a library used for connecting to and communicating
>> +with QMP servers. It is used extensively by iotests, vm tests,
>> +acceptance tests, and other utilities in the ./scripts directory. It is
>> +not a fully-fledged SDK and is subject to change at any time.
>> +
>> +See the documentation in ``__init__.py`` for more information.
>> diff --git a/python/qemu/utils/README.rst b/python/qemu/utils/README.rst
>> new file mode 100644
>> index 00000000000..975fbf4d7de
>> --- /dev/null
>> +++ b/python/qemu/utils/README.rst
>> @@ -0,0 +1,7 @@
>> +qemu.utils package
>> +==================
>> +
>> +This package provides miscellaneous utilities used for testing and
>> +debugging QEMU. It is used primarily by the vm and acceptance tests.
>> +
>> +See the documentation in ``__init__.py`` for more information.
>> --
>> 2.30.2
>>
>>
>
> With the ``setup.py`` and ``setuptools`` for consistency sake
> mentioned in my first comment, all other comments are suggestions, so:
>
I took one of those two review comments, and acted on one of two of your
suggestions.
> Reviewed-by: Cleber Rosa <crosa@redhat.com>
>
So technically I didn't meet your criteria for taking this RB :) Let me
know if I can still apply it:
diff --git a/python/README.rst b/python/README.rst
index 7a0dc5dff4a..38b0c83f321 100644
--- a/python/README.rst
+++ b/python/README.rst
@@ -7,17 +7,17 @@ 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 in a setuptools specific format. You will generally invoke it
-by doing one of the following:
+``setup.py`` in a setuptools specific format. 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.
+ 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.
+ this will fail; you likely want the first invocation above.
If you append the ``-e`` argument, pip will install in "editable" mode;
which installs a version of the package that installs a forwarder
next prev parent reply other threads:[~2021-05-25 17:17 UTC|newest]
Thread overview: 64+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-12 23:12 [PATCH v6 00/25] python: create installable package John Snow
2021-05-12 23:12 ` [PATCH v6 01/25] iotests/297: add --namespace-packages to mypy arguments John Snow
2021-05-12 23:12 ` [PATCH v6 02/25] python: create qemu packages John Snow
2021-05-18 14:31 ` Cleber Rosa
2021-05-21 17:15 ` Willian Rampazzo
2021-05-12 23:12 ` [PATCH v6 03/25] python: create utils sub-package John Snow
2021-05-18 15:12 ` Cleber Rosa
2021-05-18 15:20 ` John Snow
2021-05-21 17:18 ` Willian Rampazzo
2021-05-21 17:39 ` John Snow
2021-05-12 23:12 ` [PATCH v6 04/25] python: add qemu package installer John Snow
2021-05-21 4:00 ` Cleber Rosa
2021-05-21 15:52 ` John Snow
2021-05-12 23:12 ` [PATCH v6 05/25] python: add VERSION file John Snow
2021-05-12 23:12 ` [PATCH v6 06/25] python: add directory structure README.rst files John Snow
2021-05-25 2:33 ` Cleber Rosa
2021-05-25 17:14 ` John Snow [this message]
2021-05-25 20:30 ` Cleber Rosa
2021-05-12 23:12 ` [PATCH v6 07/25] python: add MANIFEST.in John Snow
2021-05-25 2:42 ` Cleber Rosa
2021-05-25 14:12 ` John Snow
2021-05-12 23:12 ` [PATCH v6 08/25] python: Add pipenv support John Snow
2021-05-12 23:12 ` [PATCH v6 09/25] python: add pylint import exceptions John Snow
2021-05-12 23:12 ` [PATCH v6 10/25] python: move pylintrc into setup.cfg John Snow
2021-05-12 23:12 ` [PATCH v6 11/25] python: add pylint to pipenv John Snow
2021-05-25 3:33 ` Cleber Rosa
2021-05-12 23:12 ` [PATCH v6 12/25] python: move flake8 config to setup.cfg John Snow
2021-05-12 23:12 ` [PATCH v6 13/25] python: add excluded dirs to flake8 config John Snow
2021-05-25 15:50 ` Cleber Rosa
2021-05-25 17:18 ` John Snow
2021-05-12 23:12 ` [PATCH v6 14/25] python: Add flake8 to pipenv John Snow
2021-05-12 23:12 ` [PATCH v6 15/25] python: move mypy.ini into setup.cfg John Snow
2021-05-25 15:52 ` Cleber Rosa
2021-05-12 23:12 ` [PATCH v6 16/25] python: add mypy to pipenv John Snow
2021-05-12 23:12 ` [PATCH v6 17/25] python: move .isort.cfg into setup.cfg John Snow
2021-05-12 23:12 ` [PATCH v6 18/25] python/qemu: add isort to pipenv John Snow
2021-05-25 15:56 ` Cleber Rosa
2021-05-25 17:21 ` John Snow
2021-05-25 20:34 ` Cleber Rosa
2021-05-12 23:12 ` [PATCH v6 19/25] python/qemu: add qemu package itself " John Snow
2021-05-12 23:12 ` [PATCH v6 20/25] python: add devel package requirements to setuptools John Snow
2021-05-25 16:13 ` Cleber Rosa
2021-05-25 17:43 ` John Snow
2021-05-25 20:38 ` Cleber Rosa
2021-05-12 23:12 ` [PATCH v6 21/25] python: add avocado-framework and tests John Snow
2021-05-25 18:58 ` Cleber Rosa
2021-05-12 23:12 ` [PATCH v6 22/25] python: add Makefile for some common tasks John Snow
2021-05-25 19:24 ` Cleber Rosa
2021-05-25 19:45 ` John Snow
2021-05-25 20:39 ` Cleber Rosa
2021-05-12 23:12 ` [PATCH v6 23/25] python: add .gitignore John Snow
2021-05-25 19:36 ` Cleber Rosa
2021-05-25 20:10 ` John Snow
2021-05-25 20:42 ` Cleber Rosa
2021-05-25 23:54 ` John Snow
2021-05-12 23:12 ` [PATCH v6 24/25] gitlab: add python linters to CI John Snow
2021-05-25 19:55 ` Cleber Rosa
2021-05-25 20:33 ` John Snow
2021-05-12 23:12 ` [PATCH v6 25/25] python: add tox support John Snow
2021-05-25 20:15 ` Cleber Rosa
2021-05-25 20:25 ` John Snow
2021-05-25 20:46 ` Cleber Rosa
2021-05-25 22:15 ` John Snow
2021-05-17 18:52 ` [PATCH v6 00/25] python: create installable package John Snow
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=359a6fd3-995d-08e9-e78b-0f3e38ee34ae@redhat.com \
--to=jsnow@redhat.com \
--cc=alex.bennee@linaro.org \
--cc=bleal@redhat.com \
--cc=crosa@redhat.com \
--cc=ehabkost@redhat.com \
--cc=f4bug@amsat.org \
--cc=fam@euphon.net \
--cc=kwolf@redhat.com \
--cc=mreitz@redhat.com \
--cc=philmd@redhat.com \
--cc=qemu-block@nongnu.org \
--cc=qemu-devel@nongnu.org \
--cc=thuth@redhat.com \
--cc=wainersm@redhat.com \
--cc=willianr@redhat.com \
--cc=wrampazz@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).