cwms-python 0.7.1__tar.gz → 1.0.0__tar.gz

{cwms_python-0.7.1 → cwms_python-1.0.0}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: cwms-python
-Version: 0.7.1
+Version: 1.0.0
 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.7.1 → cwms_python-1.0.0}/cwms/__init__.py

@@ -17,6 +17,7 @@ from cwms.outlets.virtual_outlets import *
 from cwms.projects.project_lock_rights import *
 from cwms.projects.project_locks import *
 from cwms.projects.projects import *
+from cwms.projects.water_supply.accounting import *
 from cwms.ratings.ratings import *
 from cwms.ratings.ratings_spec import *
 from cwms.ratings.ratings_template import *

{cwms_python-0.7.1 → cwms_python-1.0.0}/cwms/api.py

@@ -131,8 +131,9 @@ 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(
@@ -142,8 +143,10 @@ def init_session(
         )
         SESSION.mount("https://", adapter)
     if api_key:
+        if api_key.startswith("apikey "):
+            api_key = api_key.replace("apikey ", "")
         logging.debug(f"Setting authorization key: api_key={api_key}")
-        SESSION.headers.update({"Authorization": api_key})
+        SESSION.headers.update({"Authorization": "apikey " + api_key})
 
     return SESSION
 
@@ -212,6 +215,27 @@ 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")
+        # 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,
@@ -240,24 +264,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(
@@ -300,6 +307,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,
@@ -319,22 +345,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.0/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.7.1 → cwms_python-1.0.0}/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.7.1 → cwms_python-1.0.0}/cwms/cwms_types.py

@@ -79,6 +79,44 @@ class Data:
                 df["date-time"] = to_datetime(df["date-time"], unit="ms", utc=True)
             return df
 
+        def reorder_measurement_cols(df: DataFrame) -> DataFrame:
+            # reorders measurement columns for usability
+
+            # Define the columns to bring to the front
+            front_columns = [
+                "id.office-id",
+                "id.name",
+                "number",
+                "instant",
+                "streamflow-measurement.gage-height",
+                "streamflow-measurement.flow",
+                "streamflow-measurement.quality",
+                "used",
+                "agency",
+                "wm-comments",
+            ]
+
+            # Identify columns containing 'unit' to be last
+            unit_columns = [col for col in df.columns if "unit" in col]
+
+            # Identify remaining columns (not in front_columns or unit_columns)
+            remaining_columns = [
+                col
+                for col in df.columns
+                if col not in front_columns and col not in unit_columns
+            ]
+
+            # Construct the new column order
+            new_column_order = front_columns + remaining_columns + unit_columns
+
+            # Filter out columns that might not actually exist in the DataFrame.
+            existing_columns = [col for col in new_column_order if col in df.columns]
+
+            # Reorder the DataFrame
+            df = df[existing_columns]
+
+            return df
+
         data = deepcopy(json)
 
         if selector:
@@ -95,6 +133,9 @@ class Data:
                 df = json_normalize(df_data) if df_data else DataFrame()
         else:
             df = json_normalize(data)
+            # if streamflow-measurement reorder columns
+            if "streamflow-measurement.flow" in df.columns:
+                df = reorder_measurement_cols(df)
 
         return df
 

{cwms_python-0.7.1 → cwms_python-1.0.0}/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.7.1 → cwms_python-1.0.0}/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.7.1 → cwms_python-1.0.0}/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.7.1 → cwms_python-1.0.0}/cwms/measurements/measurements.py

@@ -116,8 +116,15 @@ def store_measurements(
         "fail-if-exists": fail_if_exists,
     }
 
-    if not isinstance(data, dict):
-        raise ValueError("Cannot store a timeseries without a JSON data dictionary")
+    if not isinstance(data, list):
+        raise ValueError(
+            "Cannot store a measurement without a JSON list, object is not a list of dictionaries"
+        )
+    for item in data:
+        if not isinstance(item, dict):
+            raise ValueError(
+                "Cannot store a measurement without a JSON list: a non-dictionary object was found"
+            )
 
     return api.post(endpoint, data, params, api_version=1)
 
@@ -175,3 +182,28 @@ def delete_measurements(
     }
 
     return api.delete(endpoint, params, api_version=1)
+
+
+def get_measurements_extents(
+    office_mask: Optional[str] = None,
+) -> Data:
+    """Get time extents of streamflow measurements
+
+    Parameters
+    ----------
+        office_mask: string
+            Office Id used to filter the results.
+
+    Returns
+    -------
+        cwms data type.  data.json will return the JSON output and data.df will return a dataframe. Dates returned are all in UTC.
+
+    """
+    endpoint = "measurements/time-extents"
+
+    params = {
+        "office-mask": office_mask,
+    }
+
+    response = api.get(endpoint, params, api_version=1)
+    return Data(response)  # , selector=selector)