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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cwms-python
-Version: 0.3.0
+Version: 0.4.4
 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(p_tsId='Some.Fully.Qualified.Ts.Id',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.3.0 → cwms_python-0.4.4}/README.md

@@ -28,7 +28,7 @@ from datetime import datetime, timedelta
 
 end = datetime.now()
 begin = end - timedelta(days = 10)
-data = cwms.get_timeseries(p_tsId='Some.Fully.Qualified.Ts.Id',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/__init__.py

@@ -0,0 +1,22 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .api import *
+from .catalog.catalog import *
+from .forecast.forecast_instance import *
+from .forecast.forecast_spec import *
+from .levels.location_levels import *
+from .levels.specified_levels import *
+from .locations.physical_locations import *
+from .ratings.ratings import *
+from .ratings.ratings_spec import *
+from .ratings.ratings_template import *
+from .standard_text.standard_text import *
+from .timeseries.timerseries_identifier import *
+from .timeseries.timeseries import *
+from .timeseries.timeseries_bin import *
+from .timeseries.timeseries_txt import *
+
+try:
+    __version__ = version("cwms-python")
+except PackageNotFoundError:
+    __version__ = "version-unknown"

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

@@ -29,7 +29,7 @@ the error.
 import json
 import logging
 from json import JSONDecodeError
-from typing import Optional, cast
+from typing import Any, Optional, cast
 
 from requests import Response
 from requests_toolbelt import sessions  # type: ignore
@@ -150,12 +150,51 @@ def api_version_text(api_version: int) -> str:
         version = "application/json"
     elif api_version == 2:
         version = "application/json;version=2"
+    elif api_version == 102:
+        version = "application/xml;version=2"
     else:
         raise InvalidVersion(f"API version {api_version} is not supported.")
 
     return version
 
 
+def get_xml(
+    endpoint: str,
+    params: Optional[RequestParams] = None,
+    *,
+    api_version: int = API_VERSION,
+) -> Any:
+    """Make a GET request to the CWMS Data API.
+
+    Args:
+        endpoint: The CDA endpoint for the record(s).
+        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.
+    """
+
+    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)
+
+    try:
+        return response.content.decode("utf-8")
+    except JSONDecodeError as error:
+        logging.error(f"Error decoding CDA response as xml: {error}")
+        return {}
+
+
 def get(
     endpoint: str,
     params: Optional[RequestParams] = None,
@@ -182,20 +221,20 @@ def get(
     headers = {"Accept": api_version_text(api_version)}
     response = SESSION.get(endpoint, params=params, headers=headers)
 
-    if response.status_code != 200:
+    if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
         raise ApiError(response)
 
     try:
         return cast(JSON, response.json())
     except JSONDecodeError as error:
-        logging.error(f"Error decoding CDA response: {error}")
+        logging.error(f"Error decoding CDA response as json: {error}")
         return {}
 
 
 def post(
     endpoint: str,
-    data: JSON,
+    data: Any,
     params: Optional[RequestParams] = None,
     *,
     api_version: int = API_VERSION,
@@ -221,18 +260,19 @@ def post(
     # post requires different headers than get for
     headers = {"accept": "*/*", "Content-Type": api_version_text(api_version)}
 
-    response = SESSION.post(
-        endpoint, params=params, headers=headers, data=json.dumps(data)
-    )
+    if isinstance(data, dict):
+        data = json.dumps(data)
+
+    response = SESSION.post(endpoint, params=params, headers=headers, data=data)
 
-    if response.status_code != 200:
+    if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
         raise ApiError(response)
 
 
 def patch(
     endpoint: str,
-    data: JSON,
+    data: Optional[Any] = None,
     params: Optional[RequestParams] = None,
     *,
     api_version: int = API_VERSION,
@@ -256,12 +296,14 @@ def patch(
     """
 
     headers = {"accept": "*/*", "Content-Type": api_version_text(api_version)}
+    if data is None:
+        response = SESSION.patch(endpoint, params=params, headers=headers)
+    else:
+        if isinstance(data, dict):
+            data = json.dumps(data)
+        response = SESSION.patch(endpoint, params=params, headers=headers, data=data)
 
-    response = SESSION.patch(
-        endpoint, params=params, headers=headers, data=json.dumps(data)
-    )
-
-    if response.status_code != 200:
+    if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
         raise ApiError(response)
 
@@ -289,6 +331,6 @@ def delete(
     headers = {"Accept": api_version_text(api_version)}
     response = SESSION.delete(endpoint, params=params, headers=headers)
 
-    if response.status_code != 200:
+    if response.status_code < 200 or response.status_code >= 300:
         logging.error(f"CDA Error: response={response}")
         raise ApiError(response)

cwms_python-0.4.4/cwms/catalog/catalog.py

@@ -0,0 +1,128 @@
+from typing import Optional
+
+import cwms.api as api
+from cwms.types import Data
+
+
+def get_locations_catalog(
+    office_id: str,
+    page: Optional[str] = None,
+    page_size: Optional[int] = 5000,
+    unit_system: Optional[str] = None,
+    like: Optional[str] = None,
+    location_category_like: Optional[str] = None,
+    location_group_like: Optional[str] = None,
+    bounding_office_like: Optional[str] = None,
+    location_kind_like: Optional[str] = None,
+) -> Data:
+    """Retrieves filters for a locations catalog
+
+    Parameters
+    ----------
+        page: string
+            The endpoint used to identify where the request is located.
+        page_size: integer
+            The entries per page returned. The default value is 5000.
+        unit_system: string
+            The unit system desired in response. Valid values for this
+            field are:
+                1. SI
+                2. EN
+        office_id: string
+            The owning office of the timeseries group.
+        like: string
+            The regex for matching against the id
+        location_category_like: string
+            The regex for matching against the location category id
+        location_group_like: string
+            The regex for matching against the location group id
+        bounding_office_like: string
+            The regex for matching against the location bounding office
+        location_kind_like: string
+            Posix regular expression matching against the location kind. The location-kind is typically unset or one of the following: {"SITE", "EMBANKMENT", "OVERFLOW", "TURBINE", "STREAM", "PROJECT", "STREAMGAGE", "BASIN", "OUTLET", "LOCK", "GATE"}. Multiple kinds can be matched by using Regular Expression OR clauses. For example: "(SITE|STREAM)"
+
+    Returns
+    -------
+        cwms data type
+    """
+
+    # CHECKS
+    if office_id is None:
+        raise ValueError("Retrieve locations catalog requires an office")
+
+    dataset = "LOCATIONS"
+    endpoint = f"catalog/{dataset}"
+    params = {
+        "page": page,
+        "page-size": page_size,
+        "units": unit_system,
+        "office": office_id,
+        "like": like,
+        "location-category-like": location_category_like,
+        "location-group-like": location_group_like,
+        "bounding-office-like": bounding_office_like,
+        "location-kind-like": location_kind_like,
+    }
+
+    response = api.get(endpoint=endpoint, params=params, api_version=2)
+    return Data(response, selector="entries")
+
+
+def get_timeseries_catalog(
+    office_id: str,
+    page: Optional[str] = None,
+    page_size: Optional[int] = 5000,
+    unit_system: Optional[str] = None,
+    like: Optional[str] = None,
+    timeseries_category_like: Optional[str] = None,
+    timeseries_group_like: Optional[str] = "DMZ Include List",
+    bounding_office_like: Optional[str] = None,
+) -> Data:
+    """Retrieves filters for the timeseries catalog
+
+    Parameters
+    ----------
+        page: string
+            The endpoint used to identify where the request is located.
+        page_size: integer
+            The entries per page returned. The default value is 500.
+        unit_system: string
+            The unit system desired in response. Valid values for this
+            field are:
+                1. SI
+                2. EN
+        office_id: string
+            The owning office of the timeseries group.
+        like: string
+            The regex for matching against the id
+        timeseries_category_like: string
+            The regex for matching against the category id
+        timeseries_group_like: string
+            The regex for matching against the timeseries group id. This will default to pull only public datasets
+        bounding_office_like: string
+            The regex for matching against the location bounding office
+
+    Returns
+    -------
+        cwms data type
+    """
+
+    # CHECKS
+    if office_id is None:
+        raise ValueError("Retrieve timeseries catalog requires an office")
+
+    dataset = "TIMESERIES"
+    endpoint = f"catalog/{dataset}"
+    params = {
+        "page": page,
+        "page-size": page_size,
+        "unit-system": unit_system,
+        "office": office_id,
+        "like": like,
+        "timeseries-category-like": timeseries_category_like,
+        "timeseries-group-like": timeseries_group_like,
+        "bounding-office-like": bounding_office_like,
+    }
+
+    response = api.get(endpoint=endpoint, params=params, api_version=2)
+    return Data(response, selector="entries")

cwms_python-0.4.4/cwms/forecast/forecast_instance.py

@@ -0,0 +1,208 @@
+#  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 datetime import datetime
+from typing import Optional
+
+import cwms.api as api
+from cwms.types import JSON, Data
+
+
+def get_forecast_instances(
+    spec_id: Optional[str] = None,
+    office: Optional[str] = None,
+    designator: Optional[str] = None,
+) -> Data:
+    """
+    Parameters
+    ----------
+    spec_id : str, optional
+        The forecast spec id.
+    office : str, optional
+        The spec office id.
+    designator : str, optional
+        The spec designator.
+
+    Returns
+    -------
+    response : dict
+        the JSON response from CWMS Data API.
+
+    Raises
+    ------
+    ValueError
+        If any of spec_id, office, or designator 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 spec_id is None:
+        raise ValueError("Retrieving forecast instances requires an id")
+    if office is None:
+        raise ValueError("Retrieving forecast instances requires an office")
+    if designator is None:
+        raise ValueError("Retrieving forecast instances requires a designator")
+    endpoint = "forecast-instance"
+
+    params = {
+        "office": office,
+        "name": spec_id,
+        "designator": designator,
+    }
+
+    response = api.get(endpoint, params)
+    return Data(response)
+
+
+def get_forecast_instance(
+    spec_id: str,
+    office: str,
+    designator: str,
+    forecast_date: datetime,
+    issue_date: datetime,
+) -> Data:
+    """
+    Parameters
+    ----------
+    spec_id : str
+        The ID of the forecast spec.
+    office : str
+        The ID of the office.
+    designator : str
+        The designator of the forecast spec
+
+    Returns
+    -------
+    response : dict
+        the JSON response from CWMS Data API.
+
+    Raises
+    ------
+    ValueError
+        If any of spec_id, office, or designator 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 spec_id is None:
+        raise ValueError("Retrieve forecast instance requires an id")
+    if office is None:
+        raise ValueError("Retrieve a forecast instance requires an office")
+    if designator is None:
+        raise ValueError("Retrieve a forecast instance requires a designator")
+    if forecast_date is None:
+        raise ValueError("Retrieve a forecast instance requires a forecast date")
+    if issue_date is None:
+        raise ValueError("Retrieve a forecast instance requires a issue date")
+
+    endpoint = f"forecast-instance/{spec_id}"
+
+    params = {
+        "office": office,
+        "designator": designator,
+        "forecast-date": forecast_date.isoformat(),
+        "issue-date": issue_date.isoformat(),
+    }
+
+    response = api.get(endpoint, params)
+    return Data(response)
+
+
+def store_forecast_instance(data: JSON) -> None:
+    """
+    This method is used to store a forecast instance through CWMS Data API.
+
+    Parameters
+    ----------
+    data : dict
+        A dictionary representing the JSON data to be stored.
+        If the `data` value is None, a `ValueError` will be raised.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If dict 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("Storing a forecast instance requires a JSON data dictionary")
+    endpoint = "forecast-instance"
+
+    return api.post(endpoint, data, params=None)
+
+
+def delete_forecast_instance(
+    spec_id: str,
+    office: str,
+    designator: str,
+    forecast_date: datetime,
+    issue_date: datetime,
+) -> None:
+    """
+    Parameters
+    ----------
+    spec_id : str
+        The ID of the forecast spec.
+    office : str
+        The ID of the office.
+    designator : str
+        The designator of the forecast spec
+    forecast_date : datetime
+        The forecast date of the forecast instance
+    issue_date : datetime
+        The forecast issue date of the forecast instance
+
+    Returns
+    -------
+    response : dict
+        the JSON response from CWMS Data API.
+
+    Raises
+    ------
+    ValueError
+        If any of spec_id, office, designator,
+        forecast_date, or issue_date 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 spec_id is None:
+        raise ValueError("Deleting a forecast instance requires an id")
+    if office is None:
+        raise ValueError("Deleting a forecast instance requires an office")
+    if designator is None:
+        raise ValueError("Deleting a forecast instance requires a designator")
+    if forecast_date is None:
+        raise ValueError("Deleting a forecast instance requires a forecast date")
+    if issue_date is None:
+        raise ValueError("Deleting a forecast instance requires a issue date")
+
+    endpoint = f"forecast-instance/{spec_id}"
+
+    params = {
+        "office": office,
+        "designator": designator,
+        "forecast-date": forecast_date.isoformat(),
+        "issue-date": issue_date.isoformat(),
+    }
+    return api.delete(endpoint, params)

cwms_python-0.4.4/cwms/forecast/forecast_spec.py

@@ -0,0 +1,181 @@
+#  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.types import JSON, Data, DeleteMethod
+
+
+def get_forecast_specs(
+    id_mask: Optional[str] = None,
+    office: Optional[str] = None,
+    designator_mask: Optional[str] = None,
+    source_entity: Optional[str] = None,
+) -> Data:
+    """
+    Parameters
+    ----------
+    id_mask : str, optional
+        The regex filter for the forecast spec id.
+    office : str, optional
+        The regex filter for the forecast spec id.
+    designator_mask : str, optional
+        The regex filter for the forecast spec id.
+    source_entity : str, optional
+        The regex filter for the forecast spec id.
+
+    Returns
+    -------
+    response : dict
+        the JSON response from CWMS Data API.
+
+    Raises
+    ------
+    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.
+    """
+    endpoint = "forecast-spec"
+
+    params = {
+        "office": office,
+        "id_mask": id_mask,
+        "designator-mask": designator_mask,
+        "source-entity": source_entity,
+    }
+
+    response = api.get(endpoint, params)
+    return Data(response)
+
+
+def get_forecast_spec(spec_id: str, office: str, designator: str) -> Data:
+    """
+    Parameters
+    ----------
+    spec_id : str
+        The ID of the forecast spec.
+    office : str
+        The ID of the office.
+    designator : str
+        The designator of the forecast spec
+
+    Returns
+    -------
+    response : dict
+        the JSON response from CWMS Data API.
+
+    Raises
+    ------
+    ValueError
+        If any of spec_id, office, or designator 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 spec_id is None:
+        raise ValueError("Retrieve forecast spec requires an id")
+    if office is None:
+        raise ValueError("Retrieve a forecast spec requires an office")
+    if designator is None:
+        raise ValueError("Retrieve a forecast spec requires a designator")
+
+    endpoint = f"forecast-spec/{spec_id}"
+
+    params = {
+        "office": office,
+        "designator": designator,
+    }
+
+    response = api.get(endpoint, params)
+    return Data(response)
+
+
+def store_forecast_spec(data: JSON) -> None:
+    """
+    This method is used to store a forecast spec through CWMS Data API.
+
+    Parameters
+    ----------
+    data : dict
+        A dictionary representing the JSON data to be stored.
+        If the `data` value is None, a `ValueError` will be raised.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If dict 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("Storing a forecast spec requires a JSON data dictionary")
+    endpoint = "forecast-spec"
+
+    return api.post(endpoint, data)
+
+
+def delete_forecast_spec(
+    spec_id: str,
+    office: str,
+    designator: str,
+    delete_method: DeleteMethod,
+) -> None:
+    """
+    Parameters
+    ----------
+    spec_id : str
+        The ID of the forecast spec.
+    office : str
+        The ID of the office.
+    designator : str
+        The designator of the forecast spec
+    delete_method: DeleteMethod
+        The method to use to delete forecast spec data
+
+    Returns
+    -------
+    response : dict
+        the JSON response from CWMS Data API.
+
+    Raises
+    ------
+    ValueError
+        If any of spec_id, office, or designator 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 spec_id is None:
+        raise ValueError("Deleting a forecast spec requires an id")
+    if office is None:
+        raise ValueError("Deleting a forecast spec requires an office")
+    if designator is None:
+        raise ValueError("Deleting a forecast spec requires a designator")
+
+    endpoint = f"forecast-spec/{spec_id}"
+    params = {
+        "office": office,
+        "designator": designator,
+        "method": delete_method.name,
+    }
+    return api.delete(endpoint, params)