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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cwms-python
-Version: 0.4.4
+Version: 0.5.0
 Summary: Corps water managerment systems (CWMS) REST API for Data Retrieval of USACE water data
 License: LICENSE
 Keywords: USACE,water data
@@ -49,7 +49,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

{cwms_python-0.4.4 → cwms_python-0.5.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

cwms_python-0.5.0/cwms/__init__.py

@@ -0,0 +1,27 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from cwms.api import *
+from cwms.catalog.catalog 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.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.timerseries_identifier import *
+from cwms.timeseries.timeseries import *
+from cwms.timeseries.timeseries_bin import *
+from cwms.timeseries.timeseries_txt import *
+
+try:
+    __version__ = version("cwms-python")
+except PackageNotFoundError:
+    __version__ = "version-unknown"

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

@@ -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})
@@ -220,7 +228,6 @@ def get(
 
     headers = {"Accept": api_version_text(api_version)}
     response = SESSION.get(endpoint, params=params, headers=headers)
-
     if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
         raise ApiError(response)
@@ -232,6 +239,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,

{cwms_python-0.4.4 → cwms_python-0.5.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.4.4/cwms/types.py → cwms_python-0.5.0/cwms/cwms_types.py

@@ -51,27 +51,47 @@ 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()
+            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 +101,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

{cwms_python-0.4.4 → cwms_python-0.5.0}/cwms/forecast/forecast_instance.py

@@ -6,7 +6,7 @@ from datetime import datetime
 from typing import Optional
 
 import cwms.api as api
-from cwms.types import JSON, Data
+from cwms.cwms_types import JSON, Data
 
 
 def get_forecast_instances(

{cwms_python-0.4.4 → cwms_python-0.5.0}/cwms/forecast/forecast_spec.py

@@ -5,7 +5,7 @@
 from typing import Optional
 
 import cwms.api as api
-from cwms.types import JSON, Data, DeleteMethod
+from cwms.cwms_types import JSON, Data, DeleteMethod
 
 
 def get_forecast_specs(

{cwms_python-0.4.4 → cwms_python-0.5.0}/cwms/levels/location_levels.py

@@ -9,7 +9,7 @@ from typing import Optional
 import pandas as pd
 
 import cwms.api as api
-from cwms.types import JSON, Data
+from cwms.cwms_types import JSON, Data
 
 
 def get_location_levels(
@@ -218,4 +218,4 @@ def get_level_as_timeseries(
         "unit": unit,
     }
     response = api.get(endpoint, params)
-    return Data(response)
+    return Data(response, selector="values")

{cwms_python-0.4.4 → cwms_python-0.5.0}/cwms/levels/specified_levels.py

@@ -5,7 +5,7 @@
 from typing import Optional
 
 import cwms.api as api
-from cwms.types import JSON, Data
+from cwms.cwms_types import JSON, Data
 
 
 def get_specified_levels(

{cwms_python-0.4.4 → cwms_python-0.5.0}/cwms/locations/physical_locations.py

@@ -4,7 +4,7 @@ import pandas as pd
 from pandas import DataFrame
 
 import cwms.api as api
-from cwms.types import JSON, Data
+from cwms.cwms_types import JSON, Data
 
 
 def get_location_group(loc_group_id: str, category_id: str, office_id: str) -> Data:
@@ -46,20 +46,44 @@ def get_location(location_id: str, office_id: str, unit: str = "EN") -> Data:
 
 def get_locations(
     office_id: Optional[str] = None,
-    loc_ids: Optional[str] = None,
-    units: Optional[str] = None,
+    location_ids: Optional[str] = None,
+    units: Optional[str] = "EN",
     datum: Optional[str] = None,
 ) -> Data:
+    """
+    Get location data for a single location
+
+    Parameters
+    ----------
+        location_id: str
+            Specifies the name(s) of the location(s) whose data is to be included in the response. This parameter is a Posix regular expression matching against the id
+        office_id : str
+            The ID of the office that the locations belongs to.
+        unit: string, optional, default is EN
+            The unit or unit system of the response. Defaults to EN. Valid values
+            for the unit field are:
+                1. EN. English unit system.
+                2. SI. SI unit system.
+                3. Other.
+        Datum: string, optional, default is None
+            Specifies the elevation datum of the response. This field affects only vertical datum. Valid values for this field are:
+                1.) NAVD88 The elevation values will in the specified or default units above the NAVD-88 datum.
+                2.) NGVD29 The elevation values will be in the specified or default units above the NGVD-29 datum.
+    Returns
+    -------
+        cwms data type.  data.json will return the JSON output and data.df will return a dataframe
+
+    """
     endpoint = "locations"
     params = {
         "office": office_id,
-        "names": loc_ids,
+        "names": location_ids,
         "units": units,
         "datum": datum,
     }
 
     response = api.get(endpoint, params)
-    return Data(response, selector="locations.locations")
+    return Data(response)
 
 
 def ExpandLocations(df: DataFrame) -> DataFrame:

cwms_python-0.5.0/cwms/outlets/outlets.py

@@ -0,0 +1,195 @@
+#  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
+from typing import Optional
+
+import cwms.api as api
+from cwms.cwms_types import JSON, Data, DeleteMethod
+
+
+def get_outlet(office_id: str, name: str) -> Data:
+    """
+    Parameters
+    ----------
+    name : str
+        The ID of the outlet.
+    office_id : str
+        The ID of the office.
+
+    Returns
+    -------
+    response : dict
+        the JSON response from CWMS Data API.
+
+    Raises
+    ------
+    ValueError
+        If any of name or office_id is None.
+    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 name is None:
+        raise ValueError("Retrieve outlet requires a name")
+    if office_id is None:
+        raise ValueError("Retrieve outlet requires an office")
+
+    endpoint = f"projects/outlets/{name}"
+    params = {"office": office_id}
+    response = api.get(endpoint, params)
+    return Data(response)
+
+
+def get_outlets(office_id: str, project_id: str) -> Data:
+    """
+    Parameters
+    ----------
+    project_id : str
+        The project ID of the outlets.
+    office_id : str
+        The ID of the project's office.
+
+    Returns
+    -------
+    response : dict
+        the JSON response from CWMS Data API.
+
+    Raises
+    ------
+    ValueError
+        If any of project_id or office_id is None.
+    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 project_id is None:
+        raise ValueError("Retrieve outlets requires a project id")
+    if office_id is None:
+        raise ValueError("Retrieve outlets requires an office")
+
+    endpoint = "projects/outlets"
+    params = {"office": office_id, "project-id": project_id}
+    response = api.get(endpoint, params)
+    return Data(response)
+
+
+def delete_outlet(office_id: str, name: str, delete_method: DeleteMethod) -> None:
+    """
+    Parameters
+    ----------
+    name : str
+        The name of the outlets.
+    office_id : str
+        The ID of the project's office.
+    delete_method: DeleteMethod
+        The method to use to delete the outlet.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If any of name, delete_method, or office_id is None.
+    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 name is None:
+        raise ValueError("Delete outlet requires an outlet name")
+    if office_id is None:
+        raise ValueError("Delete outlet requires an office")
+    if delete_method is None:
+        raise ValueError("Delete outlet requires a delete method")
+
+    endpoint = f"projects/outlets/{name}"
+    params = {"office": office_id, "method": delete_method.name}
+    api.delete(endpoint, params)
+
+
+def rename_outlet(office_id: str, old_name: str, new_name: str) -> None:
+    """
+    Parameters
+    ----------
+    old_name : str
+        The name of the outlet to rename.
+    new_name : str
+        The new name of the outlet.
+    office_id : str
+        The ID of the project's office.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If any of old_outlet_name, new_outlet_name,  or office_id is None.
+    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 old_name is None:
+        raise ValueError("Rename outlet requires the original outlet name")
+    if new_name is None:
+        raise ValueError("Rename outlet requires a new outlet name")
+    if office_id is None:
+        raise ValueError("Rename outlet requires an office")
+
+    endpoint = f"projects/outlets/{old_name}"
+    params = {"office": office_id, "name": new_name}
+    api.patch(endpoint=endpoint, params=params)
+
+
+def store_outlet(data: JSON, fail_if_exists: Optional[bool] = True) -> None:
+    """
+    Parameters
+    ----------
+    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 : str, optional
+        A boolean value indicating whether to fail if the outlet already exists.
+        Default is True.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If any of data is None.
+    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 data is None:
+        raise ValueError("Cannot store an outlet without a JSON data dictionary")
+
+    endpoint = "projects/outlets"
+    params = {"fail-if-exists": fail_if_exists}
+    api.post(endpoint, data, params)