cwms-python 1.0.8__tar.gz → 1.0.9__tar.gz

{cwms_python-1.0.8 → cwms_python-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cwms-python
-Version: 1.0.8
+Version: 1.0.9
 Summary: Corps water management systems (CWMS) REST API for Data Retrieval of USACE water data
 License: LICENSE
 License-File: LICENSE
@@ -16,8 +16,12 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: pandas (>=2.1.3,<3.0.0)
-Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: numpy (>=1.23.5,<3) ; python_version >= "3.9" and python_version < "3.13"
+Requires-Dist: numpy (>=2.1.0,<3) ; python_version == "3.13"
+Requires-Dist: numpy (>=2.3.3,<3) ; python_version >= "3.14"
+Requires-Dist: pandas (>=2.3.3,<3.0.0)
+Requires-Dist: requests (>=2.32.4,<3.0.0) ; python_version == "3.9"
+Requires-Dist: requests (>=2.33.0,<3.0.0) ; python_version >= "3.10"
 Requires-Dist: requests-toolbelt (>=1.0.0,<2.0.0)
 Project-URL: Repository, https://github.com/HydrologicEngineeringCenter/cwms-python
 Description-Content-Type: text/markdown
@@ -124,3 +128,8 @@ endpoint implementation.
 
 Please view the contribution documentation here: [CONTRIBUTING.md]
 
+## Contributing and releases
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development checks, PR title conventions,
+and the Release Please publishing workflow.
+

{cwms_python-1.0.8 → cwms_python-1.0.9}/README.md

@@ -99,3 +99,8 @@ endpoint implementation.
 ## Contributing
 
 Please view the contribution documentation here: [CONTRIBUTING.md]
+
+## Contributing and releases
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development checks, PR title conventions,
+and the Release Please publishing workflow.

{cwms_python-1.0.8 → cwms_python-1.0.9}/cwms/__init__.py

@@ -10,6 +10,7 @@ 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.lookups import *
 from cwms.locations.physical_locations import *
 from cwms.measurements.measurements import *
 from cwms.outlets.outlets import *
@@ -18,6 +19,7 @@ from cwms.projects.project_lock_rights import *
 from cwms.projects.project_locks import *
 from cwms.projects.projects import *
 from cwms.projects.water_supply.accounting import *
+from cwms.properties.properties import *
 from cwms.ratings.ratings import *
 from cwms.ratings.ratings_spec import *
 from cwms.ratings.ratings_template import *

{cwms_python-1.0.8 → cwms_python-1.0.9}/cwms/api.py

@@ -48,6 +48,9 @@ from cwms.cwms_types import JSON, RequestParams
 API_ROOT = "https://cwms-data.usace.army.mil/cwms-data/"
 API_VERSION = 2
 
+# Specify whether LRTS will use new ID format
+USE_NEW_LRTS_IDS = False
+
 # Initialize a non-authenticated session with the default root URL and set default pool connections.
 
 retry_strategy = Retry(
@@ -168,6 +171,7 @@ def init_session(
     api_key: Optional[str] = None,
     token: Optional[str] = None,
     pool_connections: int = 100,
+    use_new_lrts_format: bool = False,
 ) -> BaseUrlSession:
     """Specify a root URL and authentication credentials for the CWMS Data API.
 
@@ -186,7 +190,7 @@ def init_session(
         Returns the updated session object.
     """
 
-    global SESSION
+    global SESSION, USE_NEW_LRTS_IDS
     if api_root:
         # Ensure the API_ROOT ends with a single slash
         api_root = api_root.rstrip("/") + "/"
@@ -206,11 +210,23 @@ def init_session(
         # Ensure we don't provide the bearer text twice
         if token.lower().startswith("bearer "):
             token = token[7:]
-        SESSION.headers.update({"Authorization": "Bearer " + token})
+        SESSION.headers.update(
+            {
+                "Authorization": "Bearer " + token,
+                "X-CWMS-LRTS-Formatting": str(USE_NEW_LRTS_IDS).lower(),
+            }
+        )
     elif api_key:
         if api_key.startswith("apikey "):
             api_key = api_key.replace("apikey ", "")
-        SESSION.headers.update({"Authorization": "apikey " + api_key})
+        SESSION.headers.update(
+            {
+                "Authorization": "apikey " + api_key,
+                "X-CWMS-LRTS-Formatting": str(USE_NEW_LRTS_IDS).lower(),
+            }
+        )
+
+    USE_NEW_LRTS_IDS = use_new_lrts_format
 
     return SESSION
 
@@ -225,6 +241,46 @@ def return_base_url() -> str:
     return str(SESSION.base_url)
 
 
+def set_use_new_lrts_ids(state: bool) -> None:
+    """Sets whether the new LRTS identifer format is used for subsequent operations.
+
+    The old Local Regular Time Series (LRTS) identifier format is the same as the
+    Pseudo-Regular Time Series (PRTS) identifier format, where both prepend a tilde
+    character ('~') to valid Regular Time Series (RTS) interval identifiers (e.g.,
+    ~6Hours, ~1Day).
+
+    The new LRTS identifiers instead append "Local" to valid RTS interval identifiers
+    (e.g., 6HoursLocal, 1DayLocal), leaving the old format to specify only PRTS.
+
+    Args:
+        state: Whether the new LRTS identifier format is used
+    """
+
+    global USE_NEW_LRTS_IDS
+
+    USE_NEW_LRTS_IDS = state
+
+
+def get_use_new_lrts_ids() -> bool:
+    """Gets whether the new LRTS identifer format is used for subsequent operations.
+
+    The old Local Regular Time Series (LRTS) identifier format is the same as the
+    Pseudo-Regular Time Series (PRTS) identifier format, where both prepend a tilde
+    character ('~') to valid Regular Time Series (RTS) interval identifiers (e.g.,
+    ~6Hours, ~1Day).
+
+    The new LRTS identifiers instead append "Local" to valid RTS interval identifiers
+    (e.g., 6HoursLocal, 1DayLocal), leaving the old format to specify only PRTS.
+
+    Returns:
+        Whether the new LRTS identifier format is used
+    """
+
+    global USE_NEW_LRTS_IDS
+
+    return USE_NEW_LRTS_IDS
+
+
 def api_version_text(api_version: int) -> str:
     """Initialize CDA request headers.
 
@@ -329,7 +385,10 @@ def get(
         ApiError: If an error response is return by the API.
     """
 
-    headers = {"Accept": api_version_text(api_version)}
+    headers = {
+        "Accept": api_version_text(api_version),
+        "X-CWMS-LRTS-Formatting": str(USE_NEW_LRTS_IDS).lower(),
+    }
     try:
         with SESSION.get(endpoint, params=params, headers=headers) as response:
             if not response.ok:
@@ -389,7 +448,11 @@ def _post_function(
 ) -> Any:
 
     # post requires different headers than get for
-    headers = {"accept": "*/*", "Content-Type": api_version_text(api_version)}
+    headers = {
+        "accept": "*/*",
+        "Content-Type": api_version_text(api_version),
+        "X-CWMS-LRTS-Formatting": str(USE_NEW_LRTS_IDS).lower(),
+    }
     if isinstance(data, dict) or isinstance(data, list):
         data = json.dumps(data)
     try:
@@ -487,7 +550,11 @@ def patch(
         ApiError: If an error response is return by the API.
     """
 
-    headers = {"accept": "*/*", "Content-Type": api_version_text(api_version)}
+    headers = {
+        "accept": "*/*",
+        "Content-Type": api_version_text(api_version),
+        "X-CWMS-LRTS-Formatting": str(USE_NEW_LRTS_IDS).lower(),
+    }
 
     if data and isinstance(data, dict) or isinstance(data, list):
         data = json.dumps(data)
@@ -522,7 +589,10 @@ def delete(
         ApiError: If an error response is return by the API.
     """
 
-    headers = {"Accept": api_version_text(api_version)}
+    headers = {
+        "Accept": api_version_text(api_version),
+        "X-CWMS-LRTS-Formatting": str(USE_NEW_LRTS_IDS).lower(),
+    }
     try:
         with SESSION.delete(endpoint, params=params, headers=headers) as response:
             if not response.ok:

cwms_python-1.0.9/cwms/locations/lookups.py

@@ -0,0 +1,161 @@
+#  Copyright (c) 2026
+#  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
+
+import cwms.api as api
+from cwms.cwms_types import JSON, Data
+
+ENDPOINT = "lookup-types"
+
+
+def get_all_lookups(category: str, prefix: str, office_id: str) -> Data:
+    """
+    Retrieves all lookups for a given category, prefix, and office.
+
+    Parameters
+    ----------
+    category : str
+        Filters lookup types to the specified category
+    prefix : str
+        Filters lookup types to the specified prefix
+    office_id : str
+        Filters lookup types to the specified office ID
+
+    Returns
+    -------
+    Data
+        The JSON response from CWMS Data API wrapped in a Data object.
+
+    Raises
+    ------
+    ValueError
+        If any required argument is missing.
+    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 not all([category, prefix, office_id]):
+        raise ValueError("Category, Prefix, and Office ID must be specified")
+
+    params = {"category": category, "prefix": prefix, "office": office_id}
+    response = api.get(ENDPOINT, params, api_version=1)
+    return Data(response)
+
+
+def create_lookup(data: JSON, category: str, prefix: str) -> None:
+    """
+    Creates a new lookup entry.
+
+    Parameters
+    ----------
+    data: JSON
+        A dictionary representing the JSON data to be stored. This should match the
+        LookupType structure as defined by the API.
+    category : str
+        Specifies the category of the lookup.
+    prefix : str
+        Specifies the prefix of the lookup.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If any required argument is missing.
+    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 not all([category, prefix]):
+        raise ValueError("Category and Prefix must be specified")
+    if not data:
+        raise ValueError("Data must be specified")
+    params = {"category": category, "prefix": prefix}
+    api.post(ENDPOINT, data, params, api_version=1)
+
+
+def update_lookup(data: JSON, category: str, prefix: str) -> None:
+    """
+    Updates a specified lookup entry.
+
+    Parameters
+    ----------
+    data : JSON
+        A dictionary representing the JSON data to be stored.
+        If the `data` value is None, a `ValueError` will be raised.
+    category : str
+        Specifies the category of the lookup.
+    prefix : str
+        Specifies the prefix of the lookup.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If any required argument is missing.
+    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 not all([category, prefix]):
+        raise ValueError("Category and Prefix must be specified")
+    if not data:
+        raise ValueError("Data must be specified")
+
+    # Note that the path parameter is unused in CDA
+    endpoint = f"{ENDPOINT}/{category}"
+    params = {"category": category, "prefix": prefix}
+    api.patch(endpoint, data, params, api_version=1)
+
+
+def delete_lookup(name: str, category: str, prefix: str, office_id: str) -> None:
+    """
+    Deletes a specified lookup entry.
+
+    Parameters
+    ----------
+    name : str
+        Specifies the location type to delete.
+    category : str
+        Specifies the category id of the lookup type to be deleted.
+    prefix : str
+        Specifies the prefix of the lookup type to be deleted.
+    office_id : str
+        Specifies the owning office of the lookup type to be deleted.
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        If any required argument is missing.
+    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 not all([name, category, prefix, office_id]):
+        raise ValueError("Name, Category, Prefix, and Office ID must be specified")
+
+    endpoint = f"{ENDPOINT}/{name}"
+    params = {"category": category, "prefix": prefix, "office": office_id}
+    api.delete(endpoint, params, api_version=1)

{cwms_python-1.0.8 → cwms_python-1.0.9}/cwms/projects/projects.py

@@ -42,7 +42,7 @@ def get_project(office_id: str, name: str) -> Data:
 
     endpoint = f"projects/{name}"
     params = {"office": office_id}
-    response = api.get(endpoint, params)
+    response = api.get(endpoint, params, api_version=1)
     return Data(response)
 
 
@@ -129,7 +129,7 @@ def get_project_locations(
         "project-like": project_like,
         "location-kind-like": location_id_like,
     }
-    response = api.get(endpoint, params)
+    response = api.get(endpoint, params, api_version=1)
     return Data(response)
 
 
@@ -169,7 +169,7 @@ def delete_project(office_id: str, name: str, delete_method: DeleteMethod) -> No
 
     endpoint = f"projects/{name}"
     params = {"office": office_id, "method": delete_method.name}
-    api.delete(endpoint, params)
+    api.delete(endpoint, params, api_version=1)
 
 
 def rename_project(office_id: str, old_name: str, new_name: str) -> None:

cwms_python-1.0.9/cwms/properties/properties.py

@@ -0,0 +1,168 @@
+#  Copyright (c) 2026
+#  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
+
+
+def get_properties(
+    office_mask: Optional[str] = None,
+    category_id_mask: Optional[str] = None,
+    name_mask: Optional[str] = None,
+) -> Data:
+    """
+    Returns matching CWMS Property Data.
+
+    Parameters
+    ----------
+        office_mask: string, optional
+            Filters properties to the specified office mask
+        category_id_mask: string, optional
+            Filters properties to the specified category mask
+        name_mask: string, optional
+            Filters properties to the specified name mask
+
+    Returns
+    -------
+        cwms data type
+    """
+
+    endpoint = "properties"
+    params = {
+        "office-mask": office_mask,
+        "category-id-mask": category_id_mask,
+        "name-mask": name_mask,
+    }
+
+    response = api.get(endpoint, params, api_version=1)
+    return Data(response)
+
+
+def get_property(
+    name: str, office: str, category_id: str, default_value: Optional[str] = None
+) -> Data:
+    """
+    Returns CWMS Property Data.
+
+    Parameters
+    ----------
+        name: string
+            Specifies the name of the property to be retrieved.
+        office: string
+            Specifies the owning office of the property to be retrieved.
+        category_id: string
+            Specifies the category id of the property to be retrieved.
+        default_value: string, optional
+            Specifies the default value if the property does not exist.
+
+    Returns
+    -------
+        cwms data type
+    """
+
+    endpoint = f"properties/{name}"
+    params = {
+        "office": office,
+        "category-id": category_id,
+        "default-value": default_value,
+    }
+
+    response = api.get(endpoint, params, api_version=1)
+    return Data(response)
+
+
+def create_property(data: JSON) -> None:
+    """
+    Create CWMS Property.
+
+    Parameters
+    ----------
+        data: JSON dictionary
+            Property data to be stored.
+            Example:
+            {
+                "office-id": "string",
+                "name": "string",
+                "category": "string",
+                "value": "string",
+                "comment": "string"
+            }
+
+    Returns
+    -------
+        None
+    """
+
+    endpoint = "properties"
+
+    if data is None:
+        raise ValueError("Cannot store a property without JSON data")
+
+    return api.post(endpoint, data, api_version=1)
+
+
+def update_property(name: str, data: JSON) -> None:
+    """
+    Update CWMS Property.
+
+    Parameters
+    ----------
+        name: string
+            Specifies the name of the property to be updated.
+        data: JSON dictionary
+            Property data to be updated.
+            Example:
+            {
+                "office-id": "string",
+                "name": "string",
+                "category": "string",
+                "value": "string",
+                "comment": "string"
+            }
+
+    Returns
+    -------
+        None
+    """
+
+    endpoint = f"properties/{name}"
+
+    if name is None:
+        raise ValueError("Must specify a property name to update")
+
+    if data is None:
+        raise ValueError("Cannot update a property without JSON data")
+
+    return api.patch(endpoint, data, api_version=1)
+
+
+def delete_property(name: str, office: str, category_id: str) -> None:
+    """
+    Delete CWMS Property.
+
+    Parameters
+    ----------
+        name: string
+            Specifies the name of the property to be deleted.
+        office: string
+            Specifies the owning office of the property to be deleted.
+        category_id: string
+            Specifies the category id of the property to be deleted.
+
+    Returns
+    -------
+        None
+    """
+
+    endpoint = f"properties/{name}"
+
+    params = {
+        "office": office,
+        "category-id": category_id,
+    }
+
+    return api.delete(endpoint, params, api_version=1)

{cwms_python-1.0.8 → cwms_python-1.0.9}/cwms/timeseries/timeseries.py

@@ -166,6 +166,9 @@ def _call_with_retry(fn: Any, *args: Any, attempts: int = _CHUNK_ATTEMPTS) -> An
         try:
             return fn(*args)
         except Exception as e:
+            status_code = getattr(getattr(e, "response", None), "status_code", None)
+            if status_code == 404:
+                raise
             if i == attempts - 1:
                 raise
             logging.warning(f"chunk attempt {i + 1}/{attempts} failed: {e}")
@@ -525,7 +528,7 @@ def store_multi_timeseries_df(
                 DELETE_INSERT.
         override_protection: bool, optional, default is False
             A flag to ignore the protected data quality flag when storing data.
-        multithread: bool, default is false
+        multithread: bool, default is true
             Specifies whether to store chunked time series values using multiple threads.
         max_workers: Int, Optional, default is None
             It is a number of Threads aka size of pool in concurrent.futures.ThreadPoolExecutor.
@@ -533,6 +536,12 @@ def store_multi_timeseries_df(
         Returns
         -------
             None
+
+        Raises
+        ------
+        RuntimeError
+            If any series fails to store. The message identifies failed series;
+            other series may already have been stored successfully.
     """
 
     def store_ts_ids(
@@ -541,24 +550,21 @@ def store_multi_timeseries_df(
         office_id: str,
         version_date: Optional[datetime] = None,
     ) -> None:
-        try:
-            units = data["units"].iloc[0]
-            data_json = timeseries_df_to_json(
-                data=data,
-                ts_id=ts_id,
-                units=units,
-                office_id=office_id,
-                version_date=version_date,
-            )
-            store_timeseries(
-                data=data_json,
-                create_as_ltrs=create_as_ltrs,
-                store_rule=store_rule,
-                override_protection=override_protection,
-                multithread=multithread,
-            )
-        except Exception as e:
-            print(f"Error processing {ts_id}: {e}")
+        units = data["units"].iloc[0]
+        data_json = timeseries_df_to_json(
+            data=data,
+            ts_id=ts_id,
+            units=units,
+            office_id=office_id,
+            version_date=version_date,
+        )
+        store_timeseries(
+            data=data_json,
+            create_as_ltrs=create_as_ltrs,
+            store_rule=store_rule,
+            override_protection=override_protection,
+            multithread=multithread,
+        )
         return None
 
     required_columns = ["date-time", "value", "ts_id", "units"]
@@ -574,7 +580,9 @@ def store_multi_timeseries_df(
         ts_data_all["ts_id"].astype(str) + ":" + ts_data_all["version_date"].astype(str)
     ).unique()
 
+    errors: List[str] = []
     with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {}
         for unique_tsid in unique_tsids:
             ts_id, version_date = unique_tsid.split(":", 1)
             if version_date != "NaT":
@@ -589,9 +597,21 @@ def store_multi_timeseries_df(
                     (ts_data_all["ts_id"] == ts_id) & ts_data_all["version_date"].isna()
                 ]
             if not data.empty:
-                executor.submit(
+                future = executor.submit(
                     store_ts_ids, ts_data, ts_id, office_id, version_date_dt
                 )
+                futures[future] = unique_tsid
+
+        for future in concurrent.futures.as_completed(futures):
+            try:
+                future.result()
+            except Exception as e:
+                errors.append(f"{futures[future]}: {e}")
+
+    if errors:
+        raise RuntimeError(
+            f"{len(errors)} time series failed to store:\n" + "\n".join(errors)
+        )
 
 
 def chunk_timeseries_data(
@@ -683,7 +703,14 @@ def store_timeseries(
     if len(chunks) == 1 or not multithread:
         return api.post(endpoint, data, params)
 
-    actual_workers = min(max_workers, len(chunks))
+    if max_workers <= 0:
+        raise ValueError("max_workers must be greater than 0")
+
+    # A new series must exist before multiple transactions can write its data.
+    # Complete one normal write first, then retain parallelism for the rest.
+    _call_with_retry(api.post, endpoint, chunks[0], params)
+    remaining_chunks = chunks[1:]
+    actual_workers = min(max_workers, len(remaining_chunks))
     logging.debug(
         f"Storing {len(chunks)} chunks of timeseries data with {actual_workers} threads"
     )
@@ -695,7 +722,7 @@ def store_timeseries(
     with concurrent.futures.ThreadPoolExecutor(max_workers=actual_workers) as executor:
         future_to_chunk = {
             executor.submit(_call_with_retry, api.post, endpoint, chunk, params): chunk
-            for chunk in chunks
+            for chunk in remaining_chunks
         }
 
         for future in concurrent.futures.as_completed(future_to_chunk):

{cwms_python-1.0.8 → cwms_python-1.0.9}/pyproject.toml

@@ -2,7 +2,8 @@
 name = "cwms-python"
 repository = "https://github.com/HydrologicEngineeringCenter/cwms-python"
 
-version = "1.0.8"
+# Managed by Release Please; runtime versions come from package metadata.
+version = "1.0.9"
 
 packages = [
     { include = "cwms" },
@@ -15,16 +16,31 @@ authors = ["Eric Novotny <eric.v.novotny@usace.army.mil>"]
 
 [tool.poetry.dependencies]
 python = "^3.9"
-pandas = "^2.1.3"
+pandas = "^2.3.3"
+# Require NumPy wheels for newer Python versions while retaining Python 3.9.
+numpy = [
+    {version = ">=1.23.5,<3", python = ">=3.9,<3.13"},
+    {version = ">=2.1.0,<3", python = ">=3.13,<3.14"},
+    {version = ">=2.3.3,<3", python = ">=3.14"},
+]
 requests-toolbelt = "^1.0.0"
-requests = "^2.31.0"
+requests = [
+    {version = "^2.32.4", python = ">=3.9,<3.10"},
+    {version = "^2.33.0", python = ">=3.10"},
+]
 
 [tool.poetry.group.dev.dependencies]
-black = "^24.2.0"
+black = [
+    {version = "^25.1.0", python = ">=3.9,<3.10"},
+    {version = "^26.3.1", python = ">=3.10"},
+]
 isort = "^5.13.2"
 mypy = "^1.9.0"
 pre-commit = "^3.6.2"
-pytest = "^8.1.1"
+pytest = [
+    {version = "^8.3.5", python = ">=3.9,<3.10"},
+    {version = "^9.0.3", python = ">=3.10"},
+]
 requests-mock = "^1.11.0"
 pytest-cov = "^4.1.0"
 pandas-stubs = "^2.2.1.240316"