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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: cwms-python
-Version: 0.7.1
+Version: 0.8.0
 Summary: Corps water management systems (CWMS) REST API for Data Retrieval of USACE water data
 License: LICENSE
 Keywords: USACE,water data,CWMS

{cwms_python-0.7.1 → cwms_python-0.8.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-0.8.0}/cwms/api.py

@@ -131,7 +131,6 @@ def init_session(
     """
 
     global SESSION
-
     if api_root:
         logging.debug(f"Initializing root URL: api_root={api_root}")
         SESSION = sessions.BaseUrlSession(base_url=api_root)
@@ -142,8 +141,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
 

{cwms_python-0.7.1 → cwms_python-0.8.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-0.8.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)

cwms_python-0.8.0/cwms/projects/water_supply/accounting.py

@@ -0,0 +1,145 @@
+#  Copyright (c) 2024
+#  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
+import cwms.api as api
+from cwms.cwms_types import JSON, Data
+
+
+def get_pump_accounting(
+    office_id: str,
+    project_id: str,
+    water_user: str,
+    contract_name: str,
+    start: str,
+    end: str,
+    timezone: str = "UTC",
+    unit: str = "cms",
+    start_time_inclusive: bool = True,
+    end_time_inclusive: bool = True,
+    ascending: bool = True,
+    row_limit: int = 0,
+) -> Data:
+    """
+    Retrieves pump accounting entries associated with a water supply contract.
+
+    Parameters
+    ----------
+    office_id : str
+        The office ID the pump accounting is associated with. (Path)
+    project_id : str
+        The project ID the pump accounting is associated with. (Path)
+    water_user : str
+        The water user the pump accounting is associated with. (Path)
+    contract_name : str
+        The name of the contract associated with the pump accounting. (Path)
+    start : str
+        The start time of the time window for pump accounting entries to retrieve.
+        Format: ISO 8601 extended, with optional offset and timezone. (Query)
+    end : str
+        The end time of the time window for pump accounting entries to retrieve.
+        Format: ISO 8601 extended, with optional offset and timezone. (Query)
+    timezone : str, optional
+        The default timezone to use if `start` or `end` lacks offset/timezone info.
+        Defaults to "UTC". (Query)
+    unit : str, optional
+        Unit of flow rate for accounting entries. Defaults to "cms". (Query)
+    start_time_inclusive : bool, optional
+        Whether the start time is inclusive. Defaults to True. (Query)
+    end_time_inclusive : bool, optional
+        Whether the end time is inclusive. Defaults to True. (Query)
+    ascending : bool, optional
+        Whether entries should be returned in ascending order. Defaults to True. (Query)
+    row_limit : int, optional
+        Maximum number of rows to return. Defaults to 0, meaning no limit. (Query)
+
+    Returns
+    -------
+    Data
+        The JSON response from CWMS Data API wrapped in a Data object.
+
+    Raises
+    ------
+    ValueError
+        If any required path parameters are None.
+    ClientError
+        If a 400-level error occurs.
+    NoDataFoundError
+        If a 404-level error occurs.
+    ServerError
+        If a 500-level error occurs.
+    """
+    if not all([office_id, project_id, water_user, contract_name, start, end]):
+        raise ValueError("All required parameters must be provided.")
+
+    endpoint = f"projects/{office_id}/{project_id}/water-user/{water_user}/contracts/{contract_name}/accounting"
+
+    params: dict[str, str | int] = {
+        "start": start,
+        "end": end,
+        "timezone": timezone,
+        "unit": unit,
+        "start-time-inclusive": str(start_time_inclusive).lower(),
+        "end-time-inclusive": str(end_time_inclusive).lower(),
+        "ascending": str(ascending).lower(),
+        "row-limit": row_limit,
+    }
+
+    response = api.get(endpoint, params, api_version=1)
+    return Data(response)
+
+
+def store_pump_accounting(
+    office: str,
+    project_id: str,
+    water_user: str,
+    contract_name: str,
+    data: JSON,
+) -> None:
+    """
+    Creates a new pump accounting entry associated with a water supply contract.
+
+    Parameters
+    ----------
+    office : str
+        The office ID the accounting is associated with. (Path)
+    project_id : str
+        The project ID the accounting is associated with. (Path)
+    water_user : str
+        The water user the accounting is associated with. (Path)
+    contract_name : str
+        The name of the contract associated with the accounting. (Path)
+    data : dict
+        A dictionary representing the JSON data to be stored. This should match the
+        WaterSupplyAccounting structure as defined by the API.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If any required argument is missing.
+    ClientError
+        If a 400 range error code response is returned from the server.
+    NoDataFoundError
+        If a 404 range error code response is returned from the server.
+    ServerError
+        If a 500 range error code response is returned from the server.
+    """
+    if not all([office, project_id, water_user, contract_name]):
+        raise ValueError(
+            "Office, project_id, water_user, and contract_name must be provided."
+        )
+    if not data:
+        raise ValueError("Data must be provided and cannot be empty.")
+
+    endpoint = f"projects/{office}/{project_id}/water-user/{water_user}/contracts/{contract_name}/accounting"
+    params = {
+        "office": office,
+        "project-id": project_id,
+        "water-user": water_user,
+        "contract-name": contract_name,
+    }
+    api.post(endpoint, data, params)

{cwms_python-0.7.1 → cwms_python-0.8.0}/pyproject.toml

@@ -2,7 +2,7 @@
 name = "cwms-python"
 repository = "https://github.com/HydrologicEngineeringCenter/cwms-python"
 
-version = "0.7.1"
+version = "0.8.0"
 
 
 packages = [