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

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

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: cwms-python
-Version: 0.5.0
-Summary: Corps water managerment systems (CWMS) REST API for Data Retrieval of USACE water data
+Version: 0.7.0
+Summary: Corps water management 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
@@ -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.5.0 → cwms_python-0.7.0}/README.md

@@ -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.5.0 → cwms_python-0.7.0}/cwms/__init__.py

@@ -1,12 +1,17 @@
 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.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.measurements.measurements import *
 from cwms.outlets.outlets import *
 from cwms.outlets.virtual_outlets import *
 from cwms.projects.project_lock_rights import *
@@ -16,10 +21,15 @@ 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_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")

{cwms_python-0.5.0 → cwms_python-0.7.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
@@ -26,6 +26,7 @@ which includes the response object and provides some hints to the user on how to
 the error.
 """
 
+import base64
 import json
 import logging
 from json import JSONDecodeError
@@ -34,6 +35,7 @@ from typing import Any, Optional, cast
 from requests import Response, adapters
 from requests_toolbelt import sessions  # type: ignore
 from requests_toolbelt.sessions import BaseUrlSession  # type: ignore
+from urllib3.util.retry import Retry
 
 from cwms.cwms_types import JSON, RequestParams
 
@@ -42,8 +44,24 @@ API_ROOT = "https://cwms-data.usace.army.mil/cwms-data/"
 API_VERSION = 2
 
 # Initialize a non-authenticated session with the default root URL and set default pool connections.
+
+retry_strategy = Retry(
+    total=6,
+    backoff_factor=0.5,
+    status_forcelist=[
+        403,
+        429,
+        500,
+        502,
+        503,
+        504,
+    ],  # Example: also retry on these HTTP status codes
+    allowed_methods=["GET", "PUT", "POST", "PATCH", "DELETE"],  # Methods to retry
+)
 SESSION = sessions.BaseUrlSession(base_url=API_ROOT)
-adapter = adapters.HTTPAdapter(pool_connections=100, pool_maxsize=100)
+adapter = adapters.HTTPAdapter(
+    pool_connections=100, pool_maxsize=100, max_retries=retry_strategy
+)
 SESSION.mount("https://", adapter)
 
 
@@ -118,7 +136,9 @@ def init_session(
         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
+            pool_connections=pool_connections,
+            pool_maxsize=pool_connections,
+            max_retries=retry_strategy,
         )
         SESSION.mount("https://", adapter)
     if api_key:
@@ -188,19 +208,8 @@ def get_xml(
     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 {}
+    # Wrap the primary get for backwards compatibility
+    return get(endpoint=endpoint, params=params, api_version=api_version)
 
 
 def get(
@@ -208,7 +217,7 @@ def get(
     params: Optional[RequestParams] = None,
     *,
     api_version: int = API_VERSION,
-) -> JSON:
+) -> Any:
     """Make a GET request to the CWMS Data API.
 
     Args:
@@ -227,16 +236,28 @@ 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)
-
-    try:
-        return cast(JSON, response.json())
-    except JSONDecodeError as error:
-        logging.error(f"Error decoding CDA response as json: {error}")
-        return {}
+    with SESSION.get(endpoint, params=params, headers=headers) as response:
+        if not response.ok:
+            logging.error(f"CDA Error: response={response}")
+            raise ApiError(response)
+        try:
+            # Avoid case sensitivity issues with the content type header
+            content_type = response.headers.get("Content-Type", "").lower()
+            # Most CDA content is JSON
+            if "application/json" in content_type or not content_type:
+                return cast(JSON, response.json())
+            # Use automatic charset detection with .text
+            if "text/plain" in content_type or "text/" in content_type:
+                return response.text
+            if content_type.startswith("image/"):
+                return base64.b64encode(response.content).decode("utf-8")
+            # Fallback for remaining content types
+            return response.content.decode("utf-8")
+        except JSONDecodeError as error:
+            logging.error(
+                f"Error decoding CDA response as JSON: {error} on line {error.lineno}\n\tFalling back to text"
+            )
+            return response.text
 
 
 def get_with_paging(
@@ -245,7 +266,7 @@ def get_with_paging(
     params: RequestParams,
     *,
     api_version: int = API_VERSION,
-) -> JSON:
+) -> Any:
     """Make a GET request to the CWMS Data API with paging.
 
     Args:
@@ -307,14 +328,13 @@ 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)
-
-    if response.status_code < 200 or response.status_code >= 300:
-        logging.error(f"CDA Error: response={response}")
-        raise ApiError(response)
+    with SESSION.post(endpoint, params=params, headers=headers, data=data) as response:
+        if not response.ok:
+            logging.error(f"CDA Error: response={response}")
+            raise ApiError(response)
 
 
 def patch(
@@ -343,16 +363,13 @@ 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)
 
-    if response.status_code < 200 or response.status_code >= 300:
-        logging.error(f"CDA Error: response={response}")
-        raise ApiError(response)
+    if data and isinstance(data, dict) or isinstance(data, list):
+        data = json.dumps(data)
+    with SESSION.patch(endpoint, params=params, headers=headers, data=data) as response:
+        if not response.ok:
+            logging.error(f"CDA Error: response={response}")
+            raise ApiError(response)
 
 
 def delete(
@@ -376,8 +393,7 @@ def delete(
     """
 
     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)
+    with SESSION.delete(endpoint, params=params, headers=headers) as response:
+        if not response.ok:
+            logging.error(f"CDA Error: response={response}")
+            raise ApiError(response)

cwms_python-0.7.0/cwms/catalog/blobs.py

@@ -0,0 +1,99 @@
+import base64
+from typing import Optional
+
+import cwms.api as api
+from cwms.cwms_types import JSON, Data
+from cwms.utils.checks import is_base64
+
+STORE_DICT = """data = {
+    "office-id": "SWT",
+    "id": "MYFILE_OR_BLOB_ID.TXT",
+    "description": "Your description here",
+    "media-type-id": "application/octet-stream",
+    "value": "STRING of content or BASE64_ENCODED_STRING"
+}
+"""
+
+
+def get_blob(blob_id: str, office_id: str) -> str:
+    """Get a single BLOB (Binary Large Object).
+
+    Parameters
+        ----------
+            blob_id: string
+                Specifies the id of the blob. ALL blob ids are UPPERCASE.
+            office_id: string
+                Specifies the office of the blob.
+
+
+        Returns
+        -------
+            str: the value returned based on the content-type it was stored with as a string
+    """
+
+    endpoint = f"blobs/{blob_id}"
+    params = {"office": office_id}
+    response = api.get(endpoint, params, api_version=1)
+    return str(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=2)
+    return Data(response, selector="blobs")
+
+
+def store_blobs(data: JSON, fail_if_exists: Optional[bool] = True) -> None:
+    f"""Create New Blob
+
+    Parameters
+    ----------
+        **Note**: The "id" field is automatically cast to uppercase.
+
+        Data: JSON dictionary
+            JSON containing information of Blob to be updated.
+
+            {STORE_DICT}
+        fail_if_exists: Boolean
+            Create will fail if the provided ID already exists. Default: True
+
+    Returns
+    -------
+        None
+    """
+
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"Cannot store a Blob without a JSON data dictionary:\n{STORE_DICT}"
+        )
+
+    # Encode value if it's not already Base64-encoded
+    if "value" in data and not is_base64(data["value"]):
+        # Encode to bytes, then Base64, then decode to string for storing
+        data["value"] = base64.b64encode(data["value"].encode("utf-8")).decode("utf-8")
+
+    endpoint = "blobs"
+    params = {"fail-if-exists": fail_if_exists}
+    return api.post(endpoint, data, params, api_version=1)

{cwms_python-0.5.0 → cwms_python-0.7.0}/cwms/catalog/catalog.py

@@ -77,6 +77,7 @@ def get_timeseries_catalog(
     timeseries_category_like: Optional[str] = None,
     timeseries_group_like: Optional[str] = "DMZ Include List",
     bounding_office_like: Optional[str] = None,
+    include_extents: Optional[bool] = False,
 ) -> Data:
     """Retrieves filters for the timeseries catalog
 
@@ -101,6 +102,8 @@ def get_timeseries_catalog(
             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
+        include_extents: bool
+            Whether to include the time series extents in the catalog
 
     Returns
     -------
@@ -122,6 +125,7 @@ def get_timeseries_catalog(
         "timeseries-category-like": timeseries_category_like,
         "timeseries-group-like": timeseries_group_like,
         "bounding-office-like": bounding_office_like,
+        "include-extents": include_extents,
     }
 
     response = api.get(endpoint=endpoint, params=params, api_version=2)

cwms_python-0.7.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.5.0 → cwms_python-0.7.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]
@@ -62,6 +62,7 @@ class 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: