hydroserverpy 2.0.0b2__tar.gz → 2.0.0b4__tar.gz

{hydroserverpy-2.0.0b2/src/hydroserverpy.egg-info → hydroserverpy-2.0.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hydroserverpy
-Version: 2.0.0b2
+Version: 2.0.0b4
 Summary: A Python client for managing HydroServer data
 Home-page: https://github.com/hydroserver2/hydroserver/tree/main/packages/hydroserverpy
 Author: Kenneth Lippold

{hydroserverpy-2.0.0b2 → hydroserverpy-2.0.0b4}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = hydroserverpy
-version = 2.0.0b2
+version = 2.0.0b4
 description = A Python client for managing HydroServer data
 long_description = file: README.md
 long_description_content_type = text/markdown

{hydroserverpy-2.0.0b2 → hydroserverpy-2.0.0b4}/src/hydroserverpy/api/client.py

@@ -13,6 +13,7 @@ from hydroserverpy.api.services import (
     DatastreamService,
     DataConnectionService,
     TaskService,
+    EtlMappingService,
     MonitoringTaskService,
     MonitoringRuleService,
     RatingCurveService,
@@ -25,7 +26,7 @@ class HydroServer:
     def __init__(
         self,
         host: str,
-        base_route: str = "/api/data",
+        base_route: str = "/api/ogc",
         email: Optional[str] = None,
         password: Optional[str] = None,
         apikey: Optional[str] = None,
@@ -45,9 +46,28 @@ class HydroServer:
 
         self._init_session()
 
+    @staticmethod
+    def _encode_query_value(value):
+        """
+        Encodes booleans as the lowercase 'true' and 'false' the API requires; requests would
+        otherwise send str(value), i.e. 'True' and 'False'.
+        """
+
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if isinstance(value, (list, tuple)):
+            return [HydroServer._encode_query_value(item) for item in value]
+
+        return value
+
     def request(self, method, path, *args, **kwargs) -> requests.Response:
         """Sends a request to HydroServer's API."""
 
+        if isinstance(kwargs.get("params"), dict):
+            kwargs["params"] = {
+                key: self._encode_query_value(value) for key, value in kwargs["params"].items()
+            }
+
         for attempt in range(2):
             try:
                 response = getattr(self._session, method)(
@@ -172,6 +192,12 @@ class HydroServer:
 
         return TaskService(self)
 
+    @property
+    def etlmappings(self):
+        """Utilities for managing HydroServer ETL mappings."""
+
+        return EtlMappingService(self)
+
     @property
     def monitoringtasks(self):
         """Utilities for managing HydroServer monitoring tasks."""

{hydroserverpy-2.0.0b2 → hydroserverpy-2.0.0b4}/src/hydroserverpy/api/models/__init__.py

@@ -2,7 +2,7 @@ from .iam.account import Account
 from .iam.workspace import Workspace
 from .iam.role import Role
 from .iam.collaborator import Collaborator
-from .iam.apikey import APIKey
+from .iam.service_account import ServiceAccount
 from .iam.account import Account
 from .sta.datastream import Datastream
 from .sta.observation import ObservationCollection
@@ -30,4 +30,4 @@ from .products.transformation import (
 Workspace.model_rebuild()
 Role.model_rebuild()
 Collaborator.model_rebuild()
-APIKey.model_rebuild()
+ServiceAccount.model_rebuild()

{hydroserverpy-2.0.0b2 → hydroserverpy-2.0.0b4}/src/hydroserverpy/api/models/base.py

@@ -97,10 +97,9 @@ class HydroServerBaseModel(BaseModel):
 class HydroServerCollection:
     items: List["HydroServerBaseModel"]
     filters: Optional[dict[str, Any]] = None
-    order_by: Optional[List[str]] = None
-    page: Optional[int] = None
-    page_size: Optional[int] = None
-    total_pages: Optional[int] = None
+    sortby: Optional[List[str]] = None
+    offset: Optional[int] = None
+    limit: Optional[int] = None
     total_count: Optional[int] = None
 
     _service: Optional[Any] = field(init=False, repr=False)
@@ -116,40 +115,36 @@ class HydroServerCollection:
         self._service = service
 
         self.filters = data.get("filters")
-        self.order_by = data.get("order_by")
-        self.page = self._resolve_int_metadata("page", "X-Page", response, data)
-        self.page_size = self._resolve_int_metadata(
-            "page_size", "X-Page-Size", response, data
-        )
-        self.total_pages = self._resolve_int_metadata(
-            "total_pages", "X-Total-Pages", response, data
-        )
-        self.total_count = self._resolve_int_metadata(
-            "total_count", "X-Total-Count", response, data
-        )
+        self.sortby = data.get("sortby")
+
+        payload = response.json() if response is not None else {}
+        meta = payload.get("meta", {}) if isinstance(payload, dict) else {}
+
+        self.offset = self._resolve_int_metadata("offset", meta, data)
+        self.limit = self._resolve_int_metadata("limit", meta, data)
+        self.total_count = self._resolve_int_metadata("total_count", meta, data, meta_key="numberMatched")
 
         if "items" in data:
             self.items = data["items"]
         elif response is not None:
-            self.items = [model(client=client, **entity) for entity in response.json()]
+            self.items = [model(client=client, **entity) for entity in payload.get("data", [])]
         else:
             self.items = []
 
     @staticmethod
     def _resolve_int_metadata(
         field_name: str,
-        header_name: str,
-        response: Optional[Response],
+        meta: dict,
         data: dict,
+        meta_key: Optional[str] = None,
     ) -> Optional[int]:
         field_value = data.get(field_name)
         if field_value is not None:
             return int(field_value)
 
-        if response:
-            header_value = response.headers.get(header_name)
-            if header_value is not None:
-                return int(header_value)
+        meta_value = meta.get(meta_key or field_name)
+        if meta_value is not None:
+            return int(meta_value)
 
         return None
 
@@ -163,11 +158,13 @@ class HydroServerCollection:
         if not self._service:
             raise NotImplementedError("Pagination not enabled for this collection.")
 
+        limit = self.limit or 100
+
         return self._service.list(
             **(self.filters or {}),
-            page=(self.page or 0) + 1,
-            page_size=self.page_size or 100,
-            order_by=self.order_by or ...
+            offset=(self.offset or 0) + limit,
+            limit=limit,
+            sortby=self.sortby or ...
         )
 
     def previous_page(self):
@@ -176,14 +173,16 @@ class HydroServerCollection:
         if not self._service:
             raise NotImplementedError("Pagination not enabled for this collection.")
 
-        if not self.page or self.page <= 1:
+        if not self.offset:
             return None
 
+        limit = self.limit or 100
+
         return self._service.list(
             **(self.filters or {}),
-            page=self.page - 1,
-            page_size=self.page_size or 100,
-            order_by=self.order_by or ...
+            offset=max(0, self.offset - limit),
+            limit=limit,
+            sortby=self.sortby or ...
         )
 
     def fetch_all(self) -> "HydroServerCollection":
@@ -192,30 +191,23 @@ class HydroServerCollection:
         if not self._service:
             raise NotImplementedError("Pagination not enabled for this collection.")
 
-        all_items = []
-        current_page = self.page or 1
-        page_size = self.page_size or 100
-        total_pages = self.total_pages
-
-        page_num = 1
-        while total_pages is None or page_num <= total_pages:
-            if page_num == current_page:
-                all_items.extend(self.items)
-            else:
-                page = self._service.list(
-                    **(self.filters or {}),
-                    page=page_num,
-                    page_size=page_size,
-                    order_by=self.order_by or ...
-                )
-                if not page.items:
-                    break
-                all_items.extend(page.items)
-
-                if page.total_pages is not None:
-                    total_pages = page.total_pages
-
-            page_num += 1
+        all_items = list(self.items)
+        limit = self.limit or 100
+        next_offset = (self.offset or 0) + len(self.items)
+        last_page_size = len(self.items)
+
+        while last_page_size == limit:
+            page = self._service.list(
+                **(self.filters or {}),
+                offset=next_offset,
+                limit=limit,
+                sortby=self.sortby or ...
+            )
+            if not page.items:
+                break
+            all_items.extend(page.items)
+            last_page_size = len(page.items)
+            next_offset += last_page_size
 
         return self.__class__(
             model=type(self.items[0]) if self.items else None,
@@ -223,9 +215,8 @@ class HydroServerCollection:
             service=self._service,
             items=all_items,
             filters=self.filters,
-            order_by=self.order_by,
-            page=1,
-            page_size=len(all_items),
-            total_pages=1,
-            total_count=len(all_items)
+            sortby=self.sortby,
+            offset=0,
+            limit=len(all_items),
+            total_count=len(all_items),
         )

{hydroserverpy-2.0.0b2 → hydroserverpy-2.0.0b4}/src/hydroserverpy/api/models/etl/data_connection.py

@@ -109,4 +109,4 @@ class DataConnection(HydroServerBaseModel):
 
     @classmethod
     def get_route(cls):
-        return "etl/data-connections"
+        return "collections/etl-data-connections/items"

hydroserverpy-2.0.0b4/src/hydroserverpy/api/models/etl/mapping.py

@@ -0,0 +1,26 @@
+import uuid
+from typing import ClassVar, TYPE_CHECKING
+from pydantic import AliasChoices, AliasPath, Field
+from ..base import HydroServerBaseModel
+
+if TYPE_CHECKING:
+    from hydroserverpy import HydroServer
+
+
+class EtlMapping(HydroServerBaseModel):
+    task_id: uuid.UUID = Field(validation_alias="etlTaskId")
+    source_identifier: str
+    target_datastream_id: uuid.UUID = Field(
+        validation_alias=AliasChoices(
+            "targetDatastreamId", AliasPath("targetDatastream", "id")
+        )
+    )
+
+    _editable_fields: ClassVar[set[str]] = {"source_identifier", "target_datastream_id"}
+
+    def __init__(self, client: "HydroServer", **data):
+        super().__init__(client=client, service=client.etlmappings, **data)
+
+    @classmethod
+    def get_route(cls):
+        return "collections/etl-mappings/items"

{hydroserverpy-2.0.0b2 → hydroserverpy-2.0.0b4}/src/hydroserverpy/api/models/etl/task.py

@@ -1,7 +1,8 @@
 import uuid
 from datetime import datetime
+from functools import cached_property
 from typing import Any, ClassVar, Dict, List, Literal, Optional, Union, TYPE_CHECKING
-from pydantic import Field, AliasPath
+from pydantic import AliasChoices, Field, AliasPath
 from ..base import HydroServerBaseModel
 from ..orchestration.run import TaskRun
 from .mapping import EtlMapping
@@ -15,7 +16,11 @@ class EtlTask(HydroServerBaseModel):
     name: str
     description: Optional[str] = None
     task_variables: Dict[str, Any] = Field(default_factory=dict)
-    data_connection_id: uuid.UUID
+    data_connection_id: uuid.UUID = Field(
+        validation_alias=AliasChoices(
+            "dataConnectionId", AliasPath("dataConnection", "id")
+        )
+    )
     enabled: Optional[bool] = Field(None, validation_alias=AliasPath("schedule", "enabled"))
     start_time: Optional[datetime] = Field(None, validation_alias=AliasPath("schedule", "startTime"))
     crontab: Optional[str] = Field(None, validation_alias=AliasPath("schedule", "crontab"))
@@ -25,7 +30,7 @@ class EtlTask(HydroServerBaseModel):
     )
     next_run_at: Optional[datetime] = Field(None, validation_alias=AliasPath("schedule", "nextRunAt"))
     latest_run: Optional[TaskRun] = None
-    mappings: List[EtlMapping] = []
+    mapping_count: int = 0
 
     _editable_fields: ClassVar[set[str]] = set()
 
@@ -46,10 +51,6 @@ class EtlTask(HydroServerBaseModel):
             name=self.name,
             description=self.description,
             task_variables=self.task_variables,
-            mappings=[
-                {"source_identifier": m.source_identifier, "target_datastream_id": str(m.target_datastream_id)}
-                for m in self.mappings
-            ],
             crontab=self.crontab,
             interval=self.interval,
             interval_period=self.interval_period,
@@ -61,7 +62,13 @@ class EtlTask(HydroServerBaseModel):
 
     @classmethod
     def get_route(cls):
-        return "etl/tasks"
+        return "collections/etl-tasks/items"
+
+    @cached_property
+    def mappings(self) -> List[EtlMapping]:
+        """All source-to-datastream mappings for this ETL task."""
+
+        return self.client.etlmappings.list(etl_task=self.uid, fetch_all=True).items
 
     @property
     def data_connection(self) -> "DataConnection":
@@ -76,9 +83,9 @@ class EtlTask(HydroServerBaseModel):
 
     def list_runs(
         self,
-        page: int = ...,
-        page_size: int = ...,
-        order_by: List[str] = ...,
+        offset: int = ...,
+        limit: int = ...,
+        sortby: List[str] = ...,
         status: str = ...,
         started_at_min: datetime = ...,
         started_at_max: datetime = ...,
@@ -89,9 +96,9 @@ class EtlTask(HydroServerBaseModel):
 
         return self.client.etltasks.list_runs(
             uid=self.uid,
-            page=page,
-            page_size=page_size,
-            order_by=order_by,
+            offset=offset,
+            limit=limit,
+            sortby=sortby,
             status=status,
             started_at_min=started_at_min,
             started_at_max=started_at_max,

{hydroserverpy-2.0.0b2 → hydroserverpy-2.0.0b4}/src/hydroserverpy/api/models/iam/collaborator.py

@@ -1,6 +1,5 @@
-from typing import Union, ClassVar, TYPE_CHECKING
+from typing import Optional, Union, ClassVar, TYPE_CHECKING
 from uuid import UUID
-from pydantic import Field, AliasPath
 from hydroserverpy.api.models.iam.role import Role
 from hydroserverpy.api.utils import normalize_uuid
 from ..base import HydroServerBaseModel
@@ -8,13 +7,13 @@ from ..base import HydroServerBaseModel
 if TYPE_CHECKING:
     from hydroserverpy import HydroServer
     from hydroserverpy.api.models.iam.workspace import Workspace
-    from hydroserverpy.api.models.iam.account import Account
 
 
 class Collaborator(HydroServerBaseModel):
-    user: "Account"
-    role_id: Union[UUID, str] = Field(..., validation_alias=AliasPath("role", "id"))
+    role_id: Union[UUID, str]
     workspace_id: Union[UUID, str]
+    user_email: Optional[str] = None
+    service_account_email: Optional[str] = None
 
     _editable_fields: ClassVar[set[str]] = {"role_id"}
 
@@ -22,7 +21,19 @@ class Collaborator(HydroServerBaseModel):
         super().__init__(client=client, service=None, **data)
 
         self._workspace = None
-        self._role = Role(client=client, **data.get("role"))
+        self._role = None
+
+    @property
+    def email(self) -> str:
+        """The email identifying whichever principal (user or service account) this collaborator is."""
+
+        return self.user_email or self.service_account_email
+
+    @property
+    def is_service_account(self) -> bool:
+        """Whether this collaborator is a service account rather than a user."""
+
+        return self.service_account_email is not None
 
     @property
     def workspace(self) -> "Workspace":
@@ -54,17 +65,19 @@ class Collaborator(HydroServerBaseModel):
         """Saves changes to this resource to HydroServer."""
 
         if self.unsaved_changes:
-            self.client.workspaces.edit_collaborator_role(
-                uid=str(self.workspace_id), email=self.user.email, role=self.role
+            saved = self.client.workspaces.edit_collaborator_role(
+                uid=str(self.workspace_id), email=self.email, role=self.role_id
             )
             self._role = None
             self._server_data["role_id"] = self.role_id
             self.__dict__.update({"role_id": self.role_id})
+            if saved is not None:
+                self.__dict__.update(saved.__dict__)
 
     def delete(self):
         """Deletes this resource from HydroServer."""
 
         self.client.workspaces.remove_collaborator(
-            uid=str(self.workspace_id), email=self.user.email
+            uid=str(self.workspace_id), email=self.email
         )
         self.uid = None

{hydroserverpy-2.0.0b2 → hydroserverpy-2.0.0b4}/src/hydroserverpy/api/models/iam/role.py

@@ -10,7 +10,7 @@ if TYPE_CHECKING:
 
 class Role(HydroServerBaseModel):
     name: str = Field(..., max_length=255)
-    description: str
+    description: Optional[str] = None
     workspace_id: Optional[Union[UUID, str]] = None
 
     def __init__(self, client: "HydroServer", **data):
@@ -20,7 +20,7 @@ class Role(HydroServerBaseModel):
 
     @classmethod
     def get_route(cls):
-        return "roles"
+        return "collections/roles/items"
 
     @property
     def workspace(self) -> "Workspace":

hydroserverpy-2.0.0b2/src/hydroserverpy/api/models/iam/apikey.py → hydroserverpy-2.0.0b4/src/hydroserverpy/api/models/iam/service_account.py

@@ -1,7 +1,6 @@
 from typing import Optional, Union, ClassVar, TYPE_CHECKING
 from uuid import UUID
 from datetime import datetime
-from hydroserverpy.api.models.iam.role import Role
 from hydroserverpy.api.utils import normalize_uuid
 from ..base import HydroServerBaseModel
 
@@ -10,48 +9,32 @@ if TYPE_CHECKING:
     from hydroserverpy.api.models import Workspace
 
 
-class APIKey(HydroServerBaseModel):
+class ServiceAccount(HydroServerBaseModel):
     name: str
-    role_id: Union[UUID, str]
+    email: str
     workspace_id: Union[UUID, str]
     description: Optional[str] = None
     is_active: bool
-    expires_at: Optional[datetime] = None
+    key_expires_at: Optional[datetime] = None
+    created_at: datetime
+    last_used_at: Optional[datetime] = None
 
-    _editable_fields: ClassVar[set[str]] = {"name", "description", "role_id", "is_active", "expires_at"}
+    _editable_fields: ClassVar[set[str]] = {"name", "description", "is_active", "key_expires_at"}
 
     def __init__(self, client: "HydroServer", **data):
         super().__init__(client=client, service=None, **data)
 
         self._workspace = None
-        self._role = None
 
     @property
     def workspace(self) -> "Workspace":
-        """The workspace this API key belongs to."""
+        """The workspace this service account belongs to."""
 
         if self._workspace is None:
             self._workspace = self.client.workspaces.get(uid=self.workspace_id)
 
         return self._workspace
 
-    @property
-    def role(self) -> "Role":
-        """The role this API key is assigned."""
-
-        if self._role is None:
-            self._role = self.client.roles.get(uid=self.role_id)
-
-        return self._role
-
-    @role.setter
-    def role(self, role: Union["Role", UUID, str] = ...):
-        if not role:
-            raise ValueError("Role of API key cannot be None.")
-        if normalize_uuid(role) != str(self.role_id):
-            self.role_id = normalize_uuid(role)
-            self._role = None
-
     def save(self):
         """Saves changes to this resource to HydroServer."""
 
@@ -59,8 +42,8 @@ class APIKey(HydroServerBaseModel):
             raise AttributeError("Data cannot be saved: UID is not set.")
 
         if self.unsaved_changes:
-            saved_resource = self.client.workspaces.update_api_key(
-                uid=self.workspace_id, api_key_id=self.uid, **self.unsaved_changes
+            saved_resource = self.client.workspaces.update_service_account(
+                uid=self.workspace_id, service_account_id=self.uid, **self.unsaved_changes
             )
             self._server_data = saved_resource.dict(by_alias=False).copy()
             self.__dict__.update(saved_resource.__dict__)
@@ -71,7 +54,9 @@ class APIKey(HydroServerBaseModel):
         if self.uid is None:
             raise ValueError("Cannot refresh data without a valid ID.")
 
-        refreshed_resource = self.client.workspaces.get_api_key(uid=self.workspace_id, api_key_id=self.uid)
+        refreshed_resource = self.client.workspaces.get_service_account(
+            uid=self.workspace_id, service_account_id=self.uid
+        )
         self._server_data = refreshed_resource.dict(by_alias=False).copy()
         self.__dict__.update(refreshed_resource.__dict__)
 
@@ -81,16 +66,16 @@ class APIKey(HydroServerBaseModel):
         if self.uid is None:
             raise AttributeError("Cannot delete data without a valid ID.")
 
-        self.client.workspaces.delete_api_key(
-            uid=self.workspace_id, api_key_id=self.uid
+        self.client.workspaces.delete_service_account(
+            uid=self.workspace_id, service_account_id=self.uid
         )
         self.uid = None
 
-    def regenerate(self):
-        """Regenerates this API key. WARNING: Previous key will be invalidated."""
+    def regenerate(self) -> str:
+        """Regenerates this service account's key. WARNING: the previous key will be invalidated."""
 
-        _, key = self.client.workspaces.regenerate_api_key(
-            uid=self.workspace_id, api_key_id=self.uid
+        _, key = self.client.workspaces.regenerate_service_account_key(
+            uid=self.workspace_id, service_account_id=self.uid
         )
 
         return key