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

cwms_python-0.4.4/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.4.4/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.1
+Name: cwms-python
+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
+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(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
+
+#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.4.4/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(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
+
+#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.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.4.4/cwms/api.py

@@ -0,0 +1,336 @@
+""" 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 Any, 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"
+    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,
+    *,
+    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 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 as json: {error}")
+        return {}
+
+
+def post(
+    endpoint: str,
+    data: Any,
+    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)}
+
+    if isinstance(data, dict):
+        data = json.dumps(data)
+
+    response = SESSION.post(endpoint, params=params, headers=headers, data=data)
+
+    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: Optional[Any] = None,
+    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)}
+    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)
+
+    if response.status_code < 200 or response.status_code >= 300:
+        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 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")