hydroserverpy 0.4.0__py3-none-any.whl → 0.5.0b1__py3-none-any.whl

hydroserverpy/__init__.py

@@ -1,7 +1,6 @@
-from .core.service import HydroServer
-from .quality.service import HydroServerQualityControl
+from .api.main import HydroServer
 from .etl.hydroserver_etl import HydroServerETL
-
+from .quality import HydroServerQualityControl
 
 __all__ = [
     "HydroServer",

hydroserverpy/api/http.py

@@ -0,0 +1,24 @@
+import json
+from requests import HTTPError
+
+
+def raise_for_hs_status(response):
+    """"""
+
+    try:
+        response.raise_for_status()
+    except HTTPError as e:
+        try:
+            http_error_msg = (
+                f"{response.status_code} Client Error: "
+                f"{str(json.loads(response.content).get('detail'))}"
+            )
+        except (
+            ValueError,
+            TypeError,
+        ):
+            http_error_msg = e
+        if 400 <= response.status_code < 500:
+            raise HTTPError(http_error_msg, response=response)
+        else:
+            raise HTTPError(str(e), response=response)

hydroserverpy/api/main.py

@@ -0,0 +1,152 @@
+import requests
+from typing import Optional, Tuple
+from hydroserverpy.api.http import raise_for_hs_status
+from hydroserverpy.api.services import (
+    WorkspaceService,
+    ThingService,
+    ObservedPropertyService,
+    UnitService,
+    ProcessingLevelService,
+    ResultQualifierService,
+    SensorService,
+    DatastreamService,
+)
+
+
+class HydroServer:
+    def __init__(
+        self,
+        host: str,
+        email: Optional[str] = None,
+        password: Optional[str] = None,
+        apikey: Optional[str] = None,
+    ):
+        self.host = host.strip("/")
+        self.auth = (
+            (
+                email or "__key__",
+                password or apikey,
+            )
+            if (email and password) or apikey
+            else None
+        )
+
+        self._auth_url = f"{self.host}/api/auth/app/session"
+
+        self._session = None
+        self._timeout = 60
+        self._auth_header = None
+
+        self._init_session()
+
+    def login(self, email: str, password: str) -> None:
+        """Provide your HydroServer credentials to log in to your account."""
+
+        self._init_session(auth=(email, password))
+
+    def logout(self) -> None:
+        """End your HydroServer session."""
+
+        self._session.delete(self._auth_url, timeout=self._timeout)
+
+    def _init_session(self, auth: Optional[Tuple[str, str]] = None) -> None:
+        if self._session is not None:
+            self.logout()
+            self._session.close()
+
+        self._session = requests.Session()
+
+        auth = auth or self.auth
+
+        if auth and auth[0] == "__key__":
+            self._session.headers.update({"key": auth[1]})
+        elif auth:
+            self._session.headers.update(
+                {"Authorization": f"Bearer {self._authenticate(auth[0], auth[1])}"}
+            )
+
+    def _authenticate(self, email: str, password: str) -> None:
+        response = self._session.post(
+            self._auth_url,
+            json={"email": email, "password": password},
+            timeout=self._timeout,
+        )
+        response.raise_for_status()
+        session_token = response.json().get("meta", {}).get("session_token")
+
+        if not session_token:
+            raise ValueError("Authentication failed: No access token returned.")
+
+        return session_token
+
+    def request(self, method, path, *args, **kwargs) -> requests.Response:
+        """Sends a request to HydroServer's API."""
+
+        for attempt in range(2):
+            try:
+                response = getattr(self._session, method)(
+                    f"{self.host}/{path.strip('/')}",
+                    timeout=self._timeout,
+                    *args,
+                    **kwargs,
+                )
+                raise_for_hs_status(response)
+            except (
+                requests.exceptions.HTTPError,
+                requests.exceptions.ConnectionError,
+            ) as e:
+                if attempt == 0:
+                    self._init_session()
+                    continue
+                else:
+                    raise e
+
+            return response
+
+    @property
+    def workspaces(self):
+        """Utilities for managing HydroServer workspaces."""
+
+        return WorkspaceService(self)
+
+    @property
+    def things(self):
+        """Utilities for managing HydroServer things."""
+
+        return ThingService(self)
+
+    @property
+    def observedproperties(self):
+        """Utilities for managing HydroServer observed properties."""
+
+        return ObservedPropertyService(self)
+
+    @property
+    def units(self):
+        """Utilities for managing HydroServer units."""
+
+        return UnitService(self)
+
+    @property
+    def processinglevels(self):
+        """Utilities for managing HydroServer processing levels."""
+
+        return ProcessingLevelService(self)
+
+    @property
+    def resultqualifiers(self):
+        """Utilities for managing HydroServer result qualifiers."""
+
+        return ResultQualifierService(self)
+
+    @property
+    def sensors(self):
+        """Utilities for managing HydroServer sensors."""
+
+        return SensorService(self)
+
+    @property
+    def datastreams(self):
+        """Utilities for managing HydroServer datastreams."""
+
+        return DatastreamService(self)

hydroserverpy/api/models/__init__.py

@@ -0,0 +1,18 @@
+from .iam.account import Account
+from .iam.workspace import Workspace
+from .iam.role import Role
+from .iam.collaborator import Collaborator
+from .iam.account import Account
+from .sta.datastream import Datastream
+from .sta.observed_property import ObservedProperty
+from .sta.processing_level import ProcessingLevel
+from .sta.result_qualifier import ResultQualifier
+from .sta.sensor import Sensor
+from .sta.thing import Thing
+from .sta.unit import Unit
+
+Workspace.model_rebuild()
+Role.model_rebuild()
+Collaborator.model_rebuild()
+
+Unit.model_rebuild()

hydroserverpy/api/models/base.py

@@ -0,0 +1,74 @@
+from typing import Optional
+from uuid import UUID
+from pydantic import BaseModel, PrivateAttr, ConfigDict, computed_field
+from pydantic.alias_generators import to_camel
+
+
+class HydroServerBaseModel(BaseModel):
+    _uid: Optional[UUID] = PrivateAttr()
+
+    def __init__(self, _uid: Optional[UUID] = None, **data):
+        super().__init__(**data)
+        self._uid = _uid
+
+    @computed_field
+    @property
+    def uid(self) -> Optional[UUID]:
+        """The unique identifier for this resource."""
+
+        return self._uid
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+        populate_by_name=True,
+        str_strip_whitespace=True,
+        alias_generator=to_camel,
+    )
+
+
+class HydroServerModel(HydroServerBaseModel):
+    _model_ref: str = PrivateAttr()
+    _original_data: Optional[dict] = PrivateAttr()
+
+    def __init__(self, _connection, _model_ref, _uid: Optional[UUID] = None, **data):
+        if isinstance(_uid, str):
+            _uid = UUID(_uid)
+
+        super().__init__(_uid=_uid, **data)
+
+        self._connection = _connection
+        self._model_ref = _model_ref
+        self._original_data = self.dict(by_alias=False).copy()
+
+    @property
+    def _patch_data(self) -> dict:
+        return {
+            key: getattr(self, key)
+            for key, value in self._original_data.items()
+            if hasattr(self, key) and getattr(self, key) != value
+        }
+
+    def _refresh(self) -> None:
+        """Refresh this resource from HydroServer."""
+
+        self._original_data = (
+            getattr(self._connection, self._model_ref)
+            .get(uid=self.uid)
+            .model_dump(exclude=["uid"])
+        )
+        self.__dict__.update(self._original_data)
+
+    def _save(self) -> None:
+        if self._patch_data:
+            entity = getattr(self._connection, self._model_ref).update(
+                uid=self.uid, **self._patch_data
+            )
+            self._original_data = entity.dict(by_alias=False, exclude=["uid"])
+            self.__dict__.update(self._original_data)
+
+    def _delete(self) -> None:
+        if not self._uid:
+            raise AttributeError("This resource cannot be deleted: UID is not set.")
+
+        getattr(self._connection, self._model_ref).delete(uid=self._uid)
+        self._uid = None

hydroserverpy/api/models/iam/account.py

@@ -0,0 +1,12 @@
+from typing import Optional
+from pydantic import BaseModel, Field, EmailStr
+
+
+class Account(BaseModel):
+    name: str = Field(..., max_length=255)
+    email: EmailStr
+    organization_name: Optional[str] = None
+    phone: Optional[str] = Field(None, max_length=15)
+    address: Optional[str] = Field(None, max_length=255)
+    link: Optional[str] = Field(None, max_length=2000)
+    user_type: str = Field(..., max_length=255, alias="type")

hydroserverpy/api/models/iam/collaborator.py

@@ -0,0 +1,34 @@
+from typing import Union, TYPE_CHECKING
+from uuid import UUID
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from hydroserverpy.api.models.iam.account import Account
+    from hydroserverpy.api.models.iam.role import Role
+
+
+class CollaboratorFields(BaseModel):
+    user: "Account"
+    role: "Role"
+    workspace_id: Union[UUID, str]
+
+
+class Collaborator(CollaboratorFields):
+    def __init__(self, _connection, **data):
+        super().__init__(**data)
+        self._connection = _connection
+
+    def edit_role(self, role: Union["Role", UUID, str]):
+        """Edit the role of this workspace collaborator."""
+
+        response = self._connection.workspaces.edit_collaborator_role(
+            uid=self.workspace_id, email=self.user.email, role=role
+        )
+        self.role = response.role
+
+    def remove(self):
+        """Remove this collaborator from the workspace."""
+
+        self._connection.workspaces.remove_collaborator(
+            uid=self.workspace_id, email=self.user.email
+        )

hydroserverpy/api/models/iam/role.py

@@ -0,0 +1,10 @@
+from typing import Optional, Union
+from uuid import UUID
+from pydantic import BaseModel, Field
+
+
+class Role(BaseModel):
+    uid: UUID = Field(..., alias="id")
+    name: str = Field(..., max_length=255)
+    description: str
+    workspace_id: Optional[Union[UUID, str]] = None

hydroserverpy/api/models/iam/workspace.py

@@ -0,0 +1,203 @@
+from typing import List, Union, Optional, TYPE_CHECKING
+from uuid import UUID
+from pydantic import BaseModel, Field, EmailStr
+from ..base import HydroServerModel
+
+if TYPE_CHECKING:
+    from hydroserverpy import HydroServer
+    from hydroserverpy.api.models import (
+        Role,
+        Collaborator,
+        Account,
+        Thing,
+        ObservedProperty,
+        Sensor,
+        Unit,
+        ProcessingLevel,
+        ResultQualifier,
+        Datastream,
+    )
+
+
+class WorkspaceFields(BaseModel):
+    name: str = Field(..., max_length=255)
+    is_private: bool
+    owner: "Account" = Field(..., json_schema_extra={"read_only": True})
+    collaborator_role: Optional["Role"] = None
+    pending_transfer_to: Optional["Account"] = None
+
+
+class Workspace(HydroServerModel, WorkspaceFields):
+    def __init__(self, _connection: "HydroServer", _uid: Union[UUID, str], **data):
+        super().__init__(
+            _connection=_connection, _model_ref="workspaces", _uid=_uid, **data
+        )
+        self._roles = None
+        self._collaborators = None
+        self._things = None
+        self._observedproperties = None
+        self._processinglevels = None
+        self._resultqualifiers = None
+        self._units = None
+        self._sensors = None
+        self._datastreams = None
+
+    @property
+    def roles(self) -> List["Role"]:
+        """The roles that can be assigned for this workspace."""
+
+        if self._roles is None:
+            self._roles = self._connection.workspaces.list_roles(uid=self.uid)
+
+        return self._roles
+
+    @property
+    def collaborators(self) -> List["Collaborator"]:
+        """The collaborators associated with this workspace."""
+
+        if self._collaborators is None:
+            self._collaborators = self._connection.workspaces.list_collaborators(
+                uid=self.uid
+            )
+
+        return self._collaborators
+
+    @property
+    def things(self) -> List["Thing"]:
+        """The things associated with this workspace."""
+
+        if self._things is None:
+            self._things = self._connection.things.list(workspace=self.uid)
+
+        return self._things
+
+    @property
+    def observedproperties(self) -> List["ObservedProperty"]:
+        """The observed properties associated with this workspace."""
+
+        if self._observedproperties is None:
+            self._observedproperties = self._connection.observedproperties.list(
+                workspace=self.uid
+            )
+
+        return self._observedproperties
+
+    @property
+    def processinglevels(self) -> List["ProcessingLevel"]:
+        """The processing levels associated with this workspace."""
+
+        if self._processinglevels is None:
+            self._processinglevels = self._connection.processinglevels.list(
+                workspace=self.uid
+            )
+
+        return self._processinglevels
+
+    @property
+    def resultqualifiers(self) -> List["ResultQualifier"]:
+        """The result qualifiers associated with this workspace."""
+
+        if self._resultqualifiers is None:
+            self._resultqualifiers = self._connection.resultqualifiers.list(
+                workspace=self.uid
+            )
+
+        return self._resultqualifiers
+
+    @property
+    def units(self) -> List["Unit"]:
+        """The units associated with this workspace."""
+
+        if self._units is None:
+            self._units = self._connection.units.list(workspace=self.uid)
+
+        return self._units
+
+    @property
+    def sensors(self) -> List["Sensor"]:
+        """The sensors associated with this workspace."""
+
+        if self._sensors is None:
+            self._sensors = self._connection.sensors.list(workspace=self.uid)
+
+        return self._sensors
+
+    @property
+    def datastreams(self) -> List["Datastream"]:
+        """The datastreams associated with this workspace."""
+
+        if self._datastreams is None:
+            self._datastreams = self._connection.datastreams.list(workspace=self.uid)
+
+        return self._datastreams
+
+    def refresh(self) -> None:
+        """Refresh the workspace details from HydroServer."""
+
+        self._roles = None
+        self._collaborators = None
+        self._things = None
+        self._observedproperties = None
+        self._processinglevels = None
+        self._units = None
+        self._sensors = None
+        self._datastreams = None
+        super()._refresh()
+
+    def save(self):
+        """Save changes to this workspace to HydroServer."""
+
+        super()._save()
+
+    def delete(self):
+        """Delete this workspace from HydroServer."""
+
+        super()._delete()
+
+    def add_collaborator(
+        self, email: EmailStr, role: Union["Role", UUID, str]
+    ) -> "Collaborator":
+        """Add a new collaborator to the workspace."""
+
+        response = self._connection.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._connection.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._connection.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._connection.workspaces.transfer_ownership(uid=self.uid, email=email)
+        self.refresh()
+
+    def accept_ownership_transfer(self) -> None:
+        """Accept ownership transfer of this workspace."""
+
+        self._connection.workspaces.accept_ownership_transfer(uid=self.uid)
+        self.refresh()
+
+    def cancel_ownership_transfer(self) -> None:
+        """Cancel ownership transfer of this workspace."""
+
+        self._connection.workspaces.cancel_ownership_transfer(uid=self.uid)
+        self.refresh()