fix: explain externally managed Python

Author: krowvin

cwmscli/commands/commands_cwms.py

@@ -27,6 +27,7 @@
     build_update_package_spec,
     get_update_environment,
     launch_windows_update,
+    looks_like_externally_managed_environment,
     looks_like_missing_version,
 )
 from cwmscli.utils.version import get_cwms_cli_version
@@ -496,6 +497,16 @@ def update_cli_cmd(target_version: Optional[str], pre: bool, yes: bool) -> None:
 
     if result.returncode != 0:
         pip_output = "\n".join(part for part in [result.stdout, result.stderr] if part)
+        if looks_like_externally_managed_environment(pip_output):
+            raise click.ClickException(
+                colors.err(
+                    "The selected Python installation is externally managed, so pip "
+                    "refused to update cwms-cli. Install cwms-cli in a virtual "
+                    "environment or with pipx, then run that installation's "
+                    "cwms-cli update command. cwms-cli will not use "
+                    "--break-system-packages automatically."
+                )
+            )
         if target_version and looks_like_missing_version(pip_output, package_spec):
             raise click.ClickException(
                 colors.err(

cwmscli/utils/update.py

@@ -106,6 +106,10 @@ def looks_like_missing_version(pip_output: str, package_spec: str) -> bool:
     ) and package_spec in pip_output
 
 
+def looks_like_externally_managed_environment(pip_output: str) -> bool:
+    return "externally-managed-environment" in pip_output.lower()
+
+
 def write_windows_update_script(cmd: List[str]) -> str:
     quoted_cmd = subprocess.list2cmdline(cmd)
     script = "\r\n".join(

docs/cli/update.rst

@@ -27,6 +27,22 @@ the running ``cwms-cli.exe`` does not block its own replacement.
    manually, use the full Python executable displayed by ``cwms-cli update``
    with ``-m pip install --upgrade cwms-cli``.
 
+Linux externally managed environments
+-------------------------------------
+
+Some Linux distributions mark their system Python installation as externally
+managed under PEP 668. If pip reports ``externally-managed-environment``,
+``cwms-cli update`` explains that the selected Python installation cannot be
+changed safely and recommends installing ``cwms-cli`` in a virtual environment
+or with pipx. The updater does not automatically pass
+``--break-system-packages``, because doing so can conflict with packages managed
+by the operating system.
+
+A correctly created virtual environment is not subject to the system Python's
+externally managed restriction. Confirm that the displayed Python executable
+and environment prefix both point into the intended virtual environment before
+continuing.
+
 Editable installations
 ----------------------
 

tests/cli/test_update_command.py

@@ -147,6 +147,25 @@ def fake_run(cmd, check=False, capture_output=False, text=False):
     assert "Requested cwms-cli version '9.9.9' was not found." in result.output
 
 
+def test_update_command_explains_externally_managed_environment(monkeypatch):
+    def fake_run(cmd, check=False, capture_output=False, text=False):
+        return _DummyResult(
+            1,
+            stderr="error: externally-managed-environment\n",
+        )
+
+    _set_update_os(monkeypatch, "posix")
+    monkeypatch.setattr("cwmscli.commands.commands_cwms.subprocess.run", fake_run)
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["update", "--yes"])
+
+    assert result.exit_code == 1
+    assert "selected Python installation is externally managed" in result.output
+    assert "virtual environment or with pipx" in result.output
+    assert "will not use --break-system-packages automatically" in result.output
+
+
 def test_update_command_cancelled_by_user(monkeypatch):
     calls = []