cwms-cli 0.3.5__tar.gz → 0.3.7__tar.gz

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cwms-cli
-Version: 0.3.5
+Version: 0.3.7
 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
@@ -45,6 +45,11 @@ Or as of version `0.3.0+`
 cwms-cli update
 ```
 
+To install a specific version:
+```sh
+cwms-cli update --target-version 0.7.1 --yes
+```
+
 ## Command line implementation
 
 View the help in terminal:

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/README.md

@@ -22,6 +22,11 @@ Or as of version `0.3.0+`
 cwms-cli update
 ```
 
+To install a specific version:
+```sh
+cwms-cli update --target-version 0.7.1 --yes
+```
+
 ## Command line implementation
 
 View the help in terminal:

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/cwmscli/__main__.py

@@ -10,6 +10,7 @@ from cwmscli.commands import commands_cwms
 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.logging import (
     LoggingConfig,
     apply_logging_policies,
@@ -17,15 +18,18 @@ from cwmscli.utils.logging import (
     setup_logging,
 )
 from cwmscli.utils.ssl_errors import is_cert_verify_error, ssl_help_text
-from cwmscli.utils.version import get_cwms_cli_version
+from cwmscli.utils.version_cli import show_version_and_exit
 
 
 @click.group(context_settings=dict(help_option_names=["-h", "--help"]))
-@click.version_option(
-    get_cwms_cli_version(),
+@click.option(
     "--version",
     "-V",
-    message="cwms-cli version %(version)s",
+    is_flag=True,
+    is_eager=True,
+    expose_value=False,
+    callback=show_version_and_exit,
+    help="Show the cwms-cli version and exit.",
 )
 @click.option(
     "--log-file",
@@ -115,6 +119,13 @@ def main() -> None:
             click.echo(ssl_help_text(), err=True)
             raise SystemExit(2)
 
+        if not debug:
+            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.
         raise
 

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/cwmscli/commands/blob.py

@@ -133,6 +133,11 @@ def _resolve_optional_api_key(api_key: Optional[str], anonymous: bool) -> Option
     return get_api_key(api_key, None)
 
 
+def _response_status_code(exc: BaseException) -> Optional[int]:
+    response = getattr(exc, "response", None)
+    return getattr(response, "status_code", None)
+
+
 def store_blob(**kwargs):
     import cwms
     import requests
@@ -597,6 +602,7 @@ def download_cmd(
 
 def delete_cmd(blob_id: str, office: str, api_root: str, api_key: str, dry_run: bool):
     import cwms
+    import requests
 
     if dry_run:
         logging.info(
@@ -604,7 +610,17 @@ def delete_cmd(blob_id: str, office: str, api_root: str, api_key: str, dry_run:
         )
         return
     cwms.init_session(api_root=api_root, api_key=api_key)
-    cwms.delete_blob(office_id=office, blob_id=blob_id)
+    try:
+        cwms.delete_blob(office_id=office, blob_id=blob_id)
+    except requests.HTTPError as e:
+        if _response_status_code(e) == 404:
+            logging.info(
+                "Blob %s was already absent in office %s. Nothing to delete.",
+                blob_id,
+                office,
+            )
+            return
+        raise
     logging.info(f"Deleted blob: {blob_id} for office: {office}")
 
 

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/cwmscli/commands/commands_cwms.py

@@ -1,14 +1,21 @@
+import os
 import subprocess
 import sys
 import textwrap
+from typing import Optional
 
 import click
 
 from cwmscli import requirements as reqs
 from cwmscli.callbacks import csv_to_list
 from cwmscli.commands import csv2cwms
-from cwmscli.utils import api_key_loc_option, common_api_options, to_uppercase
+from cwmscli.utils import api_key_loc_option, colors, common_api_options, to_uppercase
 from cwmscli.utils.deps import requires
+from cwmscli.utils.update import (
+    build_update_package_spec,
+    launch_windows_update,
+    looks_like_missing_version,
+)
 from cwmscli.utils.version import get_cwms_cli_version
 
 
@@ -86,7 +93,16 @@ def csv2cwms_cmd(**kwargs):
     csv2_main(**kwargs)
 
 
-@click.command("update", help="Update cwms-cli to the latest version using pip.")
+@click.command(
+    "update",
+    help="Update cwms-cli with pip, optionally targeting a specific version.",
+)
+@click.option(
+    "--target-version",
+    "target_version",
+    metavar="VERSION",
+    help="Install a specific cwms-cli version instead of the latest release.",
+)
 @click.option(
     "--pre",
     is_flag=True,
@@ -100,32 +116,76 @@ def csv2cwms_cmd(**kwargs):
     default=False,
     help="Skip confirmation prompt and run update immediately.",
 )
-def update_cli_cmd(pre: bool, yes: bool) -> None:
+def update_cli_cmd(target_version: Optional[str], pre: bool, yes: bool) -> None:
     current_version = get_cwms_cli_version()
-    click.echo(f"Current cwms-cli version: {current_version}")
+    package_spec = build_update_package_spec(target_version)
 
-    cmd = [sys.executable, "-m", "pip", "install", "--upgrade", "cwms-cli"]
+    click.echo(
+        "Current cwms-cli version: " f"{colors.c(current_version, 'cyan', bright=True)}"
+    )
+    if target_version:
+        click.echo(
+            "Requested cwms-cli version: "
+            f"{colors.c(target_version, 'cyan', bright=True)}"
+        )
+    else:
+        click.echo("Requested cwms-cli version: latest available release")
+
+    cmd = [sys.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)
         if not proceed:
-            click.echo("Update canceled.")
+            click.echo(colors.warn("Update canceled."))
             return
 
     click.echo(f"Running: {' '.join(cmd)}")
+    if os.name == "nt":
+        try:
+            script_path = launch_windows_update(cmd)
+        except OSError as e:
+            raise click.ClickException(
+                f"Unable to launch Windows update process: {e}"
+            ) from e
+        click.echo(
+            colors.ok(
+                "Opened a separate command window to complete the update after "
+                "cwms-cli exits."
+            )
+        )
+        click.echo(f"Update helper script: {script_path}")
+        return
+
     try:
-        result = subprocess.run(cmd, check=False)
+        result = subprocess.run(
+            cmd,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
     except OSError as e:
         raise click.ClickException(f"Unable to run pip update command: {e}") from e
 
+    if result.stdout:
+        click.echo(result.stdout, nl=False)
+    if result.stderr:
+        click.echo(result.stderr, err=True, nl=False)
+
     if result.returncode != 0:
+        pip_output = "\n".join(part for part in [result.stdout, result.stderr] if part)
+        if target_version and looks_like_missing_version(pip_output, package_spec):
+            raise click.ClickException(
+                colors.err(
+                    f"Requested cwms-cli version '{target_version}' was not found."
+                )
+            )
         raise click.ClickException(
-            "cwms-cli update failed. Please review pip output above."
+            colors.err("cwms-cli update failed. Please review pip output above.")
         )
 
-    click.echo("Update complete. Run `cwms-cli --version` to verify.")
+    click.echo(colors.ok("Update complete. Run `cwms-cli --version` to verify."))
 
 
 # region Blob

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/cwmscli/commands/csv2cwms/tests/test_main.py

@@ -133,6 +133,41 @@ def test_load_timeseries_uses_raw_timestamps_when_rounding_disabled(monkeypatch)
     ]
 
 
+def test_load_timeseries_preserves_raw_value_when_precision_omitted(monkeypatch):
+    monkeypatch.setenv("CDA_API_KEY", "test-key")
+    monkeypatch.setenv("CDA_OFFICE", "SWT")
+    monkeypatch.setenv("CDA_HOST", "https://example.test")
+
+    csv2_main = importlib.import_module("cwmscli.commands.csv2cwms.__main__")
+    tz = csv2_main.safe_zoneinfo("UTC")
+    epoch = int(datetime(2025, 3, 25, 12, 7, tzinfo=tz).timestamp())
+
+    file_data = {
+        "header": ["Time", "Headwater"],
+        "data": {
+            epoch: ["2025-03-25 12:07", "10.12345"],
+        },
+        "source_timezone": tz,
+    }
+    config = {
+        "interval": 900,
+        "input_files": {
+            "BROK": {
+                "timeseries": {
+                    "BROK.Elev.Inst.15Minutes.0.Rev-SCADA-cda": {
+                        "columns": "Headwater",
+                        "units": "ft",
+                    }
+                }
+            }
+        },
+    }
+
+    result = csv2_main.load_timeseries(file_data, "BROK", config)
+
+    assert result[0]["values"] == [[epoch * 1000, 10.12345, 3]]
+
+
 def test_load_timeseries_rounds_to_configured_interval_when_present(monkeypatch):
     monkeypatch.setenv("CDA_API_KEY", "test-key")
     monkeypatch.setenv("CDA_OFFICE", "SWT")

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/cwmscli/commands/csv2cwms/transform.py

@@ -72,7 +72,8 @@ def select_value(
     else:
         value = raw_values[-1]
 
-    value = round(value, precision) if value is not None else None
+    if value is not None and precision is not None:
+        value = round(value, precision)
     quality = 3 if value is not None else 5
     return value, quality
 
@@ -154,7 +155,7 @@ def load_timeseries(file_data, file_key, config, logger):
     for name, meta in ts_config.items():
         expr = meta["columns"]
         units = meta.get("units", "")
-        precision = meta.get("precision", 2)
+        precision = meta.get("precision")
         ts_data = data
         ts_interval = interval
 

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/cwmscli/usgs/__init__.py

@@ -46,7 +46,7 @@ def getusgs_timeseries(office, days_back, api_root, api_key, api_key_loc, backfi
     from cwmscli.usgs.getusgs_cda import getusgs_cda
 
     if backfill is not None:
-        backfill_list = backfill.replace(" ", "").split(",")
+        backfill_list = [item.strip() for item in backfill.split(",") if item.strip()]
     else:
         backfill_list = None
 
@@ -78,7 +78,9 @@ def getusgs_ratings(office, days_back, api_root, api_key, api_key_loc, rating_su
     from cwmscli.usgs.getUSGS_ratings_cda import getusgs_rating_cda
 
     if rating_subset is not None:
-        rating_list = rating_subset.replace(" ", "").split(",")
+        rating_list = [
+            item.strip() for item in rating_subset.split(",") if item.strip()
+        ]
     else:
         rating_list = None
 
@@ -158,7 +160,9 @@ def getusgs_measurements(
         if "group" in backfill:
             backfill_group = True
         elif type(backfill) == str:
-            backfill_list = backfill.replace(" ", "").split(",")
+            backfill_list = [
+                item.strip() for item in backfill.split(",") if item.strip()
+            ]
     api_key = get_api_key(api_key, api_key_loc)
     getusgs_measurement_cda(
         api_root=api_root,

cwms_cli-0.3.7/cwmscli/utils/friendly_errors.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import json
+from typing import Iterable, Optional, Set
+
+import click
+
+
+class UserFacingError(click.ClickException):
+    def __init__(
+        self,
+        message: str,
+        hint: Optional[str] = None,
+        *,
+        exit_code: int = 1,
+    ) -> None:
+        self.hint = hint
+        self.exit_code = exit_code
+        full_message = message
+        if hint:
+            full_message = f"{full_message}\nHint: {hint}"
+        super().__init__(full_message)
+
+
+def _walk_exception_chain(exc: BaseException) -> Iterable[BaseException]:
+    seen: Set[int] = set()
+    cur: Optional[BaseException] = exc
+    while cur is not None and id(cur) not in seen:
+        seen.add(id(cur))
+        yield cur
+        cur = cur.__cause__ or cur.__context__
+
+
+def _response_text(response) -> str:
+    text = getattr(response, "text", None)
+    if text:
+        return str(text).strip()
+
+    content = getattr(response, "content", None)
+    if isinstance(content, bytes):
+        return content.decode("utf-8", errors="replace").strip()
+    if content:
+        return str(content).strip()
+    return ""
+
+
+def _response_json_field(response, field: str) -> Optional[str]:
+    text = _response_text(response)
+    if not text:
+        return None
+    try:
+        payload = json.loads(text)
+    except Exception:
+        return None
+    value = payload.get(field)
+    if value in (None, ""):
+        return None
+    return str(value)
+
+
+def _trim_message(message: str) -> str:
+    message = message.strip()
+    if not message:
+        return message
+    return message if message.endswith(".") else f"{message}."
+
+
+def _friendly_http_error(response) -> Optional[UserFacingError]:
+    status = getattr(response, "status_code", None)
+    if status is None:
+        return None
+
+    api_message = _response_json_field(response, "message")
+    incident_id = _response_json_field(response, "incidentIdentifier")
+
+    if status == 400:
+        return UserFacingError(
+            _trim_message(api_message or "CWMS rejected the request"),
+            "Check the command arguments and input values, then try again.",
+            exit_code=2,
+        )
+    if status in (401, 403):
+        return UserFacingError(
+            _trim_message(api_message or "Authentication failed while calling CWMS"),
+            "Check CDA_API_KEY, --api-key, and whether the account can access the requested office.",
+            exit_code=2,
+        )
+    if status == 404:
+        return UserFacingError(
+            _trim_message(api_message or "Requested CWMS resource was not found"),
+            "Verify the identifier, office, and any category or group arguments.",
+        )
+    if status == 409:
+        return UserFacingError(
+            _trim_message(api_message or "CWMS reported a conflict for this request"),
+            "Review overwrite or replace options and confirm the resource state before retrying.",
+        )
+    if status == 429:
+        return UserFacingError(
+            _trim_message(api_message or "CWMS rate limited the request"),
+            "Wait briefly and retry. If this persists, reduce request frequency.",
+        )
+    if isinstance(status, int) and status >= 500:
+        hint = "Retry later or contact the service owner."
+        if incident_id:
+            hint += f" Include incidentIdentifier {incident_id}."
+        return UserFacingError(
+            _trim_message(api_message or "CWMS returned a server error"),
+            hint,
+        )
+
+    return UserFacingError(
+        _trim_message(api_message or f"CWMS request failed with HTTP {status}"),
+        "Re-run with `CWMS_CLI_DEBUG=1` or `cwms-cli --log-level DEBUG ...etc` for a traceback if you need the raw exception details.",
+    )
+
+
+def _is_requests_exception(exc: BaseException, name: str) -> bool:
+    try:
+        import requests
+    except Exception:
+        return False
+
+    return isinstance(exc, getattr(requests.exceptions, name, ()))
+
+
+def to_user_facing_error(exc: BaseException) -> Optional[UserFacingError]:
+    for candidate in _walk_exception_chain(exc):
+        response = getattr(candidate, "response", None)
+        if response is not None:
+            friendly = _friendly_http_error(response)
+            if friendly is not None:
+                return friendly
+
+        if _is_requests_exception(candidate, "Timeout"):
+            return UserFacingError(
+                "Timed out while waiting for CWMS to respond.",
+                "Confirm the service is reachable and try again.",
+            )
+
+        if _is_requests_exception(candidate, "ConnectionError"):
+            return UserFacingError(
+                "Could not reach the CWMS API endpoint.",
+                "Check --api-root, network connectivity, and whether the server is running.",
+            )
+
+    return None

cwms_cli-0.3.7/cwmscli/utils/update.py

@@ -0,0 +1,61 @@
+import subprocess
+import tempfile
+from typing import List, Optional
+
+
+def build_update_package_spec(target_version: Optional[str]) -> str:
+    if target_version:
+        return f"cwms-cli=={target_version}"
+    return "cwms-cli"
+
+
+def looks_like_missing_version(pip_output: str, package_spec: str) -> bool:
+    return (
+        "No matching distribution found for" in pip_output
+        or "Could not find a version that satisfies the requirement" in pip_output
+    ) and package_spec in pip_output
+
+
+def write_windows_update_script(cmd: List[str]) -> str:
+    quoted_cmd = subprocess.list2cmdline(cmd)
+    script = "\r\n".join(
+        [
+            "@echo off",
+            "setlocal",
+            "echo Waiting for cwms-cli to exit before updating...",
+            "timeout /t 1 /nobreak >nul",
+            quoted_cmd,
+            'set "EXIT_CODE=%ERRORLEVEL%"',
+            'if "%EXIT_CODE%"=="0" (',
+            "  echo Update complete. Run cwms-cli --version to verify.",
+            ") else (",
+            "  echo.",
+            "  echo cwms-cli update failed. Review pip output above.",
+            ")",
+            "echo.",
+            "echo Press any key to close this window.",
+            "pause >nul",
+            '(goto) 2>nul & del "%~f0"',
+            "exit /b %EXIT_CODE%",
+            "",
+        ]
+    )
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix=".cmd",
+        delete=False,
+        encoding="utf-8",
+        newline="",
+    ) as fh:
+        fh.write(script)
+        return fh.name
+
+
+def launch_windows_update(cmd: List[str]) -> str:
+    script_path = write_windows_update_script(cmd)
+    creationflags = getattr(subprocess, "CREATE_NEW_CONSOLE", 0)
+    subprocess.Popen(
+        ["cmd.exe", "/c", script_path],
+        creationflags=creationflags,
+    )
+    return script_path

cwms_cli-0.3.7/cwmscli/utils/version.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+import re
+from functools import lru_cache
+from importlib import metadata
+from pathlib import Path
+from typing import Optional
+from urllib import error, request
+
+PYPI_JSON_URL = "https://pypi.org/pypi/cwms-cli/json"
+
+
+@lru_cache(maxsize=1)
+def get_cwms_cli_version() -> str:
+    """Return installed cwms-cli version, with pyproject fallback for source runs."""
+    try:
+        return metadata.version("cwms-cli")
+    except metadata.PackageNotFoundError:
+        pass
+
+    pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    if not pyproject.exists():
+        return "unknown"
+
+    text = pyproject.read_text(encoding="utf-8")
+
+    # Prefer the [tool.poetry] version declaration.
+    in_poetry_section = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("[") and stripped.endswith("]"):
+            in_poetry_section = stripped == "[tool.poetry]"
+            continue
+        if in_poetry_section:
+            m = re.match(r'^version\s*=\s*"([^"]+)"\s*$', stripped)
+            if m:
+                return m.group(1)
+
+    return "unknown"
+
+
+def _version_key(version: str) -> Optional[tuple[int, ...]]:
+    match = re.fullmatch(r"\d+(?:\.\d+)*", version.strip())
+    if not match:
+        return None
+    return tuple(int(part) for part in version.split("."))
+
+
+def is_newer_version_available(current_version: str, latest_version: str) -> bool:
+    current_key = _version_key(current_version)
+    latest_key = _version_key(latest_version)
+    if current_key is None or latest_key is None:
+        return False
+    return latest_key > current_key
+
+
+def get_latest_cwms_cli_version(timeout: float = 1.0) -> Optional[str]:
+    try:
+        with request.urlopen(PYPI_JSON_URL, timeout=timeout) as response:
+            payload = json.load(response)
+    except (OSError, ValueError, error.URLError):
+        return None
+
+    version = payload.get("info", {}).get("version")
+    if not isinstance(version, str) or not version.strip():
+        return None
+    return version.strip()

cwms_cli-0.3.7/cwmscli/utils/version_cli.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import click
+
+from cwmscli.utils import colors
+from cwmscli.utils.version import (
+    get_cwms_cli_version,
+    get_latest_cwms_cli_version,
+    is_newer_version_available,
+)
+
+
+def version_output_allows_color(
+    no_color: bool,
+    log_file: Optional[str],
+) -> bool:
+    return sys.stdout.isatty() and (not no_color) and (not log_file)
+
+
+def show_version_and_exit(
+    ctx: click.Context, _param: click.Parameter, value: bool
+) -> None:
+    if not value or ctx.resilient_parsing:
+        return
+
+    current_version = get_cwms_cli_version()
+    colors.set_enabled(
+        version_output_allows_color(
+            no_color=bool(ctx.params.get("no_color")),
+            log_file=ctx.params.get("log_file"),
+        )
+    )
+
+    click.echo(f"cwms-cli version {colors.c(current_version, 'cyan', bright=True)}")
+
+    latest_version = get_latest_cwms_cli_version()
+    if latest_version and is_newer_version_available(current_version, latest_version):
+        click.echo(
+            colors.warn("Newer version available: ")
+            + colors.c(latest_version, "yellow", bright=True)
+        )
+        click.echo(f"Run: {colors.c('cwms-cli update', 'cyan', bright=True)}")
+
+    ctx.exit()

{cwms_cli-0.3.5 → cwms_cli-0.3.7}/pyproject.toml

@@ -2,7 +2,7 @@
 name = "cwms-cli"
 repository = "https://github.com/HydrologicEngineeringCenter/cwms-cli"
 
-version = "0.3.5"
+version = "0.3.7"
 
 
 packages = [

cwms_cli-0.3.5/cwmscli/utils/version.py

@@ -1,35 +0,0 @@
-from __future__ import annotations
-
-import re
-from functools import lru_cache
-from importlib import metadata
-from pathlib import Path
-
-
-@lru_cache(maxsize=1)
-def get_cwms_cli_version() -> str:
-    """Return installed cwms-cli version, with pyproject fallback for source runs."""
-    try:
-        return metadata.version("cwms-cli")
-    except metadata.PackageNotFoundError:
-        pass
-
-    pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
-    if not pyproject.exists():
-        return "unknown"
-
-    text = pyproject.read_text(encoding="utf-8")
-
-    # Prefer the [tool.poetry] version declaration.
-    in_poetry_section = False
-    for line in text.splitlines():
-        stripped = line.strip()
-        if stripped.startswith("[") and stripped.endswith("]"):
-            in_poetry_section = stripped == "[tool.poetry]"
-            continue
-        if in_poetry_section:
-            m = re.match(r'^version\s*=\s*"([^"]+)"\s*$', stripped)
-            if m:
-                return m.group(1)
-
-    return "unknown"