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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cwms-python
-Version: 1.0.0
+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.0 → 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.0 → cwms_python-1.0.3}/cwms/api.py

@@ -29,6 +29,7 @@ the error.
 import base64
 import json
 import logging
+from http import HTTPStatus
 from json import JSONDecodeError
 from typing import Any, Optional, cast
 
@@ -72,15 +73,19 @@ class InvalidVersion(Exception):
 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.
+    Light wrapper around a response-like object (e.g., requests.Response or a
+    test stub with url, status_code, reason, and content attributes). Produces
+    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})"
 
@@ -91,23 +96,45 @@ class ApiError(Exception):
         message += "."
 
         # Add additional context to help the user resolve the issue.
-        if hint := self.hint():
+        hint = self.hint()
+        if hint:
             message += f" {hint}"
 
-        if content := self.response.content:
-            message += f" {content.decode('utf8')}"
+        # Optional content (decoded if bytes)
+        content = getattr(self.response, "content", None)
+        if content:
+            if isinstance(content, bytes):
+                try:
+                    text = content.decode("utf-8", errors="replace")
+                except Exception:
+                    text = repr(content)
+            else:
+                text = str(content)
+            message += f" {text}"
 
         return message
 
     def hint(self) -> str:
-        """Return a message with additional information on how to resolve the error."""
+        """Return a short hint based on HTTP status code."""
+        status = getattr(self.response, "status_code", None)
 
-        if self.response.status_code == 400:
+        if status == 429:
+            return "Too many requests made."
+        if status == 400:
             return "Check that your parameters are correct."
-        elif self.response.status_code == 404:
+        if status == 404:
             return "May be the result of an empty query."
-        else:
-            return ""
+
+        # No hint for other codes
+        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(
@@ -145,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
@@ -227,6 +253,12 @@ def _process_response(response: Response) -> Any:
             return response.text
         if content_type.startswith("image/"):
             return base64.b64encode(response.content).decode("utf-8")
+        # Handle excel content types
+        if content_type in [
+            "application/vnd.ms-excel",
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ]:
+            return response.content
         # Fallback for remaining content types
         return response.content.decode("utf-8")
     except JSONDecodeError as error:

{cwms_python-1.0.0 → 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.0 → 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([])))
@@ -606,8 +643,8 @@ def store_timeseries(
         for chunk in chunks:
             future = executor.submit(
                 api.post,  # The function to execute
-                endpoint,  # The chunk of data to store
-                data,
+                endpoint,
+                chunk,  # The chunk of data to store
                 params,
             )
             futures.append(future)  # Add the future to the list

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.0 → cwms_python-1.0.3}/pyproject.toml

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