cwms-cli 0.1.1__tar.gz → 0.2.1__tar.gz

{cwms_cli-0.1.1 → cwms_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cwms-cli
-Version: 0.1.1
+Version: 0.2.1
 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
@@ -22,19 +22,28 @@ Description-Content-Type: text/markdown
 
 # cwms-cli
 
-command line utilities used for Corps Water Management Systems (CWMS) processes
+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/)
+[![Docs](https://readthedocs.org/projects/cwms-cli/badge/?version=latest)](https://cwms-cli.readthedocs.io/en/latest/) - 📖 Read the docs: https://cwms-cli.readthedocs.io/en/latest/
 
 ## Install
 
 ```sh
-pip install git+https://github.com/HydrologicEngineeringCenter/cwms-cli.git@main
+pip3 install git+https://github.com/HydrologicEngineeringCenter/cwms-cli.git@main
 ```
+Note: If you are on Windows OS, you may just need to use the command `pip`
 
 ## 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
+```
+

cwms_cli-0.2.1/README.md

@@ -0,0 +1,26 @@
+# 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/) - 📖 Read the docs: https://cwms-cli.readthedocs.io/en/latest/
+
+## Install
+
+```sh
+pip3 install git+https://github.com/HydrologicEngineeringCenter/cwms-cli.git@main
+```
+Note: If you are on Windows OS, you may just need to use the command `pip`
+
+## 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
+```

{cwms_cli-0.1.1 → cwms_cli-0.2.1}/cwmscli/__init__.py

@@ -1,5 +1,7 @@
 import logging as lg
 
+from cwmscli import load
+
 # create logging for logging
 logging = lg.getLogger()
 if logging.hasHandlers():

{cwms_cli-0.1.1 → cwms_cli-0.2.1}/cwmscli/__main__.py

@@ -1,6 +1,7 @@
 import click
 
 from cwmscli.commands import commands_cwms
+from cwmscli.load import __main__ as load
 from cwmscli.usgs import usgs_group
 
 
@@ -13,3 +14,4 @@ cli.add_command(usgs_group, name="usgs")
 cli.add_command(commands_cwms.shefcritimport)
 cli.add_command(commands_cwms.csv2cwms_cmd)
 cli.add_command(commands_cwms.blob_group)
+cli.add_command(load.load_group)

{cwms_cli-0.1.1 → cwms_cli-0.2.1}/cwmscli/commands/blob.py

@@ -7,10 +7,6 @@ import re
 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
 
@@ -27,22 +23,21 @@ DATA_URL_RE = re.compile(r"^data:(?P<mime>[^;]+);base64,(?P<data>.+)$", re.I | r
         "link": "https://docs.python.org/3/library/imghdr.html",
     }
 )
-def _determine_ext(data: bytes | str, write_type: str) -> str:
+def _determine_ext(data: bytes) -> 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 or base64 string to inspect.
-        write_type: The mode in which the data will be written ('wb' for binary, 'w' for text).
+        data: The binary data to inspect.
 
     Returns:
         The determined file extension, including the leading dot (e.g., '.png', '.jpg').
     """
     import imghdr
 
-    kind = imghdr.what(None, data)
+    kind: Optional[str] = imghdr.what(None, data)
     if kind == "jpeg":
         kind = "jpg"
     return f".{kind}" if kind else ".bin"
@@ -51,7 +46,7 @@ def _determine_ext(data: bytes | str, write_type: str) -> str:
 def _save_base64(
     b64_or_dataurl: str,
     dest: str,
-    media_type_hint: str | None = None,
+    media_type_hint: Optional[str] = None,
 ) -> str:
     m = DATA_URL_RE.match(b64_or_dataurl.strip())
     if m:
@@ -80,8 +75,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:
-            ext = _determine_ext(data, write_type)
+        if not ext and isinstance(data, bytes):
+            ext = _determine_ext(data)
         dest = base + ext
 
     os.makedirs(os.path.dirname(dest) or ".", exist_ok=True)
@@ -91,8 +86,11 @@ 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"))
 
@@ -146,13 +144,15 @@ def store_blob(**kwargs):
 
 
 def retrieve_blob(**kwargs):
-    blob_id = kwargs.get("blob_id", "")
+    import cwms
+    import requests
+
+    blob_id = kwargs.get("blob_id", "").upper()
     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,14 +174,17 @@ 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)
@@ -199,8 +202,11 @@ 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
@@ -229,7 +235,7 @@ def list_blobs(
     if limit is not None:
         df = df.head(limit)
 
-    logging.info(f"Found {len(df):,} blobs")
+    logging.info(f"Found {len(df):,} blob(s)")
     # List the blobs in the logger
     for _, row in df.iterrows():
         logging.info(f"Blob ID: {row['id']}, Description: {row.get('description')}")
@@ -241,77 +247,6 @@ 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,
@@ -323,7 +258,10 @@ def upload_cmd(
     api_root: str,
     api_key: str,
 ):
-    cwms.api.init_session(api_root=api_root, api_key=get_api_key(api_key, ""))
+    import cwms
+    import requests
+
+    cwms.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:
@@ -351,7 +289,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(
                 {
@@ -365,7 +303,7 @@ def upload_cmd(
         return
 
     try:
-        cwms.store_blobs(blob, fail_if_exists=overwrite)
+        cwms.store_blobs(blob, fail_if_exists=not 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:
@@ -377,8 +315,18 @@ def upload_cmd(
         sys.exit(1)
 
 
-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, ""))
+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, api_key=get_api_key(api_key, ""))
     bid = blob_id.upper()
     logging.debug(f"Office={office} BlobID={bid}")
 
@@ -396,18 +344,65 @@ def download_cmd(blob_id: str, dest: str, office: str, api_root: str, api_key: s
         sys.exit(1)
 
 
-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"
-    )
+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(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 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
+
+    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 list_cmd(
@@ -421,7 +416,10 @@ def list_cmd(
     api_root: str,
     api_key: str,
 ):
-    cwms.api.init_session(api_root=api_root, api_key=get_api_key(api_key, None))
+    import cwms
+    import pandas as pd
+
+    cwms.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,

{cwms_cli-0.1.1 → cwms_cli-0.2.1}/cwmscli/commands/commands_cwms.py

@@ -1,3 +1,5 @@
+import textwrap
+
 import click
 
 from cwmscli import requirements as reqs
@@ -23,6 +25,7 @@ from cwmscli.utils.deps import requires
 @requires(reqs.cwms)
 def shefcritimport(filename, office, api_root, api_key, api_key_loc):
     from cwmscli.commands.shef_critfile_import import import_shef_critfile
+    from cwmscli.utils import get_api_key
 
     api_key = get_api_key(api_key, api_key_loc)
     import_shef_critfile(
@@ -94,14 +97,16 @@ def csv2cwms_cmd(**kwargs):
 @click.group(
     "blob",
     help="Manage CWMS Blobs (upload, download, delete, update, list)",
-    epilog="""
-  * Store a PDF/image as a CWMS blob with optional description
-  * Download a blob by id to your local filesystem
-  * Update a blob's name/description
-  * Bulk list blobs for an office
-""",
+    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  
+"""
+    ),
 )
-@requires(reqs.cwms)
 def blob_group():
     pass
 
@@ -124,13 +129,14 @@ def blob_group():
     help="Override media type (guessed from file if omitted).",
 )
 @click.option(
-    "--overwrite/--no-overwrite",
+    "--overwrite",
     default=False,
     show_default=True,
     help="If true, replace existing blob.",
 )
 @click.option("--dry-run", is_flag=True, help="Show request; do not send.")
 @common_api_options
+@requires(reqs.cwms)
 def blob_upload(**kwargs):
     from cwmscli.commands.blob import upload_cmd
 
@@ -148,7 +154,9 @@ def blob_upload(**kwargs):
     default=None,
     help="Destination file path. Defaults to blob-id.",
 )
+@click.option("--dry-run", is_flag=True, help="Show request; do not send.")
 @common_api_options
+@requires(reqs.cwms)
 def blob_download(**kwargs):
     from cwmscli.commands.blob import download_cmd
 
@@ -158,9 +166,11 @@ def blob_download(**kwargs):
 # ================================================================================
 #       Delete
 # ================================================================================
-@blob_group.command("delete", help="[Not implemented] Delete a blob by ID")
+@blob_group.command("delete", help="Delete a blob by ID")
 @click.option("--blob-id", required=True, type=str, help="Blob ID to delete.")
+@click.option("--dry-run", is_flag=True, help="Show request; do not send.")
 @common_api_options
+@requires(reqs.cwms)
 def delete_cmd(**kwargs):
     from cwmscli.commands.blob import delete_cmd
 
@@ -170,15 +180,33 @@ def delete_cmd(**kwargs):
 # ================================================================================
 #       Update
 # ================================================================================
-@blob_group.command("update", help="[Not implemented] Update/patch a blob by ID")
+@blob_group.command("update", help="Update/patch a blob by ID")
 @click.option("--blob-id", required=True, type=str, help="Blob ID to update.")
+@click.option("--dry-run", is_flag=True, help="Show request; do not send.")
+@click.option(
+    "--description",
+    default=None,
+    help="New description JSON or text.",
+)
+@click.option(
+    "--media-type",
+    default=None,
+    help="New media type (guessed from file if omitted).",
+)
 @click.option(
     "--input-file",
     required=False,
     type=click.Path(exists=True, dir_okay=False, readable=True, path_type=str),
     help="Optional file content to upload with update.",
 )
+@click.option(
+    "--overwrite/--no-overwrite",
+    default=False,
+    show_default=True,
+    help="If true, replace existing blob.",
+)
 @common_api_options
+@requires(reqs.cwms)
 def update_cmd(**kwargs):
     from cwmscli.commands.blob import update_cmd
 
@@ -218,6 +246,7 @@ def update_cmd(**kwargs):
     help="If set, write results to this CSV file.",
 )
 @common_api_options
+@requires(reqs.cwms)
 def list_cmd(**kwargs):
     from cwmscli.commands.blob import list_cmd
 

cwms_cli-0.2.1/cwmscli/load/README.md

@@ -0,0 +1,7 @@
+# Loader Scripts
+
+This command supports loading data in some form or fashion.
+
+Initially it was intended to load data across from one CDA instance (GET) to another (POST). But could be expanded to other forms of loading including backloading jobs that potentially wrap existing other commands.
+
+It differs from the other scripts in that it is effectively a `CDA2CDA` script which is usually only needed for `loading` data in initial setups. (Dev/Docker Compose)

cwms_cli-0.2.1/cwmscli/load/__main__.py

@@ -0,0 +1,5 @@
+# cwmscli/load/__main__.py
+# Side-effect imports to register subcommands under `load_group`
+from cwmscli.load.location import location as _locations
+from cwmscli.load.root import load_group  # export for callers
+from cwmscli.load.timeseries import timeseries as _timeseries