feat: consume report packages for CLI rendering

.gitignore

@@ -191,6 +191,14 @@ cython_debug/
 # Ruff stuff:
 .ruff_cache/
 
+# Rendered report outputs from local `cwms-cli report generate` runs.
+/*.html
+/*.pdf
+/report*.txt
+/wm_daily_*.txt
+/KEYS*.txt
+/.tmp_reports/
+
 # PyPI configuration file
 .pypirc
 

README.md

@@ -4,6 +4,8 @@ A collection of scripts to create, read, update, list, and delete data through C
 
 [![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/
 
+[![Docs](https://readthedocs.org/projects/cwms-cli/badge/?version=latest)](https://cwms-cli.readthedocs.io/en/latest/)
+
 ## Install
 
 ```sh

cwmscli/__main__.py

@@ -7,6 +7,7 @@
 
 from cwmscli.commands import commands_cwms
 from cwmscli.load import __main__ as load
+from cwmscli.reporting import report_cli
 from cwmscli.usgs import usgs_group
 from cwmscli.utils.click_help import add_version_to_help_tree
 from cwmscli.utils.logging import LoggingConfig, setup_logging
@@ -54,6 +55,7 @@ def cli(log_file: Optional[str], no_color: bool, log_level: str) -> None:
 cli.add_command(commands_cwms.csv2cwms_cmd)
 cli.add_command(commands_cwms.update_cli_cmd)
 cli.add_command(commands_cwms.blob_group)
+cli.add_command(report_cli)
 cli.add_command(load.load_group)
 add_version_to_help_tree(cli)
 

cwmscli/commands/blob.py

@@ -7,6 +7,10 @@
 import sys
 from typing import Optional, Sequence
 
+import cwms
+import pandas as pd
+import requests
+
 from cwmscli.utils import get_api_key
 from cwmscli.utils.deps import requires
 
@@ -23,21 +27,22 @@
         "link": "https://docs.python.org/3/library/imghdr.html",
     }
 )
-def _determine_ext(data: bytes) -> str:
+def _determine_ext(data: bytes | str, write_type: str) -> str:
     """
     Attempt to determine the file extension from the data itself.
     Requires the imghdr module (lazy import) to inspect the bytes for image types.
     If not an image, defaults to .bin
 
     Args:
-        data: The binary data to inspect.
+        data: The binary data or base64 string to inspect.
+        write_type: The mode in which the data will be written ('wb' for binary, 'w' for text).
 
     Returns:
         The determined file extension, including the leading dot (e.g., '.png', '.jpg').
     """
     import imghdr
 
-    kind: Optional[str] = imghdr.what(None, data)
+    kind = imghdr.what(None, data)
     if kind == "jpeg":
         kind = "jpg"
     return f".{kind}" if kind else ".bin"
@@ -46,7 +51,7 @@ def _determine_ext(data: bytes) -> str:
 def _save_base64(
     b64_or_dataurl: str,
     dest: str,
-    media_type_hint: Optional[str] = None,
+    media_type_hint: str | None = None,
 ) -> str:
     m = DATA_URL_RE.match(b64_or_dataurl.strip())
     if m:
@@ -75,8 +80,8 @@ def _save_base64(
                 ext = ".jpg"
         # last resort, try to determine from the data itself
         # requires imghdr to dig into the bytes to determine image type
-        if not ext and isinstance(data, bytes):
-            ext = _determine_ext(data)
+        if not ext:
+            ext = _determine_ext(data, write_type)
         dest = base + ext
 
     os.makedirs(os.path.dirname(dest) or ".", exist_ok=True)
@@ -86,11 +91,8 @@ def _save_base64(
 
 
 def store_blob(**kwargs):
-    import cwms
-    import requests
-
     file_data = kwargs.get("file_data")
-    blob_id = kwargs.get("blob_id", "").upper()
+    blob_id = kwargs.get("blob_id").upper()
     # Attempt to determine what media type should be used for the mime-type if one is not presented based on the file extension
     media = kwargs.get("media_type") or get_media_type(kwargs.get("input_file"))
 
@@ -144,15 +146,13 @@ def store_blob(**kwargs):
 
 
 def retrieve_blob(**kwargs):
-    import cwms
-    import requests
-
-    blob_id = kwargs.get("blob_id", "").upper()
+    blob_id = kwargs.get("blob_id", "")
     if not blob_id:
         logging.warning(
             "Valid blob_id required to download a blob. cwms-cli blob download --blob-id=myid. Run the list directive to see options for your office."
         )
         sys.exit(0)
+    blob_id = blob_id.upper()
     logging.debug(f"Office: {kwargs.get('office')}  Blob ID: {blob_id}")
     try:
         blob = cwms.get_blob(
@@ -174,17 +174,14 @@ def retrieve_blob(**kwargs):
 
 
 def delete_blob(**kwargs):
-    import cwms
-    import requests
-
     blob_id = kwargs.get("blob_id").upper()
     logging.debug(f"Office: {kwargs.get('office')}  Blob ID: {blob_id}")
 
     try:
-        cwms.delete_blob(
-            office_id=kwargs.get("office"),
-            blob_id=kwargs.get("blob_id").upper(),
-        )
+        # cwms.delete_blob(
+        #     office_id=kwargs.get("office"),
+        #     blob_id=kwargs.get("blob_id").upper(),
+        # )
         logging.info(f"Successfully deleted blob with ID: {blob_id}")
     except requests.HTTPError as e:
         details = getattr(e.response, "text", "") or str(e)
@@ -202,11 +199,8 @@ def list_blobs(
     sort_by: Optional[Sequence[str]] = None,
     ascending: bool = True,
     limit: Optional[int] = None,
-):
+) -> pd.DataFrame:
     logging.info(f"Listing blobs for office: {office!r}...")
-    import cwms
-    import pandas as pd
-
     result = cwms.get_blobs(office_id=office, blob_id_like=blob_id_like)
 
     # Accept either a DataFrame or a JSON/dict-like response
@@ -235,7 +229,7 @@ def list_blobs(
     if limit is not None:
         df = df.head(limit)
 
-    logging.info(f"Found {len(df):,} blob(s)")
+    logging.info(f"Found {len(df):,} blobs")
     # List the blobs in the logger
     for _, row in df.iterrows():
         logging.info(f"Blob ID: {row['id']}, Description: {row.get('description')}")
@@ -247,6 +241,77 @@ def get_media_type(file_path: str) -> str:
     return mime_type or "application/octet-stream"
 
 
+def main(
+    directive: str,
+    input_file: str,
+    blob_id: str,
+    description: Optional[str],
+    media_type: Optional[str],
+    office: str,
+    api_root: str,
+    api_key: str,
+    overwrite: Optional[bool] = True,
+    dry_run: Optional[bool] = False,
+):
+    """
+    Upload, Download, Delete, or Update blob data in CWMS.
+
+    DIRECTIVE is the action to perform (upload, download, delete, update).
+    INPUT_FILE is the path to the file on disk.
+    BLOB_ID   is the blob ID to store under.
+    """
+
+    cwms.api.init_session(api_root=api_root, api_key=api_key)
+    file_data = None
+    if directive in ["upload", "update"]:
+        if not input_file or not os.path.isfile(input_file):
+            logging.warning(
+                "Valid input_file required for upload/update. Use --input-file to specify."
+            )
+            sys.exit(0)
+        try:
+            file_size = os.path.getsize(input_file)
+            with open(input_file, "rb") as f:
+                file_data = f.read()
+            logging.info(f"Read file: {input_file} ({file_size} bytes)")
+        except Exception as e:
+            logging.error(f"Failed to read file: {e}")
+            sys.exit(1)
+
+    # Determine what should be done based on directive
+    if directive == "upload":
+        store_blob(
+            office=office,
+            api_root=api_root,
+            input_file=input_file,
+            blob_id=blob_id,
+            description=description,
+            media_type=media_type,
+            file_data=file_data,
+            overwrite=overwrite,
+            dry_run=dry_run,
+        )
+    elif directive == "list":
+        list_blobs(office=office, blob_id_like=blob_id, sort_by="blob_id")
+    elif directive == "download":
+        retrieve_blob(
+            office=office,
+            blob_id=blob_id,
+        )
+    elif directive == "delete":
+        # TODO: Delete endpoint does not exist in cwms-python yet
+        logging.warning(
+            "[NOT IMPLEMENTED] Delete Blob is not supported yet!\n\thttps://github.com/HydrologicEngineeringCenter/cwms-python/issues/192"
+        )
+        pass
+    elif directive == "update":
+        # TODO: Patch endpoint does not exist in cwms-python yet
+        logging.warning(
+            "[NOT IMPLEMENTED] Update Blob is not supported yet! Consider overwriting instead if a rename is not needed.\n\thttps://github.com/HydrologicEngineeringCenter/cwms-python/issues/192"
+        )
+        pass
+
+
 def upload_cmd(
     input_file: str,
     blob_id: str,
@@ -258,10 +323,7 @@ def upload_cmd(
     api_root: str,
     api_key: str,
 ):
-    import cwms
-    import requests
-
-    cwms.init_session(api_root=api_root, api_key=get_api_key(api_key, ""))
+    cwms.api.init_session(api_root=api_root, api_key=get_api_key(api_key, ""))
     try:
         file_size = os.path.getsize(input_file)
         with open(input_file, "rb") as f:
@@ -289,7 +351,7 @@ def upload_cmd(
     params = {"fail-if-exists": not overwrite}
 
     if dry_run:
-        logging.info(f"DRY RUN: would POST {api_root}blobs with params={params}")
+        logging.info(f"--dry-run: would POST {api_root}blobs with params={params}")
         logging.info(
             json.dumps(
                 {
@@ -303,7 +365,7 @@ def upload_cmd(
         return
 
     try:
-        cwms.store_blobs(blob, fail_if_exists=not overwrite)
+        cwms.store_blobs(blob, fail_if_exists=overwrite)
         logging.info(f"Uploaded blob: {blob_id_up}")
         logging.info(f"View: {api_root}blobs/{blob_id_up}?office={office}")
     except requests.HTTPError as e:
@@ -315,18 +377,8 @@ def upload_cmd(
         sys.exit(1)
 
 
-def download_cmd(
-    blob_id: str, dest: str, office: str, api_root: str, api_key: str, dry_run: bool
-):
-    import cwms
-    import requests
-
-    if dry_run:
-        logging.info(
-            f"DRY RUN: would GET {api_root} blob with blob-id={blob_id} office={office}."
-        )
-        return
-    cwms.init_session(api_root=api_root)
+def download_cmd(blob_id: str, dest: str, office: str, api_root: str, api_key: str):
+    cwms.api.init_session(api_root=api_root, api_key=get_api_key(api_key, ""))
     bid = blob_id.upper()
     logging.debug(f"Office={office} BlobID={bid}")
 
@@ -344,65 +396,18 @@ def download_cmd(
         sys.exit(1)
 
 
-def delete_cmd(blob_id: str, office: str, api_root: str, api_key: str, dry_run: bool):
-    import cwms
-
-    if dry_run:
-        logging.info(
-            f"DRY RUN: would DELETE {api_root} blob with blob-id={blob_id} office={office}"
-        )
-        return
-    cwms.init_session(api_root=api_root, api_key=api_key)
-    cwms.delete_blob(office_id=office, blob_id=blob_id)
-    logging.info(f"Deleted blob: {blob_id} for office: {office}")
-
-
-def update_cmd(
-    input_file: str,
-    blob_id: str,
-    description: str,
-    media_type: str,
-    overwrite: bool,
-    dry_run: bool,
-    office: str,
-    api_root: str,
-    api_key: str,
-):
-    import cwms
+def delete_cmd(blob_id: str, office: str, api_root: str, api_key: str):
+    logging.warning(
+        "[NOT IMPLEMENTED] Delete Blob is not supported yet.\n"
+        "See: https://github.com/HydrologicEngineeringCenter/cwms-python/issues/192"
+    )
 
-    if dry_run:
-        logging.info(
-            f"DRY RUN: would PATCH {api_root} blob with blob-id={blob_id} office={office}"
-        )
-        return
-    file_data = None
-    if input_file:
-        try:
-            file_size = os.path.getsize(input_file)
-            with open(input_file, "rb") as f:
-                file_data = f.read()
-            logging.info(f"Read file: {input_file} ({file_size} bytes)")
-        except Exception as e:
-            logging.error(f"Failed to read file: {e}")
-            sys.exit(1)
-    # Setup minimum required payload
-    blob = {"office-id": office, "id": blob_id.upper()}
-    if description:
-        blob["description"] = description
-    if media_type:
-        blob["media-type-id"] = media_type
-    else:
-        logging.info("Media type not specified; Retrieving existing media type...")
-        blob_metadata = cwms.get_blobs(office_id=office, blob_id_like=blob_id)
-        blob["media-type-id"] = blob_metadata.df.get(
-            "media-type-id", "application/octet-stream"
-        )[0]
-        logging.info(f"Using existing media type: {blob['media-type-id']}")
 
-    if file_data:
-        blob["value"] = base64.b64encode(file_data).decode("utf-8")
-    cwms.init_session(api_root=api_root, api_key=api_key)
-    cwms.update_blob(blob, fail_if_not_exists=not overwrite)
+def update_cmd(blob_id: str, input_file: str, office: str, api_root: str, api_key: str):
+    logging.warning(
+        "[NOT IMPLEMENTED] Update Blob is not supported yet. Consider --overwrite with upload.\n"
+        "See: https://github.com/HydrologicEngineeringCenter/cwms-python/issues/192"
+    )
 
 
 def list_cmd(
@@ -416,10 +421,7 @@ def list_cmd(
     api_root: str,
     api_key: str,
 ):
-    import cwms
-    import pandas as pd
-
-    cwms.init_session(api_root=api_root)
+    cwms.api.init_session(api_root=api_root, api_key=get_api_key(api_key, None))
     df = list_blobs(
         office=office,
         blob_id_like=blob_id_like,