cwms-python 1.0.1__tar.gz → 1.0.3__tar.gz

{cwms_python-1.0.1 → cwms_python-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cwms-python
-Version: 1.0.1
+Version: 1.0.3
 Summary: Corps water management systems (CWMS) REST API for Data Retrieval of USACE water data
 License: LICENSE
 License-File: LICENSE

{cwms_python-1.0.1 → cwms_python-1.0.3}/cwms/__init__.py

@@ -31,6 +31,7 @@ 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 *
+from cwms.users.users import *
 
 try:
     __version__ = version("cwms-python")

{cwms_python-1.0.1 → cwms_python-1.0.3}/cwms/api.py

@@ -78,10 +78,14 @@ class ApiError(Exception):
     a concise, single-line error message with an optional hint.
     """
 
-    def __init__(self, response: Response):
+    def __init__(self, response: Response, message: Optional[str] = None):
         self.response = response
+        self.message = message
 
     def __str__(self) -> str:
+        if self.message:
+            return self.message
+
         # Include the request URL in the error message.
         message = f"CWMS API Error ({self.response.url})"
 
@@ -125,6 +129,14 @@ class ApiError(Exception):
         return ""
 
 
+class NotFoundError(ApiError):
+    """Raised when a requested CDA resource does not exist."""
+
+
+class PermissionError(ApiError):
+    """Raised when the CDA request is not authorized for the current caller."""
+
+
 def init_session(
     *,
     api_root: Optional[str] = None,
@@ -160,7 +172,6 @@ def init_session(
     if api_key:
         if api_key.startswith("apikey "):
             api_key = api_key.replace("apikey ", "")
-        logging.debug(f"Setting authorization key: api_key={api_key}")
         SESSION.headers.update({"Authorization": "apikey " + api_key})
 
     return SESSION

{cwms_python-1.0.1 → cwms_python-1.0.3}/cwms/outlets/outlets.py

@@ -41,7 +41,7 @@ def get_outlet(office_id: str, name: str) -> Data:
 
     endpoint = f"projects/outlets/{name}"
     params = {"office": office_id}
-    response = api.get(endpoint, params)
+    response = api.get(endpoint, params, api_version=1)
     return Data(response)
 
 

{cwms_python-1.0.1 → cwms_python-1.0.3}/cwms/timeseries/timeseries.py

@@ -228,8 +228,13 @@ def combine_timeseries_results(results: List[Data]) -> Data:
     combined_json["end"] = combined_df["date-time"].max().isoformat()
     combined_json["total"] = len(combined_df)
 
+    combined_df["date-time"] = combined_df["date-time"].apply(
+        lambda x: int(pd.Timestamp(x).timestamp() * 1000)
+    )
+    combined_df["date-time"] = combined_df["date-time"].astype("Int64")
+    combined_df = combined_df.reindex(columns=["date-time", "value", "quality-code"])
     # Update the "values" key in the JSON to include the combined data
-    combined_json["values"] = combined_df.to_dict(orient="records")
+    combined_json["values"] = combined_df.values.tolist()
 
     # Return a new cwms Data object with the combined DataFrame and updated metadata
     return Data(combined_json, selector="values")
@@ -455,6 +460,32 @@ def store_multi_timeseries_df(
     office_id: str,
     max_workers: Optional[int] = 30,
 ) -> None:
+    """stored mulitple timeseries from a dataframe.  The dataframe must be a metled dataframe with columns
+    for date-time, value, quality-code(optional), ts_id, units, and version_date(optional).  The dataframe will
+    be grouped by ts_id and version_date and each group will be posted as a separate timeseries using the store_timeseries
+    function.  If version_date column is not included then all data will be stored as unversioned data.  If version_date
+    column is included then data will be grouped by ts_id and version_date and stored as versioned timeseries with the
+    version date specified in the version_date column.
+
+    Parameters
+    ----------
+        data: dataframe
+            Time Series data to be stored.  Dataframe must be melted with columns for date-time, value, quality-code(optional),
+            ts_id, units, and version_date(optional).
+                                        date-time value  quality-code  ts_id                                  units   version_date
+                0   2023-12-20T14:45:00.000-05:00  93.1           0   OMA.Stage.Inst.6Hours.0.Fcst-MRBWM-GRFT ft     2024-04-22 07:00:00-05:00
+                1   2023-12-20T15:00:00.000-05:00  99.8           0   OMA.Stage.Inst.6Hours.0.Fcst-MRBWM-GRFT ft     2024-04-22 07:00:00-05:00
+                2   2023-12-20T15:15:00.000-05:00  98.5           0   OMA.Stage.Inst.6Hours.0.Fcst-MRBWM-GRFT ft     2024-04-22 07:15:00-05:00
+        office_id: string
+            The owning office of the time series(s).
+        max_workers: Int, Optional, default is None
+            It is a number of Threads aka size of pool in concurrent.futures.ThreadPoolExecutor.
+
+        Returns
+        -------
+            None
+    """
+
     def store_ts_ids(
         data: pd.DataFrame,
         ts_id: str,
@@ -476,6 +507,12 @@ def store_multi_timeseries_df(
             print(f"Error processing {ts_id}: {e}")
         return None
 
+    required_columns = ["date-time", "value", "ts_id", "units"]
+    for col in required_columns:
+        if col not in data.columns:
+            raise TypeError(
+                f"{col} is a required column in data when posting multiple timeseries from a dataframe. Make sure you are using a melted dataframe with columns for date-time, value, quality-code(optional), ts_id, units, and version_date(optional)."
+            )
     ts_data_all = data.copy()
     if "version_date" not in ts_data_all.columns:
         ts_data_all = ts_data_all.assign(version_date=pd.to_datetime(pd.Series([])))

cwms_python-1.0.3/cwms/users/users.py

@@ -0,0 +1,155 @@
+import json
+from typing import Any, List, Optional
+
+import cwms.api as api
+from cwms.cwms_types import Data
+
+
+def _raise_user_management_error(error: api.ApiError, action: str) -> None:
+    status_code = getattr(error.response, "status_code", None)
+    if status_code == 403:
+        response_hint = getattr(error.response, "reason", None) or "Forbidden"
+        message = (
+            f"{action} could not be completed because the current credentials "
+            "are not authorized for user-management access or are missing the "
+            f"required role assignment. CDA responded with 403 {response_hint}."
+        )
+        raise api.PermissionError(error.response, message) from None
+    raise error
+
+
+def get_roles() -> List[str]:
+    """Retrieve all available user-management roles."""
+
+    try:
+        response = api.get("roles", api_version=1)
+    except api.ApiError as error:
+        _raise_user_management_error(error, "User role lookup")
+    return list(response)
+
+
+def get_user_profile() -> dict[str, Any]:
+    """Retrieve the profile for the currently authenticated user."""
+
+    response = api.get("user/profile", api_version=1)
+    return dict(response)
+
+
+def get_users(
+    office_id: Optional[str] = None,
+    page: Optional[str] = None,
+    page_size: Optional[int] = None,
+) -> Data:
+    """Retrieve users with optional office and paging filters."""
+
+    params = {"office": office_id, "page": page, "page-size": page_size}
+    try:
+        response = api.get("users", params=params, api_version=1)
+    except api.ApiError as error:
+        _raise_user_management_error(error, "User list lookup")
+    return Data(response, selector="users")
+
+
+def get_user(user_name: str) -> dict[str, Any]:
+    """Retrieve a single user by user name."""
+
+    if not user_name:
+        raise ValueError("Get user requires a user name")
+    try:
+        response = api.get(f"users/{user_name}", api_version=1)
+    except api.ApiError as error:
+        status_code = getattr(error.response, "status_code", None)
+        if status_code == 404:
+            raise api.NotFoundError(
+                error.response, f"User '{user_name}' was not found."
+            ) from None
+        if status_code == 403:
+            _raise_user_management_error(error, f"User '{user_name}' retrieval")
+        raise
+    return dict(response)
+
+
+def store_user(user_name: str, office_id: str, roles: List[str]) -> None:
+    """Create a user role assignment for an office.
+
+    Notes
+    -----
+    The CDA User Management API creates/manages user access through role assignment
+    at `/user/{user-name}/roles/{office-id}`.
+    """
+
+    if not user_name:
+        raise ValueError("Store user requires a user name")
+    if not office_id:
+        raise ValueError("Store user requires an office id")
+    if not roles:
+        raise ValueError("Store user requires a roles list")
+
+    endpoint = f"user/{user_name}/roles/{office_id}"
+    try:
+        api.post(endpoint, roles)
+    except api.ApiError as error:
+        _raise_user_management_error(
+            error, f"User '{user_name}' role assignment update"
+        )
+
+
+def delete_user_roles(user_name: str, office_id: str, roles: List[str]) -> None:
+    """Delete user role assignments for an office."""
+
+    if not user_name:
+        raise ValueError("Delete user roles requires a user name")
+    if not office_id:
+        raise ValueError("Delete user roles requires an office id")
+    if roles is None:
+        raise ValueError("Delete user roles requires a roles list")
+
+    endpoint = f"user/{user_name}/roles/{office_id}"
+    headers = {"accept": "*/*", "Content-Type": api.api_version_text(api.API_VERSION)}
+    # TODO: Delete does not currently support a body in the api module. Use SESSION directly
+    with api.SESSION.delete(
+        endpoint, headers=headers, data=json.dumps(roles)
+    ) as response:
+        if not response.ok:
+            _raise_user_management_error(
+                api.ApiError(response), f"User '{user_name}' role deletion"
+            )
+
+
+def update_user(user_name: str, office_id: str, roles: List[str]) -> None:
+    """Update a user's roles for an office by replacing the current role set."""
+
+    if not user_name:
+        raise ValueError("Update user requires a user name")
+    if not office_id:
+        raise ValueError("Update user requires an office id")
+    if not roles:
+        raise ValueError("Update user requires a roles list")
+
+    endpoint = f"user/{user_name}/roles/{office_id}"
+    user = get_user(user_name)
+
+    roles_by_office = user.get("roles")
+    if isinstance(roles_by_office, dict):
+        existing_roles = roles_by_office.get(office_id, [])
+    elif isinstance(roles_by_office, list):
+        existing_roles = roles_by_office
+    else:
+        existing_roles = []
+
+    if not isinstance(existing_roles, list):
+        existing_roles = []
+
+    desired_roles = sorted(set(roles))
+    current_roles = sorted(set(existing_roles))
+    # Determine roles to add and remove
+    roles_to_remove = [role for role in current_roles if role not in desired_roles]
+    roles_to_add = [role for role in desired_roles if role not in current_roles]
+
+    if roles_to_remove:
+        delete_user_roles(user_name, office_id, roles_to_remove)
+    if roles_to_add:
+        try:
+            api.post(endpoint, roles_to_add)
+        except api.ApiError as error:
+            _raise_user_management_error(error, f"User '{user_name}' role replacement")

{cwms_python-1.0.1 → cwms_python-1.0.3}/pyproject.toml

@@ -2,7 +2,7 @@
 name = "cwms-python"
 repository = "https://github.com/HydrologicEngineeringCenter/cwms-python"
 
-version = "1.0.1"
+version = "1.0.3"
 
 
 packages = [