fix: show update environment before confirmation (#246)

## Summary

- show the Python executable, environment prefix and type, and installed
package location before updating
- run pip through the displayed interpreter so the update targets the
environment running `cwms-cli`
- recognize standard Python, virtualenv, and Conda environments across
Windows and POSIX
- document the safer `python -m pip` manual update form and the
updater's environment behavior

## Root cause and impact

A bare `pip install` can resolve to a different Python installation from
the one running `cwms-cli`. Although the updater already used the
running interpreter, it did not expose that environment before asking
for confirmation. Users can now verify the exact runtime and package
location before any update begins.

## Validation

- `poetry run pytest -q` - 228 passed
- repository-pinned Black and isort checks
- ownership synchronization check
- CLI smoke test
- Sphinx HTML build with warnings treated as errors

Fixes #222

Author: krowvin

README.md

@@ -14,14 +14,20 @@ Note: You may need to run `python -m pip install cwms-cli` if PIP is not in your
 
 ### Update
 ```sh
-pip install cwms-cli --upgrade
+python -m pip install --upgrade cwms-cli
 ```
 
 Or as of version `0.3.0+`
 ```sh
 cwms-cli update
 ```
 
+`cwms-cli update` displays the Python executable, environment, package metadata
+location, and editable project location when applicable before asking for
+confirmation. It runs pip through the same Python interpreter that is running
+`cwms-cli`, avoiding accidental updates to a different Python installation or
+virtual environment.
+
 To install a specific version:
 ```sh
 cwms-cli update --target-version 0.7.1 --yes

cwmscli/commands/commands_cwms.py

@@ -1,7 +1,6 @@
 import logging
 import os
 import subprocess
-import sys
 import textwrap
 from pathlib import Path
 from typing import Optional
@@ -26,7 +25,9 @@
 from cwmscli.utils.deps import requires
 from cwmscli.utils.update import (
     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
@@ -416,6 +417,7 @@ def csv2cwms_cmd(**kwargs):
 def update_cli_cmd(target_version: Optional[str], pre: bool, yes: bool) -> None:
     current_version = get_cwms_cli_version()
     package_spec = build_update_package_spec(target_version)
+    update_environment = get_update_environment()
 
     click.echo(
         "Current cwms-cli version: " f"{colors.c(current_version, 'cyan', bright=True)}"
@@ -428,12 +430,35 @@ def update_cli_cmd(target_version: Optional[str], pre: bool, yes: bool) -> None:
     else:
         click.echo("Requested cwms-cli version: latest available release")
 
-    cmd = [sys.executable, "-m", "pip", "install", "--upgrade", package_spec]
+    click.echo("Update environment:")
+    click.echo(f"  Python executable: {update_environment.python_executable}")
+    click.echo(
+        f"  Environment: {update_environment.environment_prefix} "
+        f"({update_environment.environment_type})"
+    )
+    click.echo(f"  Package metadata location: {update_environment.package_location}")
+    if update_environment.editable_project_location:
+        click.echo(
+            "  Editable project location: "
+            f"{update_environment.editable_project_location}"
+        )
+
+    cmd = [
+        update_environment.python_executable,
+        "-m",
+        "pip",
+        "install",
+        "--upgrade",
+        package_spec,
+    ]
     if pre:
         cmd.append("--pre")
 
     if not yes:
-        proceed = click.confirm("Proceed with updating cwms-cli via pip?", default=True)
+        proceed = click.confirm(
+            "Proceed with updating cwms-cli in this environment via pip?",
+            default=True,
+        )
         if not proceed:
             click.echo(colors.warn("Update canceled."))
             return
@@ -472,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

@@ -1,6 +1,96 @@
+import importlib.metadata
+import json
+import os
 import subprocess
+import sys
 import tempfile
+from dataclasses import dataclass
 from typing import List, Optional
+from urllib.parse import unquote, urlparse
+from urllib.request import url2pathname
+
+
+@dataclass(frozen=True)
+class UpdateEnvironment:
+    python_executable: str
+    environment_prefix: str
+    environment_type: str
+    package_location: str
+    editable_project_location: Optional[str] = None
+
+
+def _absolute_path(path: str) -> str:
+    return os.path.abspath(os.path.expanduser(path))
+
+
+def _same_path(left: str, right: str) -> bool:
+    return os.path.normcase(_absolute_path(left)) == os.path.normcase(
+        _absolute_path(right)
+    )
+
+
+def _editable_project_location(
+    distribution: importlib.metadata.Distribution,
+) -> Optional[str]:
+    direct_url_text = distribution.read_text("direct_url.json")
+    if not direct_url_text:
+        return None
+
+    try:
+        direct_url = json.loads(direct_url_text)
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+    if not isinstance(direct_url, dict):
+        return None
+    directory_info = direct_url.get("dir_info")
+    if not isinstance(directory_info, dict) or not directory_info.get("editable"):
+        return None
+
+    url = direct_url.get("url")
+    if not isinstance(url, str):
+        return None
+    parsed_url = urlparse(url)
+    if parsed_url.scheme != "file":
+        return None
+
+    project_path = url2pathname(unquote(parsed_url.path))
+    if parsed_url.netloc and parsed_url.netloc != "localhost":
+        project_path = f"//{parsed_url.netloc}{project_path}"
+    return _absolute_path(project_path)
+
+
+def get_update_environment() -> UpdateEnvironment:
+    """Describe the Python environment targeted by ``cwms-cli update``."""
+    python_executable = _absolute_path(sys.executable)
+    environment_prefix = _absolute_path(sys.prefix)
+    conda_prefix = os.getenv("CONDA_PREFIX")
+
+    if conda_prefix and _same_path(conda_prefix, sys.prefix):
+        environment_type = "Conda environment"
+    elif not _same_path(sys.prefix, sys.base_prefix):
+        environment_type = "virtual environment"
+    else:
+        environment_type = "Python installation"
+
+    try:
+        distribution = importlib.metadata.distribution("cwms-cli")
+        package_location = os.path.realpath(os.fspath(distribution.locate_file("")))
+        editable_project_location = _editable_project_location(distribution)
+    except importlib.metadata.PackageNotFoundError:
+        # This can happen when the CLI is invoked directly from a source checkout.
+        package_location = os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+        editable_project_location = None
+
+    return UpdateEnvironment(
+        python_executable=python_executable,
+        environment_prefix=environment_prefix,
+        environment_type=environment_type,
+        package_location=package_location,
+        editable_project_location=editable_project_location,
+    )
 
 
 def build_update_package_spec(target_version: Optional[str]) -> str:
@@ -16,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

@@ -8,9 +8,49 @@ By default it installs the latest available release, and you can optionally
 target a specific version with ``--target-version``. After updating, use
 :doc:`Version argument <version>` to confirm the installed version.
 
+Before asking for confirmation, the command displays the Python executable,
+environment prefix and type, and installed package metadata location. For an
+editable installation, it also displays the editable project location recorded
+by the installer. The update runs pip through the displayed executable
+(``python -m pip``), so it targets the same Python environment that is running
+``cwms-cli``. This is especially useful when multiple Python installations or
+virtual environments are present.
+
 On Windows, the command launches the pip install in a separate command window so
 the running ``cwms-cli.exe`` does not block its own replacement.
 
+.. note::
+
+   A standalone ``pip install --upgrade cwms-cli`` command uses whichever
+   ``pip`` executable appears first on the shell's path, which may belong to a
+   different Python environment. Prefer ``cwms-cli update``. When updating
+   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
+----------------------
+
+Editable installations keep their distribution metadata in the environment's
+``site-packages`` directory while loading source code from a project directory.
+The updater displays both paths when ``direct_url.json`` identifies the current
+installation as editable.
+
 Examples
 --------