cwms-python 0.8.0__tar.gz → 1.0.1__tar.gz

{cwms_python-0.8.0 → cwms_python-1.0.1}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: cwms-python
-Version: 0.8.0
+Version: 1.0.1
 Summary: Corps water management systems (CWMS) REST API for Data Retrieval of USACE water data
 License: LICENSE
+License-File: LICENSE
 Keywords: USACE,water data,CWMS
 Author: Eric Novotny
 Author-email: eric.v.novotny@usace.army.mil
@@ -14,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: pandas (>=2.1.3,<3.0.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
 Requires-Dist: requests-toolbelt (>=1.0.0,<2.0.0)

{cwms_python-0.8.0 → cwms_python-1.0.1}/cwms/api.py

@@ -29,6 +29,7 @@ the error.
 import base64
 import json
 import logging
+from http import HTTPStatus
 from json import JSONDecodeError
 from typing import Any, Optional, cast
 
@@ -72,9 +73,9 @@ class InvalidVersion(Exception):
 class ApiError(Exception):
     """CWMS Data Api Error.
 
-    This class is a light wrapper around a `requests.Response` object. Its primary purpose
-    is to generate an error message that includes the request URL and provide additional
-    information to the user to help them resolve the error.
+    Light wrapper around a response-like object (e.g., requests.Response or a
+    test stub with url, status_code, reason, and content attributes). Produces
+    a concise, single-line error message with an optional hint.
     """
 
     def __init__(self, response: Response):
@@ -91,23 +92,37 @@ class ApiError(Exception):
         message += "."
 
         # Add additional context to help the user resolve the issue.
-        if hint := self.hint():
+        hint = self.hint()
+        if hint:
             message += f" {hint}"
 
-        if content := self.response.content:
-            message += f" {content.decode('utf8')}"
+        # Optional content (decoded if bytes)
+        content = getattr(self.response, "content", None)
+        if content:
+            if isinstance(content, bytes):
+                try:
+                    text = content.decode("utf-8", errors="replace")
+                except Exception:
+                    text = repr(content)
+            else:
+                text = str(content)
+            message += f" {text}"
 
         return message
 
     def hint(self) -> str:
-        """Return a message with additional information on how to resolve the error."""
+        """Return a short hint based on HTTP status code."""
+        status = getattr(self.response, "status_code", None)
 
-        if self.response.status_code == 400:
+        if status == 429:
+            return "Too many requests made."
+        if status == 400:
             return "Check that your parameters are correct."
-        elif self.response.status_code == 404:
+        if status == 404:
             return "May be the result of an empty query."
-        else:
-            return ""
+
+        # No hint for other codes
+        return ""
 
 
 def init_session(
@@ -132,6 +147,8 @@ def init_session(
 
     global SESSION
     if api_root:
+        # Ensure the API_ROOT ends with a single slash
+        api_root = api_root.rstrip("/") + "/"
         logging.debug(f"Initializing root URL: api_root={api_root}")
         SESSION = sessions.BaseUrlSession(base_url=api_root)
         adapter = adapters.HTTPAdapter(
@@ -213,6 +230,33 @@ def get_xml(
     return get(endpoint=endpoint, params=params, api_version=api_version)
 
 
+def _process_response(response: Response) -> Any:
+    try:
+        # Avoid case sensitivity issues with the content type header
+        content_type = response.headers.get("Content-Type", "").lower()
+        # Most CDA content is JSON
+        if "application/json" in content_type or not content_type:
+            return cast(JSON, response.json())
+        # Use automatic charset detection with .text
+        if "text/plain" in content_type or "text/" in content_type:
+            return response.text
+        if content_type.startswith("image/"):
+            return base64.b64encode(response.content).decode("utf-8")
+        # Handle excel content types
+        if content_type in [
+            "application/vnd.ms-excel",
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ]:
+            return response.content
+        # Fallback for remaining content types
+        return response.content.decode("utf-8")
+    except JSONDecodeError as error:
+        logging.error(
+            f"Error decoding CDA response as JSON: {error} on line {error.lineno}\n\tFalling back to text"
+        )
+        return response.text
+
+
 def get(
     endpoint: str,
     params: Optional[RequestParams] = None,
@@ -241,24 +285,7 @@ def get(
         if not response.ok:
             logging.error(f"CDA Error: response={response}")
             raise ApiError(response)
-        try:
-            # Avoid case sensitivity issues with the content type header
-            content_type = response.headers.get("Content-Type", "").lower()
-            # Most CDA content is JSON
-            if "application/json" in content_type or not content_type:
-                return cast(JSON, response.json())
-            # Use automatic charset detection with .text
-            if "text/plain" in content_type or "text/" in content_type:
-                return response.text
-            if content_type.startswith("image/"):
-                return base64.b64encode(response.content).decode("utf-8")
-            # Fallback for remaining content types
-            return response.content.decode("utf-8")
-        except JSONDecodeError as error:
-            logging.error(
-                f"Error decoding CDA response as JSON: {error} on line {error.lineno}\n\tFalling back to text"
-            )
-            return response.text
+        return _process_response(response)
 
 
 def get_with_paging(
@@ -301,6 +328,25 @@ def get_with_paging(
     return response
 
 
+def _post_function(
+    endpoint: str,
+    data: Any,
+    params: Optional[RequestParams] = None,
+    *,
+    api_version: int = API_VERSION,
+) -> Any:
+
+    # post requires different headers than get for
+    headers = {"accept": "*/*", "Content-Type": api_version_text(api_version)}
+    if isinstance(data, dict) or isinstance(data, list):
+        data = json.dumps(data)
+    with SESSION.post(endpoint, params=params, headers=headers, data=data) as response:
+        if not response.ok:
+            logging.error(f"CDA Error: response={response}")
+            raise ApiError(response)
+        return response
+
+
 def post(
     endpoint: str,
     data: Any,
@@ -320,22 +366,43 @@ def post(
             the default API_VERSION will be used.
 
     Returns:
-        The deserialized JSON response data.
+        None
 
     Raises:
         ApiError: If an error response is return by the API.
     """
+    _post_function(endpoint=endpoint, data=data, params=params, api_version=api_version)
 
-    # post requires different headers than get for
-    headers = {"accept": "*/*", "Content-Type": api_version_text(api_version)}
 
-    if isinstance(data, dict) or isinstance(data, list):
-        data = json.dumps(data)
+def post_with_returned_data(
+    endpoint: str,
+    data: Any,
+    params: Optional[RequestParams] = None,
+    *,
+    api_version: int = API_VERSION,
+) -> Any:
+    """Make a POST request to the CWMS Data API.
 
-    with SESSION.post(endpoint, params=params, headers=headers, data=data) as response:
-        if not response.ok:
-            logging.error(f"CDA Error: response={response}")
-            raise ApiError(response)
+    Args:
+        endpoint: The CDA endpoint for the record type.
+        data: A dict containing the new record data. Must be JSON-serializable.
+        params (optional): Query parameters for the request.
+
+    Keyword Args:
+        api_version (optional): The CDA version to use for the request. If not specified,
+            the default API_VERSION will be used.
+
+    Returns:
+        The response data.
+
+    Raises:
+        ApiError: If an error response is return by the API.
+    """
+
+    response = _post_function(
+        endpoint=endpoint, data=data, params=params, api_version=api_version
+    )
+    return _process_response(response)
 
 
 def patch(

cwms_python-1.0.1/cwms/catalog/blobs.py

@@ -0,0 +1,148 @@
+import base64
+from typing import Optional
+
+import cwms.api as api
+from cwms.cwms_types import JSON, Data
+from cwms.utils.checks import is_base64
+
+STORE_DICT = """data = {
+    "office-id": "SWT",
+    "id": "MYFILE_OR_BLOB_ID.TXT",
+    "description": "Your description here",
+    "media-type-id": "text/plain",
+    "value": "STRING of content or BASE64_ENCODED_STRING"
+}
+"""
+
+
+def get_blob(blob_id: str, office_id: str) -> str:
+    """Get a single BLOB (Binary Large Object).
+
+    Parameters
+        blob_id: string
+            Specifies the id of the blob. ALL blob ids are UPPERCASE.
+        office_id: string
+            Specifies the office of the blob.
+
+
+    Returns
+        str: the value returned based on the content-type it was stored with as a string
+    """
+
+    endpoint = f"blobs/{blob_id}"
+    params = {"office": office_id}
+    response = api.get(endpoint, params, api_version=1)
+    return str(response)
+
+
+def get_blobs(
+    office_id: Optional[str] = None,
+    page_size: Optional[int] = 100,
+    blob_id_like: Optional[str] = None,
+) -> Data:
+    """Get a subset of Blobs
+
+    Parameters:
+        office_id: Optional[string]
+            Specifies the office of the blob.
+        page_sie: Optional[Integer]
+            How many entries per page returned. Default 100.
+        blob_id_like: Optional[string]
+            Posix regular expression matching against the clob id
+
+    Returns:
+        cwms data type.  data.json will return the JSON output and data.df will return a dataframe
+    """
+
+    endpoint = "blobs"
+    params = {"office": office_id, "page-size": page_size, "like": blob_id_like}
+
+    response = api.get(endpoint, params, api_version=2)
+    return Data(response, selector="blobs")
+
+
+def store_blobs(data: JSON, fail_if_exists: Optional[bool] = True) -> None:
+    """Create New Blob
+
+    Parameters:
+        **Note**: The "id" field is automatically cast to uppercase.
+
+        Data: JSON dictionary
+            JSON containing information of Blob to be updated.
+
+        fail_if_exists: Boolean
+            Create will fail if the provided ID already exists. Default: True
+
+    Returns:
+        None
+    """
+
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"Cannot store a Blob without a JSON data dictionary:\n{STORE_DICT}"
+        )
+
+    # Encode value if it's not already Base64-encoded
+    if "value" in data and not is_base64(data["value"]):
+        # Encode to bytes, then Base64, then decode to string for storing
+        data["value"] = base64.b64encode(data["value"].encode("utf-8")).decode("utf-8")
+
+    endpoint = "blobs"
+    params = {"fail-if-exists": fail_if_exists}
+    return api.post(endpoint, data, params, api_version=1)
+
+
+def delete_blob(blob_id: str, office_id: str) -> None:
+    """Delete a single BLOB.
+
+    Parameters
+    ----------
+        blob_id: string
+            Specifies the id of the blob. ALL blob ids are UPPERCASE.
+        office_id: string
+            Specifies the office of the blob.
+
+    Returns
+    -------
+        None
+    """
+
+    endpoint = f"blobs/{blob_id}"
+    params = {"office": office_id}
+    return api.delete(endpoint, params, api_version=1)
+
+
+def update_blob(data: JSON, fail_if_not_exists: Optional[bool] = True) -> None:
+    """Update Existing Blob
+
+    Parameters:
+        **Note**: The "id" field is automatically cast to uppercase.
+
+        Data: JSON dictionary
+            JSON containing information of Blob to be updated.
+
+        fail_if_not_exists: Boolean
+            Update will fail if the provided ID does not already exist. Default: True
+
+    Returns:
+        None
+    """
+
+    if not data:
+        raise ValueError(
+            f"Cannot update a Blob without a JSON data dictionary:\n{STORE_DICT}"
+        )
+
+    if "id" not in data:
+        raise ValueError(f"Cannot update a Blob without an 'id' field:\n{STORE_DICT}")
+
+    # Encode value if it's not already Base64-encoded
+    if "value" in data and not is_base64(data["value"]):
+        # Encode to bytes, then Base64, then decode to string for storing
+        data["value"] = base64.b64encode(data["value"].encode("utf-8")).decode("utf-8")
+
+    blob_id = data.get("id", "").upper()
+
+    endpoint = f"blobs/{blob_id}"
+    params = {"fail-if-not-exists": fail_if_not_exists}
+    return api.patch(endpoint, data, params, api_version=1)

{cwms_python-0.8.0 → cwms_python-1.0.1}/cwms/catalog/catalog.py

@@ -1,4 +1,7 @@
-from typing import Optional
+from datetime import datetime
+from typing import Optional, Tuple
+
+import pandas as pd
 
 import cwms.api as api
 from cwms.cwms_types import Data
@@ -130,3 +133,34 @@ def get_timeseries_catalog(
 
     response = api.get(endpoint=endpoint, params=params, api_version=2)
     return Data(response, selector="entries")
+
+
+def get_ts_extents(ts_id: str, office_id: str) -> Tuple[datetime, datetime, datetime]:
+    """Retrieves earliest extent, latest extent, and last update via cwms.get_timeseries_catalog
+
+    Parameters
+    ----------
+        ts_id: string
+            Timseries id to query.
+        office_id: string
+            The owning office of the timeseries group.
+
+    Returns
+    -------
+        tuple of datetime objects (earliest_time, latest_time, last_update)
+    """
+    cwms_cat = get_timeseries_catalog(
+        office_id=office_id,
+        like=ts_id,
+        timeseries_group_like=None,
+        page_size=500,
+        include_extents=True,
+    ).df
+
+    times = cwms_cat[cwms_cat.name == ts_id].extents.values[0][0]
+
+    earliest_time = pd.to_datetime(times["earliest-time"])
+    latest_time = pd.to_datetime(times["latest-time"])
+    last_update = pd.to_datetime(times["last-update"])
+
+    return earliest_time, latest_time, last_update

{cwms_python-0.8.0 → cwms_python-1.0.1}/cwms/levels/location_levels.py

@@ -13,7 +13,7 @@ from cwms.cwms_types import JSON, Data
 
 
 def get_location_levels(
-    level_id_mask: str = "*",
+    level_id_mask: Optional[str] = None,
     office_id: Optional[str] = None,
     unit: Optional[str] = None,
     datum: Optional[str] = None,
@@ -58,13 +58,13 @@ def get_location_levels(
         "level-id-mask": level_id_mask,
         "unit": unit,
         "datum": datum,
-        "begin": begin.isoformat() if begin else "",
-        "end": end.isoformat() if end else "",
+        "begin": begin.isoformat() if begin else None,
+        "end": end.isoformat() if end else None,
         "page": page,
         "page-size": page_size,
     }
-    response = api.get(endpoint, params)
-    return Data(response)
+    response = api.get(endpoint=endpoint, params=params)
+    return Data(json=response, selector="levels")
 
 
 def get_location_level(
@@ -169,6 +169,35 @@ def delete_location_level(
     return api.delete(endpoint, params)
 
 
+def update_location_level(
+    data: JSON, level_id: str, effective_date: Optional[datetime] = None
+) -> None:
+    """
+    Parameters
+    ----------
+    data : dict
+        The JSON data dictionary containing the updated location level information.
+    level_id : str
+        The ID of the location level to be updated.
+    effective_date : datetime, optional
+        The effective date of the location level to be updated.
+        If the datetime has a timezone it will be used, otherwise it is assumed to be in UTC.
+
+    """
+    if data is None:
+        raise ValueError(
+            "Cannot update a location level without a JSON data dictionary"
+        )
+    if level_id is None:
+        raise ValueError("Cannot update a location level without an id")
+    endpoint = f"levels/{level_id}"
+
+    params = {
+        "effective-date": (effective_date.isoformat() if effective_date else None),
+    }
+    return api.patch(endpoint, data, params)
+
+
 def get_level_as_timeseries(
     location_level_id: str,
     office_id: str,

{cwms_python-0.8.0 → cwms_python-1.0.1}/cwms/locations/location_groups.py

@@ -85,6 +85,84 @@ def get_location_groups(
     return Data(response)
 
 
+def location_group_df_to_json(
+    data: pd.DataFrame,
+    group_id: str,
+    group_office_id: str,
+    category_office_id: str,
+    category_id: str,
+) -> JSON:
+    """
+    Converts a dataframe to a json dictionary in the correct format.
+
+    Parameters
+    ----------
+        data: pd.DataFrame
+            Dataframe containing timeseries information.
+        group_id: str
+            The group ID for the timeseries.
+        office_id: str
+            The ID of the office associated with the specified timeseries.
+        category_id: str
+            The ID of the category associated with the group
+
+    Returns
+    -------
+    JSON
+        JSON dictionary of the timeseries data.
+    """
+    df = data.copy()
+    required_columns = ["office-id", "location-id"]
+    optional_columns = ["alias-id", "attribute", "ref-location-id"]
+    for column in required_columns:
+        if column not in df.columns:
+            raise TypeError(
+                f"{column} is a required column in data when posting as a dataframe"
+            )
+
+    if df[required_columns].isnull().any().any():
+        raise ValueError(
+            f"Null/NaN values found in required columns: {required_columns}. "
+        )
+
+    # Fill optional columns with default values if missing
+    if "alias-id" not in df.columns:
+        df["alias-id"] = None
+    if "attribute" not in df.columns:
+        df["attribute"] = 0
+
+    # Replace NaN with None for optional columns
+    for column in optional_columns:
+        if column in df.columns:
+            df[column] = df[column].where(pd.notnull(df[column]), None)
+
+    # Build the list of time-series entries
+    assigned_locs = df.apply(
+        lambda entry: {
+            "office-id": entry["office-id"],
+            "location-id": entry["location-id"],
+            "alias-id": entry["alias-id"],
+            "attribute": entry["attribute"],
+            **(
+                {"ref-location-id": entry["ref-location-id"]}
+                if "ref-location-id" in entry and pd.notna(entry["ref-location-id"])
+                else {}
+            ),
+        },
+        axis=1,
+    ).tolist()
+
+    # Construct the final JSON dictionary
+    json_dict = {
+        "office-id": group_office_id,
+        "id": group_id,
+        "location-category": {"office-id": category_office_id, "id": category_id},
+        "assigned-locations": assigned_locs,
+    }
+
+    return json_dict
+
+
 def store_location_groups(data: JSON) -> None:
     """
     Create new Location Group
@@ -140,7 +218,12 @@ def update_location_group(
     api.patch(endpoint=endpoint, data=data, params=params, api_version=1)
 
 
-def delete_location_group(group_id: str, category_id: str, office_id: str) -> None:
+def delete_location_group(
+    group_id: str,
+    category_id: str,
+    office_id: str,
+    cascade_delete: Optional[bool] = False,
+) -> None:
     """Deletes requested time series group
 
     Parameters
@@ -161,6 +244,7 @@ def delete_location_group(group_id: str, category_id: str, office_id: str) -> No
     params = {
         "office": office_id,
         "category-id": category_id,
+        "cascade-delete": cascade_delete,
     }
 
     return api.delete(endpoint, params=params, api_version=1)

{cwms_python-0.8.0 → cwms_python-1.0.1}/cwms/locations/physical_locations.py

@@ -128,7 +128,7 @@ def delete_location(
     return api.delete(endpoint, params=params)
 
 
-def store_location(data: JSON) -> None:
+def store_location(data: JSON, fail_if_exists: bool = True) -> None:
     """
     This method is used to store and update location's data through CWMS Data API.
 
@@ -137,6 +137,10 @@ def store_location(data: JSON) -> None:
         data : dict
             A dictionary representing the JSON data to be stored.
             If the `data` value is None, a `ValueError` will be raised.
+        fail_if_exists : bool, optional
+            A boolean value indicating whether to fail if the outlet already exists.
+            Default is True.
+
 
     Returns
     -------
@@ -148,8 +152,8 @@ def store_location(data: JSON) -> None:
         raise ValueError("Storing location requires a JSON data dictionary")
 
     endpoint = "locations"
-
-    return api.post(endpoint, data)
+    params = {"fail-if-exists": fail_if_exists}
+    return api.post(endpoint, data, params=params)
 
 
 def update_location(location_id: str, data: JSON) -> None:

{cwms_python-0.8.0 → cwms_python-1.0.1}/cwms/projects/water_supply/accounting.py

@@ -2,6 +2,8 @@
 #  United States Army Corps of Engineers - Hydrologic Engineering Center (USACE/HEC)
 #  All Rights Reserved.  USACE PROPRIETARY/CONFIDENTIAL.
 #  Source may not be released without written approval from HEC
+from typing import Union
+
 import cwms.api as api
 from cwms.cwms_types import JSON, Data
 
@@ -74,7 +76,7 @@ def get_pump_accounting(
 
     endpoint = f"projects/{office_id}/{project_id}/water-user/{water_user}/contracts/{contract_name}/accounting"
 
-    params: dict[str, str | int] = {
+    params: dict[str, Union[str, int]] = {
         "start": start,
         "end": end,
         "timezone": timezone,