hydroserverpy 1.5.1__py3-none-any.whl

hydroserverpy/api/models/iam/workspace.py

@@ -0,0 +1,297 @@
+from typing import List, Union, Optional, ClassVar, TYPE_CHECKING
+from uuid import UUID
+from datetime import datetime
+from pydantic import Field, EmailStr, AliasPath
+from ..base import HydroServerBaseModel
+
+if TYPE_CHECKING:
+    from hydroserverpy import HydroServer
+    from hydroserverpy.api.models import (
+        Role,
+        Collaborator,
+        APIKey,
+        Account,
+        Thing,
+        ObservedProperty,
+        Sensor,
+        Unit,
+        ProcessingLevel,
+        ResultQualifier,
+        Datastream,
+        OrchestrationSystem,
+        DataSource,
+        DataArchive,
+    )
+
+
+class Workspace(HydroServerBaseModel):
+    name: str = Field(..., max_length=255)
+    is_private: bool
+    owner: "Account"
+    collaborator_role_id: Optional[Union[UUID, str]] = Field(
+        None, validation_alias=AliasPath("collaboratorRole", "id")
+    )
+    pending_transfer_to: Optional["Account"] = None
+
+    _editable_fields: ClassVar[set[str]] = {"name", "is_private"}
+
+    def __init__(self, client: "HydroServer", **data):
+        super().__init__(client=client, service=client.workspaces, **data)
+
+        self._roles = None
+        self._collaborators = None
+        self._collaborator_role = None
+        self._apikeys = None
+        self._things = None
+        self._observedproperties = None
+        self._processinglevels = None
+        self._resultqualifiers = None
+        self._units = None
+        self._sensors = None
+        self._datastreams = None
+        self._orchestrationsystems = None
+        self._datasources = None
+        self._dataarchives = None
+
+    @classmethod
+    def get_route(cls):
+        return "workspaces"
+
+    @property
+    def roles(self) -> List["Role"]:
+        """The roles that can be assigned for this workspace."""
+
+        if self._roles is None:
+            self._roles = self.client.roles.list(workspace=self.uid, fetch_all=True).items
+
+        return self._roles
+
+    @property
+    def collaborators(self) -> List["Collaborator"]:
+        """The collaborators associated with this workspace."""
+
+        if self._collaborators is None:
+            self._collaborators = self.client.workspaces.list_collaborators(uid=self.uid)
+
+        return self._collaborators
+
+    @property
+    def collaborator_role(self) -> Optional["Role"]:
+        """The user's collaborator role on this workspace."""
+
+        if self._collaborator_role is None and self.collaborator_role_id is not None:
+            self._collaborator_role = self.client.roles.get(uid=self.collaborator_role_id)
+
+        return self._collaborator_role
+
+    @property
+    def apikeys(self) -> List["APIKey"]:
+        """The API keys associated with this workspace."""
+
+        if self._apikeys is None:
+            self._apikeys = self.client.workspaces.list_api_keys(uid=self.uid)
+
+        return self._apikeys
+
+    @property
+    def things(self) -> List["Thing"]:
+        """The things associated with this workspace."""
+
+        if self._things is None:
+            self._things = self.client.things.list(workspace=self.uid, fetch_all=True).items
+
+        return self._things
+
+    @property
+    def observedproperties(self) -> List["ObservedProperty"]:
+        """The observed properties associated with this workspace."""
+
+        if self._observedproperties is None:
+            self._observedproperties = self.client.observedproperties.list(workspace=self.uid, fetch_all=True).items
+
+        return self._observedproperties
+
+    @property
+    def processinglevels(self) -> List["ProcessingLevel"]:
+        """The processing levels associated with this workspace."""
+
+        if self._processinglevels is None:
+            self._processinglevels = self.client.processinglevels.list(workspace=self.uid, fetch_all=True).items
+
+        return self._processinglevels
+
+    @property
+    def resultqualifiers(self) -> List["ResultQualifier"]:
+        """The result qualifiers associated with this workspace."""
+
+        if self._resultqualifiers is None:
+            self._resultqualifiers = self.client.resultqualifiers.list(workspace=self.uid, fetch_all=True).items
+
+        return self._resultqualifiers
+
+    @property
+    def units(self) -> List["Unit"]:
+        """The units associated with this workspace."""
+
+        if self._units is None:
+            self._units = self.client.units.list(workspace=self.uid, fetch_all=True).items
+
+        return self._units
+
+    @property
+    def sensors(self) -> List["Sensor"]:
+        """The sensors associated with this workspace."""
+
+        if self._sensors is None:
+            self._sensors = self.client.sensors.list(workspace=self.uid, fetch_all=True).items
+
+        return self._sensors
+
+    @property
+    def datastreams(self) -> List["Datastream"]:
+        """The datastreams associated with this workspace."""
+
+        if self._datastreams is None:
+            self._datastreams = self.client.datastreams.list(workspace=self.uid, fetch_all=True).items
+
+        return self._datastreams
+
+    @property
+    def orchestrationsystems(self) -> List["OrchestrationSystem"]:
+        """The orchestration systems associated with this workspace."""
+
+        if self._orchestrationsystems is None:
+            self._orchestrationsystems = self.client.orchestrationsystems.list(workspace=self.uid, fetch_all=True).items
+
+        return self._orchestrationsystems
+
+    @property
+    def datasources(self) -> List["DataSource"]:
+        """The data sources associated with this workspace."""
+
+        if self._datasources is None:
+            self._datasources = self.client.datasources.list(workspace=self.uid, fetch_all=True).items
+
+        return self._datasources
+
+    @property
+    def dataarchives(self) -> List["DataArchive"]:
+        """The data archives associated with this workspace."""
+
+        if self._dataarchives is None:
+            self._dataarchives = self.client.dataarchives.list(workspace=self.uid, fetch_all=True).items
+
+        return self._dataarchives
+
+    def create_api_key(
+        self,
+        role: Union["Role", UUID, str],
+        name: str,
+        description: Optional[str] = None,
+        is_active: bool = True,
+        expires_at: Optional[datetime] = None
+    ):
+        """Create an API key associated with this workspace."""
+
+        response, key = self.client.workspaces.create_api_key(
+            uid=self.uid,
+            role=role,
+            name=name,
+            description=description,
+            is_active=is_active,
+            expires_at=expires_at
+        )
+        self._apikeys = None
+
+        return response, key
+
+    def update_api_key(
+        self,
+        api_key_id: Union[UUID, str],
+        role: Union["Role", UUID, str] = ...,
+        name: str = ...,
+        description: Optional[str] = ...,
+        is_active: bool = ...,
+        expires_at: Optional[datetime] = ...
+    ):
+        """Create an API key associated with this workspace."""
+
+        response = self.client.workspaces.update_api_key(
+            uid=self.uid,
+            api_key_id=api_key_id,
+            role=role,
+            name=name,
+            description=description,
+            is_active=is_active,
+            expires_at=expires_at
+        )
+        self._apikeys = None
+
+        return response
+
+    def delete_api_key(self, api_key_id: Union[UUID, str]):
+        """Delete an API key associated with this workspace."""
+
+        self.client.workspaces.delete_api_key(
+            uid=self.uid,
+            api_key_id=api_key_id
+        )
+        self._apikeys = None
+
+    def regenerate_api_key(self, api_key_id: Union[UUID, str]):
+        """Regenerate an API key associated with this workspace."""
+
+        api_key, key = self.client.workspaces.regenerate_api_key(
+            uid=self.uid,
+            api_key_id=api_key_id
+        )
+
+        return api_key, key
+
+    def add_collaborator(
+        self, email: EmailStr, role: Union["Role", UUID, str]
+    ) -> "Collaborator":
+        """Add a new collaborator to the workspace."""
+
+        response = self.client.workspaces.add_collaborator(
+            uid=self.uid, email=email, role=role
+        )
+        self._collaborators = None
+
+        return response
+
+    def edit_collaborator_role(
+        self, email: EmailStr, role: Union["Role", UUID, str]
+    ) -> "Collaborator":
+        """Edit a collaborator's role in this workspace."""
+
+        response = self.client.workspaces.edit_collaborator_role(
+            uid=self.uid, email=email, role=role
+        )
+        self._collaborators = None
+
+        return response
+
+    def remove_collaborator(self, email: EmailStr) -> None:
+        """Remove a collaborator from the workspace."""
+
+        self.client.workspaces.remove_collaborator(uid=self.uid, email=email)
+        self._collaborators = None
+
+    def transfer_ownership(self, email: EmailStr) -> None:
+        """Transfer ownership of this workspace to another HydroServer user."""
+
+        self.client.workspaces.transfer_ownership(uid=self.uid, email=email)
+        self.refresh()
+
+    def accept_ownership_transfer(self) -> None:
+        """Accept ownership transfer of this workspace."""
+
+        self.client.workspaces.accept_ownership_transfer(uid=self.uid)
+        self.refresh()
+
+    def cancel_ownership_transfer(self) -> None:
+        """Cancel ownership transfer of this workspace."""
+
+        self.client.workspaces.cancel_ownership_transfer(uid=self.uid)
+        self.refresh()

hydroserverpy/api/models/sta/datastream.py

@@ -0,0 +1,254 @@
+import uuid
+import pandas as pd
+from typing import List, Union, Optional, Literal, ClassVar, TYPE_CHECKING
+from pydantic import Field
+from uuid import UUID
+from datetime import datetime
+from hydroserverpy.api.utils import normalize_uuid
+from ..base import HydroServerBaseModel
+
+if TYPE_CHECKING:
+    from hydroserverpy import HydroServer
+    from hydroserverpy.api.models import (
+        Workspace,
+        Thing,
+        Sensor,
+        ObservedProperty,
+        Unit,
+        ProcessingLevel,
+        DataSource,
+        DataArchive
+    )
+
+
+class Datastream(HydroServerBaseModel):
+    name: str = Field(..., max_length=255)
+    description: str
+    observation_type: str = Field(..., max_length=255)
+    sampled_medium: str = Field(..., max_length=255)
+    no_data_value: float
+    aggregation_statistic: str = Field(..., max_length=255)
+    time_aggregation_interval: float
+    status: Optional[str] = Field(None, max_length=255)
+    result_type: str = Field(..., max_length=255)
+    value_count: Optional[int] = Field(None, ge=0)
+    phenomenon_begin_time: Optional[datetime] = None
+    phenomenon_end_time: Optional[datetime] = None
+    result_begin_time: Optional[datetime] = None
+    result_end_time: Optional[datetime] = None
+    is_private: bool = False
+    is_visible: bool = True
+    time_aggregation_interval_unit: Literal["seconds", "minutes", "hours", "days"]
+    intended_time_spacing: Optional[float] = None
+    intended_time_spacing_unit: Optional[
+        Literal["seconds", "minutes", "hours", "days"]
+    ] = None
+    data_source_id: Optional[uuid.UUID] = None
+    thing_id: uuid.UUID
+    workspace_id: uuid.UUID
+    sensor_id: uuid.UUID
+    observed_property_id: uuid.UUID
+    processing_level_id: uuid.UUID
+    unit_id: uuid.UUID
+
+    _editable_fields: ClassVar[set[str]] = {
+        "name", "description", "observation_type", "sampled_medium", "no_data_value", "aggregation_statistic",
+        "time_aggregation_interval", "status", "result_type", "value_count", "phenomenon_begin_time",
+        "phenomenon_end_time", "result_begin_time", "result_end_time", "is_private", "is_visible",
+        "time_aggregation_interval_unit", "intended_time_spacing", "intended_time_spacing_unit", "thing_id",
+        "sensor_id", "observed_property_id", "processing_level_id", "unit_id"
+    }
+
+    def __init__(self, client: "HydroServer", **data):
+        super().__init__(client=client, service=client.datastreams, **data)
+
+        self._workspace = None
+        self._thing = None
+        self._observed_property = None
+        self._unit = None
+        self._processing_level = None
+        self._sensor = None
+        self._data_source = None
+        self._data_archives = None
+
+    @classmethod
+    def get_route(cls):
+        return "datastreams"
+
+    @property
+    def workspace(self) -> "Workspace":
+        """The workspace this datastream belongs to."""
+
+        if self._workspace is None:
+            self._workspace = self.client.workspaces.get(uid=self.workspace_id)
+
+        return self._workspace
+
+    @property
+    def thing(self) -> "Thing":
+        """The thing this datastream belongs to."""
+
+        if self._thing is None:
+            self._thing = self.client.things.get(uid=self.thing_id)
+
+        return self._thing
+
+    @thing.setter
+    def thing(self, thing: Union["Thing", UUID, str] = ...):
+        if not thing:
+            raise ValueError("Thing of datastream cannot be None.")
+        if normalize_uuid(thing) != str(self.thing_id):
+            self.thing_id = normalize_uuid(thing)
+            self._thing = None
+
+    @property
+    def sensor(self) -> "Sensor":
+        """The sensor of this datastream."""
+
+        if self._sensor is None:
+            self._sensor = self.client.sensors.get(uid=self.sensor_id)
+
+        return self._sensor
+
+    @sensor.setter
+    def sensor(self, sensor: Union["Sensor", UUID, str] = ...):
+        if not sensor:
+            raise ValueError("Sensor of datastream cannot be None.")
+        if normalize_uuid(sensor) != str(self.sensor_id):
+            self.sensor_id = normalize_uuid(sensor)
+            self._sensor = None
+
+    @property
+    def observed_property(self) -> "ObservedProperty":
+        """The observed property of this datastream."""
+
+        if self._observed_property is None:
+            self._observed_property = self.client.observedproperties.get(uid=self.observed_property_id)
+
+        return self._observed_property
+
+    @observed_property.setter
+    def observed_property(self, observed_property: Union["ObservedProperty", UUID, str] = ...):
+        if not observed_property:
+            raise ValueError("Observed property of datastream cannot be None.")
+        if normalize_uuid(observed_property) != str(self.observed_property_id):
+            self.observed_property_id = normalize_uuid(observed_property)
+            self._observed_property = None
+
+    @property
+    def unit(self) -> "Unit":
+        """The unit of this datastream."""
+
+        if self._unit is None:
+            self._unit = self.client.units.get(uid=self.unit_id)
+
+        return self._unit
+
+    @unit.setter
+    def unit(self, unit: Union["Unit", UUID, str] = ...):
+        if not unit:
+            raise ValueError("Unit of datastream cannot be None.")
+        if normalize_uuid(unit) != str(self.unit_id):
+            self.unit_id = normalize_uuid(unit)
+            self._unit = None
+
+    @property
+    def processing_level(self) -> "ProcessingLevel":
+        """The processing level of this datastream."""
+
+        if self._processing_level is None:
+            self._processing_level = self.client.processinglevels.get(uid=self.processing_level_id)
+
+        return self._processing_level
+
+    @processing_level.setter
+    def processing_level(self, processing_level: Union["ProcessingLevel", UUID, str] = ...):
+        if not processing_level:
+            raise ValueError("Processing level of datastream cannot be None.")
+        if normalize_uuid(processing_level) != str(self.processing_level_id):
+            self.processing_level_id = normalize_uuid(processing_level)
+            self._processing_level = None
+
+    @property
+    def data_source(self) -> Optional["DataSource"]:
+        """The data source of this datastream."""
+
+        if self._data_source is None and self.data_source_id is not None:
+            self._data_source = self.client.datasources.get(uid=self.data_source_id)
+
+        return self._data_source
+
+    @property
+    def data_archives(self) -> List["DataArchive"]:
+        """The data archives of this datastream."""
+
+        if self._data_archives is None:
+            self._data_archives = self.client.dataarchives.list(datastream=self.uid, fetch_all=True).items
+
+        return self._data_archives
+
+    def get_observations(
+        self,
+        page: int = ...,
+        page_size: int = 100000,
+        order_by: List[str] = ...,
+        phenomenon_time_max: datetime = ...,
+        phenomenon_time_min: datetime = ...,
+        result_qualifier_code: str = ...,
+        fetch_all: bool = False,
+    ) -> pd.DataFrame:
+        """Retrieve the observations for this datastream."""
+
+        return self.client.datastreams.get_observations(
+            uid=self.uid,
+            page=page,
+            page_size=page_size,
+            order_by=order_by,
+            phenomenon_time_max=phenomenon_time_max,
+            phenomenon_time_min=phenomenon_time_min,
+            result_qualifier_code=result_qualifier_code,
+            fetch_all=fetch_all
+        )
+
+    def load_observations(
+        self,
+        observations: pd.DataFrame,
+        mode: str = "insert"
+    ) -> None:
+        """Load a DataFrame of observations to the datastream."""
+
+        return self.client.datastreams.load_observations(
+            uid=self.uid,
+            observations=observations,
+            mode=mode
+        )
+
+    def delete_observations(
+        self,
+        phenomenon_time_start: Optional[datetime] = None,
+        phenomenon_time_end: Optional[datetime] = None,
+    ):
+        """Delete the observations for this datastream."""
+
+        return self.client.datastreams.delete_observations(
+            uid=self.uid,
+            phenomenon_time_start=phenomenon_time_start,
+            phenomenon_time_end=phenomenon_time_end,
+        )
+
+    # TODO: Find a better long-term solution for this issue.
+    def sync_phenomenon_end_time(self):
+        """Ensures the phenomenon_end_time field matches the actual end time of the observations."""
+
+        path = f"/{self.client.base_route}/{self.get_route()}/{str(self.uid)}/observations"
+        response = self.client.request(
+            "get", path, params={"page_size": 1, "order_by": "-phenomenonTime"}
+
+        ).json()
+
+        if len(response) > 0:
+            self.phenomenon_end_time = datetime.fromisoformat(response[0]["phenomenonTime"])
+        else:
+            self.phenomenon_end_time = None
+
+        self.save()

hydroserverpy/api/models/sta/observation.py

@@ -0,0 +1,103 @@
+import pandas as pd
+from typing import Optional, Any, List, TYPE_CHECKING
+from dataclasses import dataclass
+from requests import Response
+from pydantic.alias_generators import to_snake
+
+if TYPE_CHECKING:
+    from hydroserverpy.api.models import Datastream
+
+
+@dataclass
+class ObservationCollection:
+    dataframe: pd.DataFrame
+    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
+    total_count: Optional[int] = None
+
+    def __init__(
+        self,
+        datastream: "Datastream",
+        response: Optional[Response] = None,
+        **data
+    ):
+        self.filters = data.get("filters")
+        self.order_by = data.get("order_by")
+        self.page = data.get("page") or (int(response.headers.get("X-Page")) if response else None)
+        self.page_size = data.get("page_size") or (int(response.headers.get("X-Page-Size")) if response else None)
+        self.total_pages = data.get("total_pages") or (int(response.headers.get("X-Total-Pages")) if response else None)
+        self.total_count = data.get("total_count") or (int(response.headers.get("X-Total-Count")) if response else None)
+        self.datastream = datastream
+
+        if "dataframe" in data:
+            self.dataframe = data["dataframe"]
+        elif response is not None:
+            data = response.json()
+            self.dataframe = pd.DataFrame({to_snake(k): v for k, v in data.items()})
+            if "phenomenon_time" in self.dataframe.columns:
+                self.dataframe["phenomenon_time"] = pd.to_datetime(
+                    self.dataframe["phenomenon_time"], utc=True, format="ISO8601"
+                )
+        else:
+            self.dataframe = pd.DataFrame()
+
+    def next_page(self):
+        """Fetches the next page of data from HydroServer."""
+
+        return self.datastream.get_observations(
+            **(self.filters or {}),
+            page=(self.page or 0) + 1,
+            page_size=self.page_size or 100000,
+            order_by=self.order_by or ...,
+        )
+
+    def previous_page(self):
+        """Fetches the previous page of data from HydroServer."""
+
+        if not self.page or self.page <= 1:
+            return None
+
+        return self.datastream.get_observations(
+            **(self.filters or {}),
+            page=self.page - 1,
+            page_size=self.page_size or 100000,
+            order_by=self.order_by or ...,
+        )
+
+    def fetch_all(self) -> "ObservationCollection":
+        """Fetches all pages of data from HydroServer for this collection."""
+
+        all_dataframes = []
+        page_num = 1
+
+        while self.total_pages is None or page_num <= self.total_pages:
+            if page_num == self.page:
+                all_dataframes.append(self.dataframe)
+            else:
+                observations = self.datastream.get_observations(
+                    **(self.filters or {}),
+                    page=page_num,
+                    page_size=self.page_size or 100000,
+                    order_by=self.order_by or ...,
+                )
+                if observations.dataframe.empty:
+                    break
+                all_dataframes.append(observations.dataframe)
+
+            page_num += 1
+
+        merged_dataframe = pd.concat(all_dataframes, ignore_index=True)
+
+        return self.__class__(
+            dataframe=merged_dataframe,
+            datastream=self.datastream,
+            filters=self.filters,
+            order_by=self.order_by or ...,
+            page=1,
+            page_size=len(merged_dataframe),
+            total_pages=1,
+            total_count=len(merged_dataframe)
+        )

hydroserverpy/api/models/sta/observed_property.py

@@ -0,0 +1,37 @@
+import uuid
+from typing import Optional, ClassVar, TYPE_CHECKING
+from pydantic import Field
+from ..base import HydroServerBaseModel
+
+if TYPE_CHECKING:
+    from hydroserverpy import HydroServer
+    from hydroserverpy.api.models import Workspace
+
+
+class ObservedProperty(HydroServerBaseModel):
+    name: str = Field(..., max_length=255)
+    definition: str
+    description: str
+    observed_property_type: str = Field(..., max_length=255, alias="type")
+    code: str = Field(..., max_length=255)
+    workspace_id: Optional[uuid.UUID] = None
+
+    _editable_fields: ClassVar[set[str]] = {"name", "definition", "description", "observed_property_type", "code"}
+
+    def __init__(self, client: "HydroServer", **data):
+        super().__init__(client=client, service=client.observedproperties, **data)
+
+        self._workspace = None
+
+    @classmethod
+    def get_route(cls):
+        return "observed-properties"
+
+    @property
+    def workspace(self) -> Optional["Workspace"]:
+        """The workspace this observed property belongs to."""
+
+        if self._workspace is None and self.workspace_id:
+            self._workspace = self.client.workspaces.get(uid=self.workspace_id)
+
+        return self._workspace