qemu-devel.nongnu.org archive mirror
 help / color / mirror / Atom feed
From: John Snow <jsnow@redhat.com>
To: qemu-devel@nongnu.org
Cc: "Warner Losh" <imp@bsdimp.com>, "Beraldo Leal" <bleal@redhat.com>,
	"John Snow" <jsnow@redhat.com>, "Kyle Evans" <kevans@freebsd.org>,
	"Paolo Bonzini" <pbonzini@redhat.com>,
	"Thomas Huth" <thuth@redhat.com>,
	"Daniel Berrange" <berrange@redhat.com>,
	"Reinoud Zandijk" <reinoud@netbsd.org>,
	"Wainer dos Santos Moschetta" <wainersm@redhat.com>,
	"Cleber Rosa" <crosa@redhat.com>,
	"Ryo ONODERA" <ryoon@netbsd.org>,
	"Philippe Mathieu-Daudé" <philmd@linaro.org>,
	"Ani Sinha" <ani@anisinha.ca>,
	"Michael S. Tsirkin" <mst@redhat.com>,
	"Alex Bennée" <alex.bennee@linaro.org>
Subject: [RFC PATCH v3 18/20] mkvenv: add diagnose() method for ensure() failures
Date: Mon, 24 Apr 2023 16:02:46 -0400	[thread overview]
Message-ID: <20230424200248.1183394-19-jsnow@redhat.com> (raw)
In-Reply-To: <20230424200248.1183394-1-jsnow@redhat.com>

This is a routine that is designed to print some usable info for human
beings back out to the terminal if/when "mkvenv ensure" fails to locate
or install a package during configure time, such as meson or sphinx.

Since we are requiring that "meson" and "sphinx" are installed to the
same Python environment as QEMU is configured to build with, this can
produce some surprising failures when things are mismatched. This method
is here to try and ease that sting by offering some actionable
diagnosis.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 python/scripts/mkvenv.py | 153 +++++++++++++++++++++++++++++++++++----
 1 file changed, 140 insertions(+), 13 deletions(-)

diff --git a/python/scripts/mkvenv.py b/python/scripts/mkvenv.py
index 937664ea9c..1bc4bc01b1 100644
--- a/python/scripts/mkvenv.py
+++ b/python/scripts/mkvenv.py
@@ -64,6 +64,7 @@
 import os
 from pathlib import Path
 import re
+import shutil
 import site
 import stat
 import subprocess
@@ -543,6 +544,103 @@ def checkpip() -> None:
     logging.debug("Pip is now (hopefully) repaired!")
 
 
+def diagnose(
+    dep_spec: str,
+    online: bool,
+    wheels_dir: Optional[Union[str, Path]],
+    prog: Optional[str],
+) -> str:
+    """
+    Offer a summary to the user as to why a package failed to be installed.
+
+    :param dep_spec: The package we tried to ensure, e.g. 'meson>=0.61.5'
+    :param online: Did we allow PyPI access?
+    :param prog:
+        Optionally, a shell program name that can be used as a
+        bellwether to detect if this program is installed elsewhere on
+        the system. This is used to offer advice when a program is
+        detected for a different python version.
+    :param wheels_dir:
+        Optionally, a directory that was searched for vendored packages.
+    """
+    # pylint: disable=too-many-branches
+
+    # Parse name out of PEP-508 depspec.
+    # See https://peps.python.org/pep-0508/#names
+    match = re.match(
+        r"^([A-Z0-9]([A-Z0-9._-]*[A-Z0-9])?)", dep_spec, re.IGNORECASE
+    )
+    if not match:
+        raise ValueError(
+            f"dep_spec '{dep_spec}'"
+            " does not appear to contain a valid package name"
+        )
+    pkg_name = match.group(0)
+    pkg_version = None
+
+    has_importlib = False
+    try:
+        # Python 3.8+ stdlib
+        # pylint: disable=import-outside-toplevel
+        from importlib.metadata import PackageNotFoundError, version
+
+        has_importlib = True
+        try:
+            pkg_version = version(pkg_name)
+        except PackageNotFoundError:
+            pass
+    except ModuleNotFoundError:
+        pass
+
+    lines = []
+
+    if pkg_version:
+        lines.append(
+            f"Python package '{pkg_name}' version '{pkg_version}' was found,"
+            " but isn't suitable."
+        )
+    elif has_importlib:
+        lines.append(
+            f"Python package '{pkg_name}' was not found nor installed."
+        )
+    else:
+        lines.append(
+            f"Python package '{pkg_name}' is either not found or"
+            " not a suitable version."
+        )
+
+    if wheels_dir:
+        lines.append(
+            "No suitable version found in, or failed to install from"
+            f" '{wheels_dir}'."
+        )
+    else:
+        lines.append("No local package directory was searched.")
+
+    if online:
+        lines.append("A suitable version could not be obtained from PyPI.")
+    else:
+        lines.append(
+            "mkvenv was configured to operate offline and did not check PyPI."
+        )
+
+    if prog and not pkg_version:
+        which = shutil.which(prog)
+        if which:
+            pypath = Path(sys.executable).resolve()
+            lines.append(
+                f"'{prog}' was detected on your system at '{which}', "
+                f"but the Python package '{pkg_name}' was not found by this "
+                f"Python interpreter ('{pypath}'). "
+                f"Typically this means that '{prog}' has been installed "
+                "against a different Python interpreter on your system."
+            )
+
+    lines = [f" • {line}" for line in lines]
+    lines.insert(0, f"Could not ensure availability of '{dep_spec}':")
+    return os.linesep.join(lines)
+
+
 def pip_install(
     args: Sequence[str],
     online: bool = False,
@@ -573,23 +671,11 @@ def pip_install(
     subprocess.run(full_args, check=True)
 
 
-def ensure(
+def _do_ensure(
     dep_spec: str,
     online: bool = False,
     wheels_dir: Optional[Union[str, Path]] = None,
 ) -> None:
-    """
-    Use pip to ensure we have the package specified by @dep_spec.
-
-    If the package is already installed, do nothing. If online and
-    wheels_dir are both provided, prefer packages found in wheels_dir
-    first before connecting to PyPI.
-
-    :param dep_spec:
-        A PEP 508 dependency specification. e.g. 'meson>=0.61.5'.
-    :param online: If True, fall back to PyPI.
-    :param wheels_dir: If specified, search this path for packages.
-    """
     # This first install command will:
     # (A) Do nothing, if we already have a suitable package.
     # (B) Install the package from vendored source, if possible.
@@ -603,11 +689,42 @@ def ensure(
         # The package is missing or isn't a suitable version,
         # and we weren't able to install a suitable vendored package.
         if online:
+            logger.info("offline ensure failed, trying PyPI ...")
             pip_install([dep_spec], online=True)
         else:
             raise
 
 
+def ensure(
+    dep_spec: str,
+    online: bool = False,
+    wheels_dir: Optional[Union[str, Path]] = None,
+    prog: Optional[str] = None,
+) -> None:
+    """
+    Use pip to ensure we have the package specified by @dep_spec.
+
+    If the package is already installed, do nothing. If online and
+    wheels_dir are both provided, prefer packages found in wheels_dir
+    first before connecting to PyPI.
+
+    :param dep_spec:
+        A PEP 508 dependency specification. e.g. 'meson>=0.61.5'.
+    :param online: If True, fall back to PyPI.
+    :param wheels_dir: If specified, search this path for packages.
+    :param prog:
+        If specified, use this program name for error diagnostics that will
+        be presented to the user. e.g., 'sphinx-build' can be used as a
+        bellwether for the presence of 'sphinx'.
+    """
+    print(f"MKVENV ensure {dep_spec}", file=sys.stderr)
+    try:
+        _do_ensure(dep_spec, online, wheels_dir)
+    except subprocess.CalledProcessError as exc:
+        # Well, that's not good.
+        raise Ouch(diagnose(dep_spec, online, wheels_dir, prog)) from exc
+
+
 def post_venv_setup(bin_path: str, packages: Sequence[str] = ()) -> None:
     """
     This is intended to be run *inside the venv* after it is created.
@@ -671,6 +788,15 @@ def _add_ensure_subcommand(subparsers: Any) -> None:
         action="store",
         help="Path to vendored packages where we may install from.",
     )
+    subparser.add_argument(
+        "--diagnose",
+        type=str,
+        action="store",
+        help=(
+            "Name of a shell utility to use for "
+            "diagnostics if this command fails."
+        ),
+    )
     subparser.add_argument(
         "dep_spec",
         type=str,
@@ -727,6 +853,7 @@ def _normalize_gen() -> None:
                 dep_spec=args.dep_spec,
                 online=args.online,
                 wheels_dir=args.dir,
+                prog=args.diagnose,
             )
         logger.debug("mkvenv.py %s: exiting", args.command)
     except Ouch as exc:
-- 
2.39.2



  parent reply	other threads:[~2023-04-24 20:08 UTC|newest]

Thread overview: 46+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-04-24 20:02 [RFC PATCH v3 00/20] configure: create a python venv and ensure meson, sphinx John Snow
2023-04-24 20:02 ` [RFC PATCH v3 01/20] python: update pylint configuration John Snow
2023-04-25 16:38   ` Daniel P. Berrangé
2023-04-24 20:02 ` [RFC PATCH v3 02/20] python: add mkvenv.py John Snow
2023-04-24 20:02 ` [RFC PATCH v3 03/20] mkvenv: add console script entry point generation John Snow
2023-04-24 20:02 ` [RFC PATCH v3 04/20] mkvenv: Add better error message for missing pyexpat module John Snow
2023-04-24 20:02 ` [RFC PATCH v3 05/20] mkvenv: generate console entry shims from inside the venv John Snow
2023-04-24 20:02 ` [RFC PATCH v3 06/20] mkvenv: work around broken pip installations on Debian 10 John Snow
2023-04-24 20:02 ` [RFC PATCH v3 07/20] mkvenv: add nested venv workaround John Snow
2023-04-24 20:02 ` [RFC PATCH v3 08/20] mkvenv: add ensure subcommand John Snow
2023-04-24 20:02 ` [RFC PATCH v3 09/20] tests/docker: add python3-venv dependency John Snow
2023-04-25 16:42   ` Daniel P. Berrangé
2023-04-24 20:02 ` [RFC PATCH v3 10/20] tests/vm: Configure netbsd to use Python 3.10 John Snow
2023-04-25 16:43   ` Daniel P. Berrangé
2023-04-24 20:02 ` [RFC PATCH v3 11/20] tests/vm: add py310-expat to NetBSD John Snow
2023-04-25 16:45   ` Daniel P. Berrangé
2023-04-25 16:57     ` John Snow
2023-04-24 20:02 ` [RFC PATCH v3 12/20] scripts/make-release: download meson==0.61.5 .whl John Snow
2023-04-24 20:02 ` [RFC PATCH v3 13/20] configure: create a python venv unconditionally John Snow
2023-04-24 20:02 ` [RFC PATCH v3 14/20] configure: use 'mkvenv ensure meson' to bootstrap meson John Snow
2023-04-24 20:35   ` Warner Losh
2023-04-24 20:41     ` John Snow
2023-04-24 21:20       ` Warner Losh
2023-04-24 20:02 ` [RFC PATCH v3 15/20] configure: add --enable-pypi and --disable-pypi John Snow
2023-04-24 20:02 ` [RFC PATCH v3 16/20] tests: Use configure-provided pyvenv for tests John Snow
2023-04-24 20:02 ` [RFC PATCH v3 17/20] configure: move --enable-docs and --disable-docs back to configure John Snow
2023-04-24 20:02 ` John Snow [this message]
2023-04-24 20:02 ` [RFC PATCH v3 19/20] configure: use --diagnose option with meson ensure John Snow
2023-04-24 20:02 ` [RFC PATCH v3 20/20] configure: bootstrap sphinx with mkvenv John Snow
2023-04-25 17:17 ` [RFC PATCH v3 00/20] configure: create a python venv and ensure meson, sphinx Daniel P. Berrangé
2023-04-25 17:22   ` John Snow
2023-04-25 17:34     ` John Snow
2023-04-25 18:10       ` Daniel P. Berrangé
2023-04-25 18:58         ` John Snow
2023-04-26  8:21           ` Daniel P. Berrangé
2023-04-26  8:35             ` Paolo Bonzini
2023-04-25 18:03     ` Daniel P. Berrangé
2023-04-26  8:05 ` Paolo Bonzini
2023-04-26  8:49   ` Paolo Bonzini
2023-04-26 16:16     ` John Snow
2023-04-26 19:10       ` Paolo Bonzini
2023-04-26  8:53 ` Daniel P. Berrangé
2023-04-26  9:08   ` Paolo Bonzini
2023-04-26 16:32     ` John Snow
2023-04-26 19:23       ` Paolo Bonzini
2023-05-01 19:20 ` 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=20230424200248.1183394-19-jsnow@redhat.com \
    --to=jsnow@redhat.com \
    --cc=alex.bennee@linaro.org \
    --cc=ani@anisinha.ca \
    --cc=berrange@redhat.com \
    --cc=bleal@redhat.com \
    --cc=crosa@redhat.com \
    --cc=imp@bsdimp.com \
    --cc=kevans@freebsd.org \
    --cc=mst@redhat.com \
    --cc=pbonzini@redhat.com \
    --cc=philmd@linaro.org \
    --cc=qemu-devel@nongnu.org \
    --cc=reinoud@netbsd.org \
    --cc=ryoon@netbsd.org \
    --cc=thuth@redhat.com \
    --cc=wainersm@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).