Check EXTERNALLY-MANAGED in install and uninstall

This implements the PEP 668 logic to 'pip install' and 'pip uninstall'.
Are there any other commands that may need it?

This implementation disables the check is any of --prefix, --home, or
--target is provided, since those can indicate the command does not
actually install into the environment. Note that it is still possible
the command is still modifying the environment, but we don't have a
way to stop the user *that* determined to break the environment anyway
(they can always just use those flags in a virtual environment).

Also not sure how best this can be tested.

Author: uranusjr

news/11381.feature.rst

@@ -0,0 +1,3 @@
+Implement logic to read the ``EXTERNALLY-MANAGED`` file as specified in PEP 668.
+This allows a downstream Python distributor to prevent users from using pip to
+modify the externally managed environment.

src/pip/_internal/commands/install.py

@@ -42,6 +42,7 @@
 from pip._internal.utils.logging import getLogger
 from pip._internal.utils.misc import (
     ensure_dir,
+    get_externally_managed_error,
     get_pip_version,
     protect_pip_from_modification_on_windows,
     write_output,
@@ -284,6 +285,21 @@ def run(self, options: Values, args: List[str]) -> int:
         if options.use_user_site and options.target_dir is not None:
             raise CommandError("Can not combine '--user' and '--target'")
 
+        # Check whether the environment we're installing into is externally
+        # managed, as specified in PEP 668. Specifying --root, --target, or
+        # --prefix disables the check, since there's no reliable way to locate
+        # the EXTERNALLY-MANAGED file for those cases.
+        installing_into_current_environment = (
+            not options.dry_run
+            and options.root_path is None
+            and options.target_dir is None
+            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)
+
         upgrade_strategy = "to-satisfy-only"
         if options.upgrade:
             upgrade_strategy = options.upgrade_strategy

src/pip/_internal/commands/uninstall.py

@@ -14,7 +14,10 @@
     install_req_from_line,
     install_req_from_parsed_requirement,
 )
-from pip._internal.utils.misc import protect_pip_from_modification_on_windows
+from pip._internal.utils.misc import (
+    get_externally_managed_error,
+    protect_pip_from_modification_on_windows,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -90,6 +93,10 @@ 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)
+
         protect_pip_from_modification_on_windows(
             modifying_pip="pip" in reqs_to_uninstall
         )

src/pip/_internal/utils/misc.py

@@ -1,17 +1,20 @@
 # The following comment should be removed at some point in the future.
 # mypy: strict-optional=False
 
+import configparser
 import contextlib
 import errno
 import getpass
 import hashlib
 import io
+import locale
 import logging
 import os
 import posixpath
 import shutil
 import stat
 import sys
+import sysconfig
 import urllib.parse
 from io import StringIO
 from itertools import filterfalse, tee, zip_longest
@@ -57,6 +60,7 @@
     "captured_stdout",
     "ensure_dir",
     "remove_auth_from_url",
+    "get_externally_managed_error",
     "ConfiguredBuildBackendHookCaller",
 ]
 
@@ -581,6 +585,58 @@ 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 _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 running_under_virtualenv():
+        return None
+    marker = os.path.join(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED")
+    if not os.path.isfile(marker):
+        return 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
+
+
 def is_console_interactive() -> bool:
     """Is this console interactive?"""
     return sys.stdin is not None and sys.stdin.isatty()