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

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

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: cwms-python
-Version: 0.4.4
+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
@@ -49,7 +50,7 @@ from datetime import datetime, timedelta
 
 end = datetime.now()
 begin = end - timedelta(days = 10)
-data = cwms.get_timeseries(ts_id_='Some.Fully.Qualified.Ts.Id',office_id='OFFICE1' , begin = begin, end = end)
+data = cwms.get_timeseries(ts_id='Some.Fully.Qualified.Ts.Id',office_id='OFFICE1' , begin = begin, end = end)
 
 #a cwms data object will be provided this object containes both the JSON as well
 #as the values converted into a dataframe
@@ -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.4.4 → cwms_python-0.6.0}/README.md

@@ -28,7 +28,7 @@ from datetime import datetime, timedelta
 
 end = datetime.now()
 begin = end - timedelta(days = 10)
-data = cwms.get_timeseries(ts_id_='Some.Fully.Qualified.Ts.Id',office_id='OFFICE1' , begin = begin, end = end)
+data = cwms.get_timeseries(ts_id='Some.Fully.Qualified.Ts.Id',office_id='OFFICE1' , begin = begin, end = end)
 
 #a cwms data object will be provided this object containes both the JSON as well
 #as the values converted into a dataframe
@@ -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.6.0/cwms/__init__.py

@@ -0,0 +1,37 @@
+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 *
+from cwms.projects.project_lock_rights import *
+from cwms.projects.project_locks import *
+from cwms.projects.projects import *
+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.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")
+except PackageNotFoundError:
+    __version__ = "version-unknown"

{cwms_python-0.4.4 → 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
@@ -31,18 +31,20 @@ import logging
 from json import JSONDecodeError
 from typing import Any, Optional, cast
 
-from requests import Response
+from requests import Response, adapters
 from requests_toolbelt import sessions  # type: ignore
 from requests_toolbelt.sessions import BaseUrlSession  # type: ignore
 
-from cwms.types import JSON, RequestParams
+from cwms.cwms_types import JSON, RequestParams
 
 # Specify the default API root URL and version.
 API_ROOT = "https://cwms-data.usace.army.mil/cwms-data/"
 API_VERSION = 2
 
-# Initialize a non-authenticated session with the default root URL.
+# Initialize a non-authenticated session with the default root URL and set default pool connections.
 SESSION = sessions.BaseUrlSession(base_url=API_ROOT)
+adapter = adapters.HTTPAdapter(pool_connections=100, pool_maxsize=100)
+SESSION.mount("https://", adapter)
 
 
 class InvalidVersion(Exception):
@@ -91,7 +93,10 @@ class ApiError(Exception):
 
 
 def init_session(
-    *, api_root: Optional[str] = None, api_key: Optional[str] = None
+    *,
+    api_root: Optional[str] = None,
+    api_key: Optional[str] = None,
+    pool_connections: int = 100,
 ) -> BaseUrlSession:
     """Specify a root URL and authentication key for the CWMS Data API.
 
@@ -112,7 +117,10 @@ def init_session(
     if api_root:
         logging.debug(f"Initializing root URL: api_root={api_root}")
         SESSION = sessions.BaseUrlSession(base_url=api_root)
-
+        adapter = adapters.HTTPAdapter(
+            pool_connections=pool_connections, pool_maxsize=pool_connections
+        )
+        SESSION.mount("https://", adapter)
     if api_key:
         logging.debug(f"Setting authorization key: api_key={api_key}")
         SESSION.headers.update({"Authorization": api_key})
@@ -183,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}")
@@ -220,7 +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)
@@ -232,6 +241,46 @@ def get(
         return {}
 
 
+def get_with_paging(
+    selector: str,
+    endpoint: str,
+    params: RequestParams,
+    *,
+    api_version: int = API_VERSION,
+) -> JSON:
+    """Make a GET request to the CWMS Data API with paging.
+
+    Args:
+        endpoint: The CDA endpoint for the record(s).
+        selector: The json key that will be merged though each page call
+        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 deserialized JSON response data.
+
+    Raises:
+        ApiError: If an error response is return by the API.
+    """
+
+    first_pass = True
+    while (params["page"] is not None) or first_pass:
+        temp = get(endpoint, params, api_version=api_version)
+        if first_pass:
+            response = temp
+        else:
+            response[selector] = response[selector] + temp[selector]
+        if "next-page" in temp.keys():
+            params["page"] = temp["next-page"]
+        else:
+            params["page"] = None
+        first_pass = False
+    return response
+
+
 def post(
     endpoint: str,
     data: Any,
@@ -260,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}")
@@ -299,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)
@@ -330,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.4.4 → cwms_python-0.6.0}/cwms/catalog/catalog.py

@@ -1,7 +1,7 @@
 from typing import Optional
 
 import cwms.api as api
-from cwms.types import Data
+from cwms.cwms_types import Data
 
 
 def get_locations_catalog(

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.4.4/cwms/types.py → 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]
@@ -51,27 +51,48 @@ class Data:
             A data frame containing the data located
         """
 
-        data = deepcopy(json)
-
-        if selector:
+        def get_df_data(data: JSON, selector: str) -> JSON:
+            # get the data that will be stored in the dataframe using the selectors
             df_data = data
             for key in selector.split("."):
                 if key in df_data.keys():
                     df_data = df_data[key]
+            return df_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:
+            # if timeseries values are present then grab the values and put into
+            # dataframe else create empty dataframe
+            columns = Index([sub["name"] for sub in orig_json["value-columns"]])
+            if value_json:
+                df = DataFrame(value_json)
+                df.columns = columns
+            else:
+                df = DataFrame(columns=columns)
+
+            if "date-time" in df.columns:
+                df["date-time"] = to_datetime(df["date-time"], unit="ms", utc=True)
+            return df
+
+        data = deepcopy(json)
+
+        if selector:
+            df_data = get_df_data(data, selector)
 
             # if the dataframe is for a rating table
             if ("rating-points" in selector) and ("point" in df_data.keys()):
-                df = DataFrame(df_data["point"])
+                df = rating_type(df_data)
 
             elif selector == "values":
-                df = DataFrame(df_data)
-                # if timeseries values are present then grab the values and put into dataframe
-                df.columns = Index([sub["name"] for sub in data["value-columns"]])
+                df = timeseries_type(data, df_data)
 
-                if "date-time" in df.columns:
-                    df["date-time"] = to_datetime(df["date-time"], unit="ms", utc=True)
             else:
-                df = json_normalize(df_data)
+                df = json_normalize(df_data) if df_data else DataFrame()
         else:
             df = json_normalize(data)
 
@@ -81,7 +102,7 @@ class Data:
     def df(self) -> DataFrame:
         """Return the data frame."""
 
-        if type(self._df) != DataFrame:
+        if not isinstance(self._df, DataFrame):
             self._df = Data.to_df(self.json, self.selector)
 
         return self._df