Use ExternallyManagedEnvironment to show error

This moves most of the displaying logic into the exception class so it
can better leverage DiagnosticPipError and Rich functionalities.

Author: uranusjr

src/pip/_internal/commands/install.py

@@ -41,8 +41,8 @@
 from pip._internal.utils.filesystem import test_writable_dir
 from pip._internal.utils.logging import getLogger
 from pip._internal.utils.misc import (
+    check_externally_managed,
     ensure_dir,
-    get_externally_managed_error,
     get_pip_version,
     protect_pip_from_modification_on_windows,
     write_output,
@@ -296,9 +296,7 @@ def run(self, options: Values, args: List[str]) -> int:
             and options.prefix_path is None
         )
         if installing_into_current_environment:
-            externally_managed_error = get_externally_managed_error()
-            if externally_managed_error is not None:
-                raise InstallationError(externally_managed_error)
+            check_externally_managed()
 
         upgrade_strategy = "to-satisfy-only"
         if options.upgrade:

src/pip/_internal/commands/uninstall.py

@@ -15,7 +15,7 @@
     install_req_from_parsed_requirement,
 )
 from pip._internal.utils.misc import (
-    get_externally_managed_error,
+    check_externally_managed,
     protect_pip_from_modification_on_windows,
 )
 
@@ -93,9 +93,7 @@ def run(self, options: Values, args: List[str]) -> int:
                 f'"pip help {self.name}")'
             )
 
-        externally_managed_error = get_externally_managed_error()
-        if externally_managed_error is not None:
-            raise InstallationError(externally_managed_error)
+        check_externally_managed()
 
         protect_pip_from_modification_on_windows(
             modifying_pip="pip" in reqs_to_uninstall

src/pip/_internal/exceptions.py

@@ -6,9 +6,12 @@
 """
 
 import configparser
+import contextlib
+import locale
 import re
+import sys
 from itertools import chain, groupby, repeat
-from typing import TYPE_CHECKING, Dict, List, Optional, Union
+from typing import TYPE_CHECKING, Dict, Iterator, List, Optional, Union
 
 from pip._vendor.requests.models import Request, Response
 from pip._vendor.rich.console import Console, ConsoleOptions, RenderResult
@@ -658,3 +661,62 @@ def __str__(self) -> str:
             assert self.error is not None
             message_part = f".\n{self.error}\n"
         return f"Configuration file {self.reason}{message_part}"
+
+
+_DEFAULT_EXTERNALLY_MANAGED_ERROR = f"""\
+The Python environment under {sys.prefix} is managed externally, and may not be
+manipulated by the user. Please use specific tooling from the distributor of
+the Python installation to interact with this environment instead.
+"""
+
+
+class ExternallyManagedEnvironment(DiagnosticPipError):
+    """The current environment is externally managed.
+
+    This is raised when the current environment is externally managed, as
+    defined by `PEP 668`_. The ``EXTERNALLY-MANAGED`` configuration is checked
+    and displayed when the error is bubbled up to the user.
+
+    :param error: The error message read from ``EXTERNALLY-MANAGED``.
+    """
+
+    def __init__(self, error: Optional[str]) -> None:
+        if error is None:
+            context = Text(_DEFAULT_EXTERNALLY_MANAGED_ERROR)
+        else:
+            context = Text(error)
+        super().__init__(
+            message="This environment is externally managed",
+            context=context,
+            note_stmt=(
+                "If you believe this is a mistake, please contact your "
+                "Python installation or OS distribution provider."
+            ),
+            hint_stmt=Text("See PEP 668 for the detailed specification."),
+        )
+
+    @staticmethod
+    def _iter_externally_managed_error_keys() -> Iterator[str]:
+        lang, _ = locale.getlocale(locale.LC_MESSAGES)
+        if lang is not None:
+            yield f"Error-{lang}"
+            for sep in ("-", "_"):
+                before, found, _ = lang.partition(sep)
+                if not found:
+                    continue
+                yield f"Error-{before}"
+        yield "Error"
+
+    @classmethod
+    def from_config(
+        cls,
+        parser: configparser.ConfigParser,
+    ) -> "ExternallyManagedEnvironment":
+        try:
+            section = parser["externally-managed"]
+        except KeyError:
+            return cls(None)
+        for key in cls._iter_externally_managed_error_keys():
+            with contextlib.suppress(KeyError):
+                return cls(section[key])
+        return cls(None)

src/pip/_internal/utils/misc.py

@@ -7,8 +7,6 @@
 import getpass
 import hashlib
 import io
-import locale
-import logging
 import os
 import posixpath
 import shutil
@@ -41,8 +39,9 @@
 from pip._vendor.tenacity import retry, stop_after_delay, wait_fixed
 
 from pip import __version__
-from pip._internal.exceptions import CommandError
+from pip._internal.exceptions import CommandError, ExternallyManagedEnvironment
 from pip._internal.locations import get_major_minor_version
+from pip._internal.utils._log import VERBOSE, getLogger
 from pip._internal.utils.compat import WINDOWS
 from pip._internal.utils.virtualenv import running_under_virtualenv
 
@@ -60,12 +59,12 @@
     "captured_stdout",
     "ensure_dir",
     "remove_auth_from_url",
-    "get_externally_managed_error",
+    "check_externally_managed",
     "ConfiguredBuildBackendHookCaller",
 ]
 
 
-logger = logging.getLogger(__name__)
+logger = getLogger(__name__)
 
 T = TypeVar("T")
 ExcInfo = Tuple[Type[BaseException], BaseException, TracebackType]
@@ -585,56 +584,25 @@ def protect_pip_from_modification_on_windows(modifying_pip: bool) -> None:
         )
 
 
-_DEFAULT_EXTERNALLY_MANAGED_ERROR = f"""\
-The Python environment under {sys.prefix} is managed externally, and may not be
-manipulated by the user. Please use specific tooling from the distributor of
-the Python installation to interact with this environment instead.
-"""
+def check_externally_managed() -> None:
+    """Check whether the current environment is externally managed.
 
-
-def _iter_externally_managed_error_keys() -> Iterator[str]:
-    lang, _ = locale.getlocale(locale.LC_MESSAGES)
-    if lang is not None:
-        yield f"Error-{lang}"
-        for sep in ("-", "_"):
-            before, found, _ = lang.partition(sep)
-            if not found:
-                continue
-            yield f"Error-{before}"
-    yield "Error"
-
-
-def get_externally_managed_error() -> Optional[str]:
-    """Get an error message from the EXTERNALLY-MANAGED config file.
-
-    This checks whether the current environment pip is running in is externally
-    managed. If the EXTERNALLY-MANAGED file is found, the vendor-provided error
-    message is read and returned (if available; a default message is used
-    otherwise), as specified in `PEP 668`_.
-
-    If the current environment is *not* externally managed, *None* is returned.
-
-    .. _`PEP 668`: https://peps.python.org/pep-0668/
+    If the ``EXTERNALLY-MANAGED`` config file is found, the current environment
+    is considered externally managed, and an ExternallyManagedEnvironment is
+    raised.
     """
     if running_under_virtualenv():
         return None
     marker = os.path.join(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED")
     if not os.path.isfile(marker):
-        return None
+        return
+    parser = configparser.ConfigParser(interpolation=None)
     try:
-        parser = configparser.ConfigParser(interpolation=None)
         parser.read(marker, encoding="utf-8")
-    except (OSError, UnicodeDecodeError) as e:
-        logger.warning("Ignoring %s due to error %s", marker, e)
-        return _DEFAULT_EXTERNALLY_MANAGED_ERROR
-    try:
-        section = parser["externally-managed"]
-    except KeyError:
-        return _DEFAULT_EXTERNALLY_MANAGED_ERROR
-    for key in _iter_externally_managed_error_keys():
-        with contextlib.suppress(KeyError):
-            return section[key]
-    return _DEFAULT_EXTERNALLY_MANAGED_ERROR
+    except (OSError, UnicodeDecodeError):
+        exc_info = logger.isEnabledFor(VERBOSE)
+        logger.warning("Failed to read %s", marker, exc_info=exc_info)
+    raise ExternallyManagedEnvironment.from_config(parser)
 
 
 def is_console_interactive() -> bool: