cwms-cli 0.7.4__tar.gz → 0.8.0__tar.gz

{cwms_cli-0.7.4 → cwms_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cwms-cli
-Version: 0.7.4
+Version: 0.8.0
 Summary: Command line utilities for Corps Water Management Systems (CWMS) python scripts. This is a collection of shared scripts across the enterprise Water Management Enterprise System (WMES) teams.
 License: LICENSE
 License-File: LICENSE
@@ -16,8 +16,12 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: dss
 Requires-Dist: click (>=8.1.8,<9.0.0)
 Requires-Dist: colorama (>=0.4.6,<0.5.0)
+Requires-Dist: cwms-python (>=1.0.7) ; extra == "dss"
+Requires-Dist: hec-python-library (>=0.9.5) ; extra == "dss"
+Requires-Dist: hecdss (>=0.1.24) ; extra == "dss"
 Requires-Dist: requests (>=2.32.0,<3.0.0) ; python_version == "3.9"
 Requires-Dist: requests (>=2.33.0,<3.0.0) ; python_version >= "3.10"
 Project-URL: Repository, https://github.com/HydrologicEngineeringCenter/cwms-cli
@@ -39,7 +43,7 @@ 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+`
@@ -47,6 +51,12 @@ Or as of version `0.3.0+`
 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
@@ -66,3 +76,21 @@ from cwmscli.usgs.getusgs_measurements_cda import getusgs_measurements_cda
 from cwmscli.usgs.getUSGS_ratings_cda import getusgs_rating_cda
 ```
 
+## Development environment
+
+The repository includes a Linux/Python 3.12 development container exercised by
+a dedicated CI job. Open the repository with the VS Code Dev Containers
+extension, or use the Dev Container CLI:
+
+```sh
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . poetry run pytest -q
+```
+
+The container installs project dependencies with Poetry and uses
+`/home/vscode/.venv`, so it does not reuse a host operating system's `.venv`.
+Poetry itself is kept in a separate `/opt/poetry` environment. Use the container
+for changes involving time zones, paths, native libraries, or other
+operating-system-dependent behavior. Standard Python 3.9 and Python 3.12
+installations remain covered by the existing CI matrix.
+

cwms_cli-0.8.0/README.md

@@ -0,0 +1,66 @@
+# cwms-cli
+
+A collection of scripts to create, read, update, list, and delete data through CWMS Data API (CDA) and other commonly used API in the US Army Corps of Engineers water management. CWMS-CLI wraps these API in a friendly to use terminal based interface.
+
+[![Docs](https://readthedocs.org/projects/cwms-cli/badge/?version=latest)](https://cwms-cli.readthedocs.io/en/latest/cli.html#cwms-cli) - 📖 Read the docs: https://cwms-cli.readthedocs.io/en/latest/
+
+## Install
+
+```sh
+pip install cwms-cli
+```
+Note: You may need to run `python -m pip install cwms-cli` if PIP is not in your path.
+
+
+### Update
+```sh
+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
+```
+
+## Command line implementation
+
+View the help in terminal:
+```sh
+cwms-cli --help
+```
+
+## run from within python
+```python
+from cwmscli.usgs.getusgs_cda import getusgs_cda
+from cwmscli.usgs.getusgs_measurements_cda import getusgs_measurements_cda
+from cwmscli.usgs.getUSGS_ratings_cda import getusgs_rating_cda
+```
+
+## Development environment
+
+The repository includes a Linux/Python 3.12 development container exercised by
+a dedicated CI job. Open the repository with the VS Code Dev Containers
+extension, or use the Dev Container CLI:
+
+```sh
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . poetry run pytest -q
+```
+
+The container installs project dependencies with Poetry and uses
+`/home/vscode/.venv`, so it does not reuse a host operating system's `.venv`.
+Poetry itself is kept in a separate `/opt/poetry` environment. Use the container
+for changes involving time zones, paths, native libraries, or other
+operating-system-dependent behavior. Standard Python 3.9 and Python 3.12
+installations remain covered by the existing CI matrix.

{cwms_cli-0.7.4 → cwms_cli-0.8.0}/cwmscli/__main__.py

@@ -7,10 +7,17 @@ import click
 from click.core import ParameterSource
 
 from cwmscli.commands import commands_cwms
+from cwmscli.commands.env import env_group
+from cwmscli.dss import dss_group
 from cwmscli.load import __main__ as load
 from cwmscli.usgs import usgs_group
 from cwmscli.utils.click_help import add_version_to_help_tree
-from cwmscli.utils.friendly_errors import to_user_facing_error
+from cwmscli.utils.friendly_errors import (
+    cda_stack_trace,
+    format_cda_stack_trace,
+    to_user_facing_error,
+)
+from cwmscli.utils.links import BUG_REPORT_URL
 from cwmscli.utils.logging import (
     LoggingConfig,
     apply_logging_policies,
@@ -88,7 +95,9 @@ cli.add_command(commands_cwms.update_cli_cmd)
 cli.add_command(commands_cwms.blob_group)
 cli.add_command(commands_cwms.clob_group)
 cli.add_command(commands_cwms.users_group)
+cli.add_command(env_group)
 cli.add_command(load.load_group)
+cli.add_command(dss_group)
 add_version_to_help_tree(cli)
 
 
@@ -111,9 +120,19 @@ def main() -> None:
     except SystemExit:
         raise
     except click.ClickException as e:
+        debug = debug or logging.getLogger().isEnabledFor(logging.DEBUG)
+        if debug:
+            server_stack_trace = cda_stack_trace(e)
+            if server_stack_trace is not None:
+                click.echo(format_cda_stack_trace(server_stack_trace), err=True)
+                raise SystemExit(e.exit_code)
         e.show()
         raise SystemExit(e.exit_code)
     except Exception as e:
+        # The environment switch supports failures before Click configures logging.
+        # Once CLI setup has run, --log-level DEBUG enables the same behavior.
+        debug = debug or logging.getLogger().isEnabledFor(logging.DEBUG)
+
         if is_cert_verify_error(e) and not debug:
             # Keep this short, no stack trace.
             logging.error(
@@ -122,14 +141,21 @@ def main() -> None:
             click.echo(ssl_help_text(), err=True)
             raise SystemExit(2)
 
-        if not debug:
+        if debug:
+            server_stack_trace = cda_stack_trace(e)
+            if server_stack_trace is not None:
+                click.echo(format_cda_stack_trace(server_stack_trace), err=True)
+                raise SystemExit(1)
+        else:
             friendly_error = to_user_facing_error(e)
             if friendly_error is not None:
                 logging.debug("Suppressed traceback for CLI exception", exc_info=e)
                 friendly_error.show()
                 raise SystemExit(friendly_error.exit_code)
 
-        # If debug is enabled (or it's not a cert verify error), keep the normal failure behavior.
+        click.echo(f"Unexpected error. Report it at {BUG_REPORT_URL}", err=True)
+        # Preserve raw exception behavior when CDA did not provide a server stack
+        # trace so an issue report includes useful diagnostic details.
         raise
 
 

{cwms_cli-0.7.4 → cwms_cli-0.8.0}/cwmscli/_generated/ownership_data.py

@@ -15,6 +15,16 @@ OWNERSHIP_DATA = {
                 "name": "Charles Graham"
             }
         ],
+        "cwms-cli env": [
+            {
+                "email": "mitchell.s.weier@usace.army.mil",
+                "name": "Mitch Weier"
+            },
+            {
+                "email": "charles.r.graham@usace.army.mil",
+                "name": "Charles Graham"
+            }
+        ],
         "cwms-cli load": [
             {
                 "email": "charles.r.graham@usace.army.mil",
@@ -25,7 +35,7 @@ OWNERSHIP_DATA = {
                 "name": "Eric Novotny"
             }
         ],
-        "cwms-cli shefcritimport": [
+        "cwms-cli shef": [
             {
                 "email": "eric.v.novotny@usace.army.mil",
                 "name": "Eric Novotny"

{cwms_cli-0.7.4 → cwms_cli-0.8.0}/cwmscli/commands/blob.py

@@ -613,12 +613,12 @@ def download_cmd(
     try:
         blob_content = cwms.get_blob(office_id=office, blob_id=bid)
         target = dest or _default_download_dest(bid)
-        _save_blob_content(
+        saved_target = _save_blob_content(
             blob_content,
             dest=target,
             media_type_hint=_blob_media_type(cwms, office, bid),
         )
-        logging.info(f"Downloaded blob to: {target}")
+        logging.info(f"Downloaded blob to: {saved_target}")
     except requests.HTTPError as e:
         detail = getattr(e.response, "text", "") or str(e)
         logging.error(f"Failed to download (HTTP): {detail}")
@@ -632,6 +632,7 @@ def download_cmd(
         sys.exit(1)
     except Exception as e:
         logging.error(format_local_download_error(e, BLOB_DOCS_URL))
+        # Local write/path failures are not CDA credential scope problems.
         if not isinstance(e, (OSError, ValueError)):
             log_scoped_read_hint(
                 credential_kind=credential_kind,

{cwms_cli-0.7.4 → cwms_cli-0.8.0}/cwmscli/commands/clob.py

@@ -12,10 +12,15 @@ from cwms import api as cwms_api
 from cwmscli.utils import (
     format_local_download_error,
     get_api_key,
+    get_saved_login_token,
     has_invalid_chars,
+    init_cwms_session,
     log_scoped_read_hint,
     validate_default_download_dest,
 )
+from cwmscli.utils.click_help import DOCS_BASE_URL
+
+CLOB_DOCS_URL = f"{DOCS_BASE_URL}/cli/clob.html"
 
 
 def _join_api_url(api_root: str, path: str) -> str:
@@ -28,6 +33,16 @@ def _resolve_optional_api_key(api_key: Optional[str], anonymous: bool) -> Option
     return get_api_key(api_key, None)
 
 
+def _resolve_credential_kind(api_key: Optional[str], anonymous: bool) -> Optional[str]:
+    if anonymous:
+        return None
+    if get_saved_login_token():
+        return "token"
+    if _resolve_optional_api_key(api_key, anonymous):
+        return "api_key"
+    return None
+
+
 def _write_clob_content(content: str, dest: str) -> str:
     os.makedirs(os.path.dirname(dest) or ".", exist_ok=True)
     with open(dest, "w", encoding="utf-8", newline="") as f:
@@ -36,12 +51,17 @@ def _write_clob_content(content: str, dest: str) -> str:
 
 
 def _default_download_dest(clob_id: str) -> str:
-    return validate_default_download_dest(clob_id, resource_name="Clob")
+    return validate_default_download_dest(
+        clob_id,
+        resource_name="Clob",
+        docs_url=CLOB_DOCS_URL,
+    )
 
 
 def _clob_endpoint_id(clob_id: str) -> tuple[str, Optional[str]]:
     normalized = clob_id.upper()
     if has_invalid_chars(normalized):
+        # Path-like IDs use the placeholder route and keep the real ID in query params.
         return "ignored", normalized
     return normalized, None
 
@@ -190,8 +210,8 @@ def download_cmd(
             f"DRY RUN: would GET {api_root} clob with clob-id={clob_id} office={office}."
         )
         return
-    resolved_api_key = _resolve_optional_api_key(api_key, anonymous)
-    cwms.init_session(api_root=api_root, api_key=resolved_api_key)
+    credential_kind = _resolve_credential_kind(api_key, anonymous)
+    init_cwms_session(cwms, api_root=api_root, api_key=api_key, anonymous=anonymous)
     bid = clob_id.upper()
     logging.debug(f"Office={office} clobID={bid}")
 
@@ -215,7 +235,7 @@ def download_cmd(
         detail = getattr(e.response, "text", "") or str(e)
         logging.error(f"Failed to download (HTTP): {detail}")
         log_scoped_read_hint(
-            api_key=resolved_api_key,
+            credential_kind=credential_kind,
             anonymous=anonymous,
             office=office,
             action="download",
@@ -223,7 +243,7 @@ def download_cmd(
         )
         sys.exit(1)
     except Exception as e:
-        logging.error(format_local_download_error(e, ""))
+        logging.error(format_local_download_error(e, CLOB_DOCS_URL))
         sys.exit(1)
 
 
@@ -305,8 +325,8 @@ def list_cmd(
     api_key: str,
     anonymous: bool = False,
 ):
-    resolved_api_key = _resolve_optional_api_key(api_key, anonymous)
-    cwms.init_session(api_root=api_root, api_key=resolved_api_key)
+    credential_kind = _resolve_credential_kind(api_key, anonymous)
+    init_cwms_session(cwms, api_root=api_root, api_key=api_key, anonymous=anonymous)
     try:
         df = list_clobs(
             office=office,
@@ -319,7 +339,7 @@ def list_cmd(
         )
     except Exception:
         log_scoped_read_hint(
-            api_key=resolved_api_key,
+            credential_kind=credential_kind,
             anonymous=anonymous,
             office=office,
             action="list",

{cwms_cli-0.7.4 → cwms_cli-0.8.0}/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.auth import DEFAULT_REDIRECT_HOST, DEFAULT_REDIRECT_PORT
 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(
@@ -492,13 +527,15 @@ def update_cli_cmd(target_version: Optional[str], pre: bool, yes: bool) -> None:
 @click.group(
     "blob",
     help="Manage CWMS Blobs (upload, download, delete, update, list)",
-    epilog=textwrap.dedent("""
+    epilog=textwrap.dedent(
+        """
     Example Usage:\n
     - Store a PDF/image as a CWMS blob with optional description\n
     - Download a blob by id to your local filesystem\n
     - Update a blob's name/description/mime-type\n
     - Bulk list blobs for an office  
-"""),
+"""
+    ),
 )
 def blob_group():
     pass
@@ -671,10 +708,15 @@ def update_cmd(**kwargs):
     show_default=True,
     help="Sort descending instead of ascending.",
 )
-@click.option("--limit", type=int, default=None, help="Max rows to show.")
+@click.option(
+    "--limit",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Max rows to show.",
+)
 @click.option(
     "--page-size",
-    type=int,
+    type=click.IntRange(min=1),
     default=None,
     help="Max rows to request from the blob endpoint. Defaults to --limit if set, otherwise no pagination (all results in one page).",
 )
@@ -706,12 +748,14 @@ def list_cmd(**kwargs):
 @click.group(
     "clob",
     help="Manage CWMS Clobs (upload, download, delete, update, list)",
-    epilog=textwrap.dedent("""
+    epilog=textwrap.dedent(
+        """
     Example Usage:\n
     - Download a clob by id to your local filesystem\n
     - Update a clob's name/description/mime-type\n
     - Bulk list clobs for an office  
-"""),
+"""
+    ),
 )
 @requires(reqs.cwms)
 def clob_group():
@@ -837,10 +881,15 @@ def update_cmd(**kwargs):
     show_default=True,
     help="Sort descending instead of ascending.",
 )
-@click.option("--limit", type=int, default=None, help="Max rows to show.")
+@click.option(
+    "--limit",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Max rows to show.",
+)
 @click.option(
     "--page-size",
-    type=int,
+    type=click.IntRange(min=1),
     default=None,
     help="Max rows to request from the clob endpoint. Defaults to --limit when set.",
 )