cwms-python 0.5.0__tar.gz → 0.6.0__tar.gz

{cwms_python-0.5.0 → cwms_python-0.6.0}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: cwms-python
-Version: 0.5.0
+Version: 0.6.0
 Summary: Corps water managerment systems (CWMS) REST API for Data Retrieval of USACE water data
 License: LICENSE
-Keywords: USACE,water data
+Keywords: USACE,water data,CWMS
 Author: Eric Novotny
 Author-email: eric.v.novotny@usace.army.mil
 Requires-Python: >=3.9,<4.0
@@ -13,10 +13,11 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Classifier: Programming Language :: Python :: 3.13
 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)
+Project-URL: Repository, https://github.com/HydrologicEngineeringCenter/cwms-python
 Description-Content-Type: text/markdown
 
 # CWMSpy
@@ -93,3 +94,13 @@ print(json)
  'version-date': None}
 ```
 
+## TimeSeries Profile API Compatibility Warning
+
+Currently, the TimeSeries Profile API may not be fully supported
+until a new version of cwms-data-access is released with the updated 
+endpoint implementation.
+
+## Contributing
+
+Please view the contribution documentation here: [CONTRIBUTING.md]
+

{cwms_python-0.5.0 → cwms_python-0.6.0}/README.md

@@ -71,3 +71,13 @@ print(json)
   ['2024-04-23T10:00:00', 86.57999999999997, 3]],
  'version-date': None}
 ```
+
+## TimeSeries Profile API Compatibility Warning
+
+Currently, the TimeSeries Profile API may not be fully supported
+until a new version of cwms-data-access is released with the updated 
+endpoint implementation.
+
+## Contributing
+
+Please view the contribution documentation here: [CONTRIBUTING.md]

{cwms_python-0.5.0 → cwms_python-0.6.0}/cwms/__init__.py

@@ -1,11 +1,16 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from cwms.api import *
+from cwms.catalog.blobs import *
 from cwms.catalog.catalog import *
+from cwms.catalog.clobs import *
+from cwms.datafile_imports.shef_critfile_import import *
 from cwms.forecast.forecast_instance import *
 from cwms.forecast.forecast_spec import *
 from cwms.levels.location_levels import *
 from cwms.levels.specified_levels import *
+from cwms.locations.gate_changes import *
+from cwms.locations.location_groups import *
 from cwms.locations.physical_locations import *
 from cwms.outlets.outlets import *
 from cwms.outlets.virtual_outlets import *
@@ -16,10 +21,15 @@ from cwms.ratings.ratings import *
 from cwms.ratings.ratings_spec import *
 from cwms.ratings.ratings_template import *
 from cwms.standard_text.standard_text import *
-from cwms.timeseries.timerseries_identifier import *
 from cwms.timeseries.timeseries import *
 from cwms.timeseries.timeseries_bin import *
+from cwms.timeseries.timeseries_group import *
+from cwms.timeseries.timeseries_identifier import *
+from cwms.timeseries.timeseries_profile import *
+from cwms.timeseries.timeseries_profile_instance import *
+from cwms.timeseries.timeseries_profile_parser import *
 from cwms.timeseries.timeseries_txt import *
+from cwms.turbines.turbines import *
 
 try:
     __version__ = version("cwms-python")

{cwms_python-0.5.0 → cwms_python-0.6.0}/cwms/api.py

@@ -1,4 +1,4 @@
-""" Session management and REST functions for CWMS Data API.
+"""Session management and REST functions for CWMS Data API.
 
 This module provides functions for making REST calls to the CWMS Data API (CDA). These
 functions should be used internally to interact with the API. The user should not have to
@@ -191,6 +191,7 @@ def get_xml(
 
     headers = {"Accept": api_version_text(api_version)}
     response = SESSION.get(endpoint, params=params, headers=headers)
+    response.close()
 
     if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
@@ -228,6 +229,7 @@ def get(
 
     headers = {"Accept": api_version_text(api_version)}
     response = SESSION.get(endpoint, params=params, headers=headers)
+    response.close()
     if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
         raise ApiError(response)
@@ -307,10 +309,11 @@ def post(
     # post requires different headers than get for
     headers = {"accept": "*/*", "Content-Type": api_version_text(api_version)}
 
-    if isinstance(data, dict):
+    if isinstance(data, dict) or isinstance(data, list):
         data = json.dumps(data)
 
     response = SESSION.post(endpoint, params=params, headers=headers, data=data)
+    response.close()
 
     if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
@@ -346,10 +349,10 @@ def patch(
     if data is None:
         response = SESSION.patch(endpoint, params=params, headers=headers)
     else:
-        if isinstance(data, dict):
+        if isinstance(data, dict) or isinstance(data, list):
             data = json.dumps(data)
         response = SESSION.patch(endpoint, params=params, headers=headers, data=data)
-
+    response.close()
     if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
         raise ApiError(response)
@@ -377,7 +380,7 @@ def delete(
 
     headers = {"Accept": api_version_text(api_version)}
     response = SESSION.delete(endpoint, params=params, headers=headers)
-
+    response.close()
     if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
         raise ApiError(response)

cwms_python-0.6.0/cwms/catalog/blobs.py

@@ -0,0 +1,85 @@
+from typing import Optional
+
+import cwms.api as api
+from cwms.cwms_types import JSON, Data
+
+
+def get_blob(blob_id: str, office_id: str) -> Data:
+    """Get a single clob.
+
+    Parameters
+        ----------
+            blob_id: string
+                Specifies the id of the blob
+            office_id: string
+                Specifies the office of the blob.
+
+
+        Returns
+        -------
+            cwms data type.  data.json will return the JSON output and data.df will return a dataframe
+    """
+
+    endpoint = f"blobs/{blob_id}"
+    params = {"office": office_id}
+    response = api.get(endpoint, params, api_version=1)
+    return Data(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=1)
+    return Data(response, selector="blobs")
+
+
+def store_blobs(data: JSON, fail_if_exists: Optional[bool] = True) -> None:
+    """Create New Blob
+
+    Parameters
+        ----------
+            Data: JSON dictionary
+                JSON containing information of Blob to be updated
+                    {
+                    "office-id": "string",
+                    "id": "string",
+                    "description": "string",
+                    "media-type-id": "string",
+                    "value": "string"
+                    }
+            fail_if_exists: Boolean
+                Create will fail if provided ID already exists. Default: true
+
+        Returns
+        -------
+            None
+    """
+
+    if not isinstance(data, dict):
+        raise ValueError("Cannot store a Blob without a JSON data dictionary")
+
+    endpoint = "blobs"
+    params = {"fail-if-exists": fail_if_exists}
+
+    return api.post(endpoint, data, params, api_version=1)

cwms_python-0.6.0/cwms/catalog/clobs.py

@@ -0,0 +1,158 @@
+from typing import Optional
+
+import cwms.api as api
+from cwms.cwms_types import JSON, Data
+
+
+def get_clob(clob_id: str, office_id: str, clob_id_query: Optional[str] = None) -> Data:
+    """Get a single clob.
+
+    Parameters
+        ----------
+            clob_id: string
+                Specifies the id of the clob
+            office_id: string
+                Specifies the office of the clob.
+            clob_id_query: string
+                If this query parameter is provided the id path parameter is ignored and the
+                value of the query parameter is used. Note: this query parameter is necessary
+                for id's that contain '/' or other special characters. Because of abuse even
+                properly escaped '/' in url paths are blocked. When using this query parameter
+                a valid path parameter must still be provided for the request to be properly
+                routed. If your clob id contains '/' you can't specify the clob-id query
+                parameter and also specify the id path parameter because firewall and/or server
+                rules will deny the request even though you are specifying this override. "ignored"
+                is suggested.
+
+
+        Returns
+        -------
+            cwms data type.  data.json will return the JSON output and data.df will return a dataframe
+    """
+
+    endpoint = f"clobs/{clob_id}"
+    params = {
+        "office": office_id,
+        "clob-id-query": clob_id_query,
+    }
+    response = api.get(endpoint, params)
+    return Data(response)
+
+
+def get_clobs(
+    office_id: Optional[str] = None,
+    page_size: Optional[int] = 100,
+    include_values: Optional[bool] = False,
+    clob_id_like: Optional[str] = None,
+) -> Data:
+    """Get a subset of Clobs
+
+    Parameters
+        ----------
+            office_id: Optional[string]
+                Specifies the office of the clob.
+            page_sie: Optional[Integer]
+                How many entries per page returned. Default 100.
+            include_values: Optional[Boolean]
+                Do you want the value associated with this particular clob (default: false)
+            clob_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 = "clobs"
+    params = {
+        "office": office_id,
+        "page-size": page_size,
+        "include-values": include_values,
+        "like": clob_id_like,
+    }
+
+    response = api.get(endpoint, params)
+    return Data(response, selector="clobs")
+
+
+def delete_clob(clob_id: str, office_id: str) -> None:
+    """Deletes requested clob
+
+    Parameters
+        ----------
+            clob_id: string
+                Specifies the id of the clob to be deleted
+            office_id: string
+                Specifies the office of the clob.
+
+        Returns
+        -------
+            None
+    """
+
+    endpoint = f"clobs/{clob_id}"
+    params = {"office": office_id}
+
+    return api.delete(endpoint, params=params, api_version=1)
+
+
+def update_clob(data: JSON, clob_id: str, ignore_nulls: Optional[bool] = True) -> None:
+    """Updates clob
+
+    Parameters
+        ----------
+            Data: JSON dictionary
+                JSON containing information of Clob to be updated
+                   {
+                        "office-id": "string",
+                        "id": "string",
+                        "description": "string",
+                        "value": "string"
+                    }
+            clob_id: string
+                Specifies the id of the clob to be deleted
+            ignore_nulls: Boolean
+                If true, null and empty fields in the provided clob will be ignored and the existing value of those fields left in place. Default: true
+
+        Returns
+        -------
+            None
+    """
+
+    if not isinstance(data, dict):
+        raise ValueError("Cannot store a Clob without a JSON data dictionary")
+
+    endpoint = f"clobs/{clob_id}"
+    params = {"ignore-nulls": ignore_nulls}
+
+    return api.patch(endpoint, data, params, api_version=1)
+
+
+def store_clobs(data: JSON, fail_if_exists: Optional[bool] = True) -> None:
+    """Create New Clob
+
+    Parameters
+        ----------
+            Data: JSON dictionary
+                JSON containing information of Clob to be updated
+                   {
+                        "office-id": "string",
+                        "id": "string",
+                        "description": "string",
+                        "value": "string"
+                    }
+            fail_if_exists: Boolean
+                Create will fail if provided ID already exists. Default: true
+
+        Returns
+        -------
+            None
+    """
+
+    if not isinstance(data, dict):
+        raise ValueError("Cannot store a Clob without a JSON data dictionary")
+
+    endpoint = "clobs"
+    params = {"fail-if-exists": fail_if_exists}
+
+    return api.post(endpoint, data, params, api_version=1)

{cwms_python-0.5.0 → cwms_python-0.6.0}/cwms/cwms_types.py

@@ -2,7 +2,7 @@ from copy import deepcopy
 from enum import Enum, auto
 from typing import Any, Optional
 
-from pandas import DataFrame, Index, json_normalize, to_datetime
+from pandas import DataFrame, Index, json_normalize, to_datetime, to_numeric
 
 # Describes generic JSON serializable data.
 JSON = dict[str, Any]
@@ -62,6 +62,7 @@ class Data:
         def rating_type(data: JSON) -> DataFrame:
             # grab the correct point values for a rating table
             df = DataFrame(data["point"]) if data["point"] else DataFrame()
+            df = df.apply(to_numeric)
             return df
 
         def timeseries_type(orig_json: JSON, value_json: JSON) -> DataFrame:

cwms_python-0.6.0/cwms/datafile_imports/shef_critfile_import.py

@@ -0,0 +1,130 @@
+import re
+from typing import Dict, List
+
+import pandas as pd
+
+import cwms
+
+
+def import_critfile_to_ts_group(
+    file_path: str,
+    office_id: str,
+    group_id: str = "SHEF Data Acquisition",
+    category_id: str = "Data Acquisition",
+    group_office_id: str = "CWMS",
+    category_office_id: str = "CWMS",
+    replace_assigned_ts: bool = False,
+) -> None:
+    """
+    Processes a .crit file and saves the information to the SHEF Data Acquisition time series group.
+
+    Parameters
+    ----------
+    file_path : str
+        Path to the .crit file.
+    office_id : str
+        The ID of the office associated with the specified timeseries.
+    group_id : str, optional
+        The specified group associated with the timeseries data. Defaults to "SHEF Data Acquisition".
+    category_id : str, optional
+        The category ID that contains the timeseries group. Defaults to "Data Acquisition".
+    group_office_id : str, optional
+        The specified office group associated with the timeseries data. Defaults to "CWMS".
+    replace_assigned_ts : bool, optional
+        Specifies whether to unassign all existing time series before assigning new time series specified in the content body. Default is False.
+
+    Returns
+    -------
+    None
+    """
+
+    def parse_crit_file(file_path: str) -> List[Dict[str, str]]:
+        """
+        Parses a .crit file into a dictionary containing timeseries ID and Alias.
+
+        Parameters
+        ----------
+            file_path : str
+                   Path to the .crit file.
+
+        Returns
+        -------
+        List[Dict[str, str]]
+            A list of dictionaries with "Alias" and "Timeseries ID" as keys.
+        """
+        parsed_data = []
+        with open(file_path, "r") as file:
+            for line in file:
+                # Ignore comment lines and empty lines
+                if line.startswith("#") or not line.strip():
+                    continue
+
+                # Extract alias, timeseries ID, and TZ
+                match = re.match(r"([^=]+)=([^;]+);(.+)", line.strip())
+
+                if match:
+                    alias = match.group(1).strip()
+                    timeseries_id = match.group(2).strip()
+                    alias2 = match.group(3).strip()
+
+                    parsed_data.append(
+                        {
+                            "Alias": alias + ":" + alias2,
+                            "Timeseries ID": timeseries_id,
+                        }
+                    )
+
+        return parsed_data
+
+    def append_df(
+        df: pd.DataFrame, office_id: str, ts_id: str, alias: str
+    ) -> pd.DataFrame:
+        """
+        Appends a row to the DataFrame.
+
+        Parameters
+        ----------
+            df : pandas.DataFrame
+                The DataFrame to append to.
+            office_id : str
+                The ID of the office associated with the specified timeseries.
+            tsId : str
+                The timeseries ID from the file.
+            alias : str
+                The alias from the file.
+        Returns
+        -------
+        pandas.DataFrame
+            The updated DataFrame.
+        """
+        data = {
+            "office-id": [office_id],
+            "timeseries-id": [ts_id],
+            "alias-id": [alias],
+        }
+        df = pd.concat([df, pd.DataFrame(data)])
+        return df
+
+    # Parse the file and get the parsed data
+    parsed_data = parse_crit_file(file_path)
+
+    df = pd.DataFrame()
+    for data in parsed_data:
+        # Create DataFrame for the current row
+        df = append_df(df, office_id, data["Timeseries ID"], data["Alias"])
+
+    # Generate JSON dictionary
+    json_dict = cwms.timeseries_group_df_to_json(
+        data=df,
+        group_id=group_id,
+        group_office_id=group_office_id,
+        category_office_id=category_office_id,
+        category_id=category_id,
+    )
+
+    cwms.update_timeseries_groups(
+        group_id=group_id,
+        office_id=office_id,
+        replace_assigned_ts=replace_assigned_ts,
+        data=json_dict,
+    )