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

cwms_python-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hydrologic Engineering Center
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cwms_python-0.3.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.1
+Name: cwms-python
+Version: 0.3.0
+Summary: Corps water managerment systems (CWMS) REST API for Data Retrieval of USACE water data
+License: LICENSE
+Keywords: USACE,water data
+Author: Eric Novotny
+Author-email: eric.v.novotny@usace.army.mil
+Requires-Python: >=3.9,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+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)
+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)
+Description-Content-Type: text/markdown
+
+# CWMSpy
+
+CWMS REST API for Data Retrieval
+
+## Requirements.
+
+Python 3.9+
+
+## Installation & Usage
+
+### pip install
+
+```sh
+pip install cwms-python
+```
+
+Then import the package:
+
+```python
+import cwms
+```
+
+## Getting Started
+
+```python
+import cwms
+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)
+
+#a cwms data object will be provided this object containes both the JSON as well
+#as the values converted into a dataframe
+
+#display the dataframe
+
+df = data.df
+print(df)
+```
+
+```
+     date-time 	value 	quality-code
+0 	2024-04-23 08:15:00 	86.57 	3
+1 	2024-04-23 08:30:00 	86.57 	3
+2 	2024-04-23 08:45:00 	86.58 	3
+3 	2024-04-23 09:00:00 	86.58 	3
+4 	2024-04-23 09:15:00 	86.58 	3
+5 	2024-04-23 09:30:00 	86.58 	3
+6 	2024-04-23 09:45:00 	86.59 	3
+7 	2024-04-23 10:00:00 	86.58 	3
+```
+
+```python
+#display JSON
+json = data.JSON
+print(json)
+```
+
+```
+{'name': 'Some.Fully.Qualified.Ts.Id',
+ 'office-id': 'MVP',
+ 'units': 'ft',
+ 'values': [['2024-04-23T08:15:00', 86.57, 3],
+  ['2024-04-23T08:30:00', 86.57, 3],
+  ['2024-04-23T08:45:00', 86.57999999999997, 3],
+  ['2024-04-23T09:00:00', 86.57999999999997, 3],
+  ['2024-04-23T09:15:00', 86.57999999999997, 3],
+  ['2024-04-23T09:30:00', 86.57999999999997, 3],
+  ['2024-04-23T09:45:00', 86.59, 3],
+  ['2024-04-23T10:00:00', 86.57999999999997, 3]],
+ 'version-date': None}
+```
+

cwms_python-0.3.0/README.md

@@ -0,0 +1,73 @@
+# CWMSpy
+
+CWMS REST API for Data Retrieval
+
+## Requirements.
+
+Python 3.9+
+
+## Installation & Usage
+
+### pip install
+
+```sh
+pip install cwms-python
+```
+
+Then import the package:
+
+```python
+import cwms
+```
+
+## Getting Started
+
+```python
+import cwms
+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)
+
+#a cwms data object will be provided this object containes both the JSON as well
+#as the values converted into a dataframe
+
+#display the dataframe
+
+df = data.df
+print(df)
+```
+
+```
+     date-time 	value 	quality-code
+0 	2024-04-23 08:15:00 	86.57 	3
+1 	2024-04-23 08:30:00 	86.57 	3
+2 	2024-04-23 08:45:00 	86.58 	3
+3 	2024-04-23 09:00:00 	86.58 	3
+4 	2024-04-23 09:15:00 	86.58 	3
+5 	2024-04-23 09:30:00 	86.58 	3
+6 	2024-04-23 09:45:00 	86.59 	3
+7 	2024-04-23 10:00:00 	86.58 	3
+```
+
+```python
+#display JSON
+json = data.JSON
+print(json)
+```
+
+```
+{'name': 'Some.Fully.Qualified.Ts.Id',
+ 'office-id': 'MVP',
+ 'units': 'ft',
+ 'values': [['2024-04-23T08:15:00', 86.57, 3],
+  ['2024-04-23T08:30:00', 86.57, 3],
+  ['2024-04-23T08:45:00', 86.57999999999997, 3],
+  ['2024-04-23T09:00:00', 86.57999999999997, 3],
+  ['2024-04-23T09:15:00', 86.57999999999997, 3],
+  ['2024-04-23T09:30:00', 86.57999999999997, 3],
+  ['2024-04-23T09:45:00', 86.59, 3],
+  ['2024-04-23T10:00:00', 86.57999999999997, 3]],
+ 'version-date': None}
+```

cwms_python-0.3.0/cwms/__init__.py

@@ -0,0 +1,13 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .api import *
+
+# from .core import CwmsApiSession
+from .levels.location_levels import *
+from .locations.physical_locations import *
+from .timeseries.timeseries import *
+
+try:
+    __version__ = version("cwms-python")
+except PackageNotFoundError:
+    __version__ = "version-unknown"

cwms_python-0.3.0/cwms/_constants.py

@@ -0,0 +1,33 @@
+#  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
+
+
+HEADER_JSON_V1 = "application/json"
+HEADER_JSON_V2 = "application/json;version=2"
+
+OFFICE_PARAM = "office"
+TEMPLATE_ID_MASK_PARAM = "template-id-mask"
+FAIL_IF_EXISTS = "fail-if-exists"
+UNIT = "unit"
+DATUM = "datum"
+BEGIN = "begin"
+END = "end"
+PAGE_SIZE = "page-size"
+PAGE = "page"
+NAME = "name"
+TIMEZONE = "timezone"
+EFFECTIVE_DATE = "effective-date"
+CASCADE_DELETE = "cascade-delete"
+BINARY_TYPE_MASK = "binary-type-mask"
+REPLACE_ALL = "replace-all"
+VERSION_DATE = "version-date"
+DESIGNATOR = "designator"
+FORECAST_DATE = "forecast-date"
+ISSUE_DATE = "issue-date"
+ID_MASK = "id_mask"
+DESIGNATOR_MASK = "designator-mask"
+LOCATION_MASK = "location-mask"
+SOURCE_ENTITY = "source-entity"
+METHOD = "method"

cwms_python-0.3.0/cwms/api.py

@@ -0,0 +1,294 @@
+""" 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
+interact with these directly.
+
+The `init_session()` function can be used to specify an alternative root URL, and to
+provide an authentication key (if required). If `init_session()` is not called, the
+default root URL (see `API_ROOT` below) will be used, and no authentication keys will be
+included when making API calls.
+
+Example: Initializing a session
+
+    # Specify an alternate URL
+    init_session(api_root="https://example.com/cwms-data")
+
+    # Specify an alternate URL and an auth key
+    init_session(api_root="https://example.com/cwms-data", api_key="API_KEY")
+
+Functions which make API calls that _may_ return a JSON response will return a `dict`
+containing the deserialized data. If the API response does not include data, an empty
+`dict` will be returned.
+
+In the event the API returns an error response, the function will raise an `APIError`
+which includes the response object and provides some hints to the user on how to address
+the error.
+"""
+
+import json
+import logging
+from json import JSONDecodeError
+from typing import Optional, cast
+
+from requests import Response
+from requests_toolbelt import sessions  # type: ignore
+from requests_toolbelt.sessions import BaseUrlSession  # type: ignore
+
+from 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.
+SESSION = sessions.BaseUrlSession(base_url=API_ROOT)
+
+
+class InvalidVersion(Exception):
+    pass
+
+
+class ApiError(Exception):
+    """CWMS Data Api Error.
+
+    This class is a light wrapper around a `requests.Response` object. Its primary purpose
+    is to generate an error message that includes the request URL and provide additional
+    information to the user to help them resolve the error.
+    """
+
+    def __init__(self, response: Response):
+        self.response = response
+
+    def __str__(self) -> str:
+        # Include the request URL in the error message.
+        message = f"CWMS API Error ({self.response.url})"
+
+        # If a reason is provided in the response, add it to the message.
+        if reason := self.response.reason:
+            message += f" {reason}"
+
+        message += "."
+
+        # Add additional context to help the user resolve the issue.
+        if hint := self.hint():
+            message += f" {hint}"
+
+        if content := self.response.content:
+            message += f" {content.decode('utf8')}"
+
+        return message
+
+    def hint(self) -> str:
+        """Return a message with additional information on how to resolve the error."""
+
+        if self.response.status_code == 400:
+            return "Check that your parameters are correct."
+        elif self.response.status_code == 404:
+            return "May be the result of an empty query."
+        else:
+            return ""
+
+
+def init_session(
+    *, api_root: Optional[str] = None, api_key: Optional[str] = None
+) -> BaseUrlSession:
+    """Specify a root URL and authentication key for the CWMS Data API.
+
+    This function can be used to change the root URL used when interacting with the CDA.
+    All API calls made after this function is called will use the specified URL. If an
+    authentication key is given it will be included in all future request headers.
+
+    Keyword Args:
+        api_root (optional): The root URL for the CWMS Data API.
+        api_key (optional): An authentication key.
+
+    Returns:
+        Returns the updated session object.
+    """
+
+    global SESSION
+
+    if api_root:
+        logging.debug(f"Initializing root URL: api_root={api_root}")
+        SESSION = sessions.BaseUrlSession(base_url=api_root)
+
+    if api_key:
+        logging.debug(f"Setting authorization key: api_key={api_key}")
+        SESSION.headers.update({"Authorization": api_key})
+
+    return SESSION
+
+
+def return_base_url() -> str:
+    """returns the base URL for the CDA instance that is connected to.
+
+    Returns:
+        str: base URL
+    """
+
+    return str(SESSION.base_url)
+
+
+def api_version_text(api_version: int) -> str:
+    """Initialize CDA request headers.
+
+    The CDA supports multiple versions. To request a specific version, the version number
+    must be included in the request headers.
+
+    Args:
+        api_version: The CDA version to use for the request.
+
+    Returns:
+        A dict containing the request headers.
+
+    Raises:
+        InvalidVersion: If an unsupported API version is specified.
+    """
+
+    if api_version == 1:
+        version = "application/json"
+    elif api_version == 2:
+        version = "application/json;version=2"
+    else:
+        raise InvalidVersion(f"API version {api_version} is not supported.")
+
+    return version
+
+
+def get(
+    endpoint: str,
+    params: Optional[RequestParams] = None,
+    *,
+    api_version: int = API_VERSION,
+) -> JSON:
+    """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:
+        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}")
+        return {}
+
+
+def post(
+    endpoint: str,
+    data: JSON,
+    params: Optional[RequestParams] = None,
+    *,
+    api_version: int = API_VERSION,
+) -> None:
+    """Make a POST request to the CWMS Data API.
+
+    Args:
+        endpoint: The CDA endpoint for the record type.
+        data: A dict containing the new record data. Must be JSON-serializable.
+        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.
+    """
+
+    # 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 response.status_code != 200:
+        logging.error(f"CDA Error: response={response}")
+        raise ApiError(response)
+
+
+def patch(
+    endpoint: str,
+    data: JSON,
+    params: Optional[RequestParams] = None,
+    *,
+    api_version: int = API_VERSION,
+) -> None:
+    """Make a PATCH request to the CWMS Data API.
+
+    Args:
+        endpoint: The CDA endpoint for the record.
+        data: A dict containing the updated record data. Must be JSON-serializable.
+        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": "*/*", "Content-Type": api_version_text(api_version)}
+
+    response = SESSION.patch(
+        endpoint, params=params, headers=headers, data=json.dumps(data)
+    )
+
+    if response.status_code != 200:
+        logging.error(f"CDA Error: response={response}")
+        raise ApiError(response)
+
+
+def delete(
+    endpoint: str,
+    params: Optional[RequestParams] = None,
+    *,
+    api_version: int = API_VERSION,
+) -> None:
+    """Make a DELETE request to the CWMS Data API.
+
+    Args:
+        endpoint: The CDA endpoint for the record.
+        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.
+
+    Raises:
+        ApiError: If an error response is return by the API.
+    """
+
+    headers = {"Accept": api_version_text(api_version)}
+    response = SESSION.delete(endpoint, params=params, headers=headers)
+
+    if response.status_code != 200:
+        logging.error(f"CDA Error: response={response}")
+        raise ApiError(response)

cwms_python-0.3.0/cwms/core.py

@@ -0,0 +1,26 @@
+from typing import Optional
+
+from requests_toolbelt import sessions  # type: ignore
+from requests_toolbelt.sessions import BaseUrlSession  # type: ignore
+
+
+class CwmsApiSession:
+    def __init__(self, api_root: str, api_key: Optional[str] = None):
+        if api_root is None:
+            raise ValueError("CWMS API root URL cannot be None")
+        self.__session = sessions.BaseUrlSession(base_url=api_root)
+        if api_key is not None:
+            self.__session.headers.update({"Authorization": api_key})
+
+    def get_session(self) -> BaseUrlSession:
+        return self.__session
+
+
+class _CwmsBase:
+    def __init__(self, cwms_api_session: CwmsApiSession):
+        if cwms_api_session is None:
+            raise ValueError("CWMS API session information cannot be None")
+        self._cwms_api_session = cwms_api_session
+
+    def get_session(self) -> BaseUrlSession:
+        return self._cwms_api_session.get_session()

cwms_python-0.3.0/cwms/exceptions.py

@@ -0,0 +1,131 @@
+#  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 requests.exceptions import HTTPError
+from requests.models import Response
+
+
+class CwmsDataApiError(HTTPError):
+    """
+    Class representing an error thrown by the CwmsDataApi.
+
+    This class inherits from the requests.exceptions HTTPError class.
+
+    Attributes
+    ----------
+    incident_identifier : str
+        The incident identifier extracted from the response object.
+    response : Response
+        The response from the server
+    request : Request
+        The request made to the server
+    """
+
+    def __init__(self, message: str, response: Response):
+        """
+        Parameters
+        ----------
+        message : str
+            The message to be passed to the parent class constructor.
+        response : Response
+            The response object containing information about the incident identifier.
+
+        """
+        if response.text:
+            self.incident_identifier = response.json().get("incidentIdentifier")
+        super().__init__(message, response=response)
+
+
+class ClientError(CwmsDataApiError):
+    """
+    ClientError
+        Exception class representing the error when an error code in the 400 range is returned for a request.
+
+    Attributes
+    ----------
+    incident_identifier : str
+        The incident identifier extracted from the response object.
+    response : Response
+        The response from the server
+    request : Request
+        The request made to the server
+    """
+
+    def __init__(self, response: Response):
+        """
+        Parameters
+        ----------
+        response : Response
+            The response object that triggered the error.
+        """
+        message = (
+            f"CWMS Client error occurred for request:\n{response.request.url}\n"
+            f"Response was:\n{response.text}"
+        )
+        super().__init__(message, response=response)
+
+
+class ServerError(CwmsDataApiError):
+    """
+    ServerError
+        Exception class representing the error when an error code in the 500 range is returned for a request.
+
+    Attributes
+    ----------
+    incident_identifier : str
+        The incident identifier extracted from the response object.
+    response : Response
+        The response from the server
+    request : Request
+        The request made to the server
+    """
+
+    def __init__(self, response: Response):
+        """
+        Constructs a ServerError instance.
+
+        Parameters
+        ----------
+        response : Response
+            The response object from the CWMS server.
+
+        """
+        message = (
+            f"CWMS Server error occurred for request:\n{response.request.url}\n"
+            f"Response was:\n{response.text}"
+        )
+        super().__init__(message, response=response)
+
+
+class NoDataFoundError(CwmsDataApiError):
+    """
+    NoDataFoundError
+        Exception class representing the error when no data is found for a request and an error code 404 is returned.
+
+    Attributes
+    ----------
+    incident_identifier : str
+        The incident identifier extracted from the response object.
+    response : Response
+        The response from the server
+    request : Request
+        The request made to the server
+    """
+
+    def __init__(self, response: Response):
+        """
+        Constructs a NoDataFoundError instance.
+
+        Parameters
+        ----------
+        response : Response
+            The response object from the CWMS server.
+
+        """
+        message = (
+            f"No data found for request:\n{response.request.url}\n"
+            f"Response was:\n{response.text}"
+        )
+        super().__init__(message, response=response)