hydroserverpy 0.2.5__py3-none-any.whl → 0.4.0__py3-none-any.whl

hydroserverpy/core/endpoints/units.py

@@ -0,0 +1,111 @@
+from typing import List, Union, TYPE_CHECKING
+from uuid import UUID
+from hydroserverpy.core.endpoints.base import HydroServerEndpoint, expand_docstring
+from hydroserverpy.core.schemas import Unit
+
+if TYPE_CHECKING:
+    from hydroserverpy.core.service import HydroServer
+
+
+class UnitEndpoint(HydroServerEndpoint):
+    """
+    An endpoint for interacting with unit entities in the HydroServer service.
+
+    :ivar _model: The model class associated with this endpoint, set to `Unit`.
+    :ivar _api_route: The base route of the API, derived from the service.
+    :ivar _endpoint_route: The specific route of the endpoint, set to `'units'`.
+    """
+
+    def __init__(self, service: "HydroServer"):
+        """
+        Initialize the UnitEndpoint.
+
+        :param service: The HydroServer service instance to use for requests.
+        :type service: HydroServer
+        """
+
+        super().__init__(service)
+        self._model = Unit
+        self._api_route = self._service.api_route
+        self._endpoint_route = "units"
+
+    def list(
+        self,
+        include_owned: bool = True,
+        include_unowned: bool = True,
+        include_templates: bool = True,
+    ) -> List[Unit]:
+        """
+        Retrieve a collection of units.
+
+        :param include_owned: Whether to include owned observed properties.
+        :param include_unowned: Whether to include unowned observed properties.
+        :param include_templates: Whether to include template observed properties.
+        """
+
+        if (
+            include_owned is True
+            and include_unowned is True
+            and include_templates is True
+        ):
+            owner = "anyUserOrNoUser"
+        elif (
+            include_owned is True
+            and include_unowned is True
+            and include_templates is False
+        ):
+            owner = "anyUser"
+        elif (
+            include_owned is True
+            and include_unowned is False
+            and include_templates is True
+        ):
+            owner = "currentUserOrNoUser"
+        elif (
+            include_owned is True
+            and include_unowned is False
+            and include_templates is False
+        ):
+            owner = "currentUser"
+        elif (
+            include_owned is False
+            and include_unowned is False
+            and include_templates is True
+        ):
+            owner = "noUser"
+        else:
+            return []
+
+        return super()._get(params={"owner": owner})
+
+    @expand_docstring(include_uid=True)
+    def get(self, uid: Union[UUID, str]) -> Unit:
+        """
+        Retrieve a unit owned by the logged-in user.
+        """
+
+        return super()._get(uid)
+
+    @expand_docstring(model=Unit)
+    def create(self, **kwargs) -> Unit:
+        """
+        Create a new unit in HydroServer.
+        """
+
+        return super()._post(**kwargs)
+
+    @expand_docstring(model=Unit, include_uid=True)
+    def update(self, uid: Union[UUID, str], **kwargs) -> Unit:
+        """
+        Update an existing unit in HydroServer.
+        """
+
+        return super()._patch(uid=uid, **kwargs)
+
+    @expand_docstring(include_uid=True)
+    def delete(self, uid: Union[UUID, str]) -> None:
+        """
+        Delete an existing unit in HydroServer.
+        """
+
+        super()._delete(uid=uid)

hydroserverpy/{components → core/schemas}/__init__.py

@@ -5,6 +5,5 @@ from .observed_properties import ObservedProperty
 from .processing_levels import ProcessingLevel
 from .result_qualifiers import ResultQualifier
 from .sensors import Sensor
-from .things import Thing
+from .things import Thing, Tag, Photo, Archive
 from .units import Unit
-from .users import User

hydroserverpy/core/schemas/base.py

@@ -0,0 +1,124 @@
+from pydantic import (
+    BaseModel,
+    PrivateAttr,
+    AliasGenerator,
+    AliasChoices,
+    computed_field,
+)
+from pydantic.alias_generators import to_camel
+from uuid import UUID
+from typing import Optional
+
+
+base_alias_generator = AliasGenerator(
+    serialization_alias=lambda field_name: to_camel(field_name),
+    validation_alias=lambda field_name: AliasChoices(to_camel(field_name), field_name),
+)
+
+
+class HydroServerBaseModel(BaseModel):
+    """
+    A base model for HydroServer entities that provides common attributes and functionality for HydroServer data.
+
+    :ivar _uid: A private attribute for storing the unique identifier (UUID) of the model.
+    """
+
+    _uid: Optional[UUID] = PrivateAttr()
+
+    def __init__(self, _uid: Optional[UUID] = None, **data):
+        """
+        Initialize a HydroServerBaseModel instance.
+
+        :param _uid: The unique identifier for the model.
+        :type _uid: Optional[UUID]
+        :param data: Additional attributes for the model.
+        """
+
+        super().__init__(**data)
+        self._uid = _uid
+
+    @computed_field
+    @property
+    def uid(self) -> Optional[UUID]:
+        """
+        The unique identifier (UUID) of the model.
+
+        :return: The UUID of the model.
+        :rtype: Optional[UUID]
+        """
+
+        return self._uid
+
+    class Config:
+        alias_generator = base_alias_generator
+        validate_assignment = True
+
+
+class HydroServerCoreModel(HydroServerBaseModel):
+    """
+    A core model for HydroServer entities that includes methods for data manipulation and persistence.
+
+    :ivar _original_data: A private attribute storing the original data used to initialize the model.
+    """
+
+    _original_data: Optional[dict] = PrivateAttr()
+
+    def __init__(self, _endpoint, _uid: Optional[UUID] = None, **data):
+        """
+        Initialize a HydroServerCoreModel instance.
+
+        :param _endpoint: The endpoint associated with the model.
+        :param _uid: The unique identifier for the model.
+        :type _uid: Optional[UUID]
+        :param data: Additional attributes for the model.
+        """
+
+        super().__init__(_uid=_uid, **data)
+        self._endpoint = _endpoint
+        self._original_data = self.dict(by_alias=False).copy()
+
+    @property
+    def _patch_data(self) -> dict:
+        """
+        Generate a dictionary of modified data that needs to be patched on the server.
+
+        :return: A dictionary of modified attributes.
+        :rtype: 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 the model with the latest data from the server.
+        """
+
+        entity = self._endpoint.get(uid=self.uid).model_dump(exclude=["uid"])
+        self._original_data = entity.dict(by_alias=False, exclude=["uid"])
+        self.__dict__.update(self._original_data)
+
+    def save(self) -> None:
+        """
+        Save the current state of the model to the server by updating modified attributes.
+        """
+
+        if self._patch_data:
+            entity = self._endpoint.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:
+        """
+        Delete the model from the server.
+
+        :raises AttributeError: If the model's UID is not set.
+        """
+
+        if not self._uid:
+            raise AttributeError("This resource cannot be deleted: UID is not set.")
+        self._endpoint.delete(uid=self._uid)
+        self._uid = None

hydroserverpy/core/schemas/data_loaders.py

@@ -0,0 +1,73 @@
+from pydantic import BaseModel, Field
+from typing import Optional, List, TYPE_CHECKING
+from uuid import UUID
+from hydroserverpy.core.schemas.base import HydroServerCoreModel
+
+if TYPE_CHECKING:
+    from hydroserverpy.core.schemas.data_sources import DataSource
+
+
+class DataLoaderFields(BaseModel):
+    name: str = Field(
+        ...,
+        strip_whitespace=True,
+        max_length=255,
+        description="The name of the data loader.",
+    )
+
+
+class DataLoader(HydroServerCoreModel, DataLoaderFields):
+    """
+    A model representing a DataLoader, extending the core functionality of HydroServerCoreModel with additional
+    properties and methods.
+
+    :ivar _data_sources: A private attribute to cache the list of data sources associated with the DataLoader.
+    """
+
+    def __init__(self, _endpoint, _uid: Optional[UUID] = None, **data):
+        """
+        Initialize a DataLoader instance.
+
+        :param _endpoint: The endpoint associated with the data loader.
+        :type _endpoint: str
+        :param _uid: The unique identifier for the data loader.
+        :type _uid: Optional[UUID]
+        :param data: Additional attributes for the data loader.
+        """
+
+        super().__init__(_endpoint=_endpoint, _uid=_uid, **data)
+        self._data_sources = None
+
+    @property
+    def data_sources(self) -> List["DataSource"]:
+        """
+        The data sources associated with the data loader. If not already cached, fetch the data sources from the server.
+
+        :return: A list of data sources associated with the data loader.
+        :rtype: List[DataSource]
+        """
+
+        if self._data_sources is None:
+            self._data_sources = self._endpoint.list_data_sources(uid=self.uid)
+
+        return self._data_sources
+
+    def refresh(self) -> None:
+        """
+        Refresh the data loader with the latest data from the server and update cached data sources.
+        """
+
+        entity = self._endpoint.get(uid=self.uid).model_dump(exclude=["uid"])
+        self._original_data = entity
+        self.__dict__.update(entity)
+        if self._data_sources is not None:
+            self._data_sources = self._endpoint.list_data_sources(uid=self.uid)
+
+    def load_observations(self) -> None:
+        """
+        Load observations data from a local file or a remote URL into HydroServer using all data sources associated with
+        this data loader.
+        """
+
+        for data_source in self.data_sources:
+            data_source.load_observations()

hydroserverpy/core/schemas/data_sources.py

@@ -0,0 +1,223 @@
+import tempfile
+import io
+from pydantic import BaseModel, Field
+from typing import Optional, Literal, Union, List, TYPE_CHECKING
+from datetime import datetime
+from uuid import UUID
+from urllib.request import urlopen
+from hydroserverpy.core.schemas.base import HydroServerCoreModel
+from hydroserverpy.etl_csv.hydroserver_etl_csv import HydroServerETLCSV
+
+if TYPE_CHECKING:
+    from hydroserverpy.core.schemas.data_loaders import DataLoader
+    from hydroserverpy.core.schemas.datastreams import Datastream
+
+
+class DataSourceFields(BaseModel):
+    name: str = Field(
+        ...,
+        strip_whitespace=True,
+        max_length=255,
+        description="The name of the data source.",
+    )
+    path: Optional[str] = Field(
+        None,
+        strip_whitespace=True,
+        max_length=255,
+        description="The path to a local data source file.",
+    )
+    link: Optional[str] = Field(
+        None,
+        strip_whitespace=True,
+        max_length=255,
+        description="The link to a remote data source file.",
+    )
+    header_row: Optional[int] = Field(
+        None, gt=0, lt=9999, description="The row number where the data begins."
+    )
+    data_start_row: Optional[int] = Field(
+        None, gt=0, lt=9999, description="The row number where the data begins."
+    )
+    delimiter: Optional[str] = Field(
+        ",",
+        strip_whitespace=True,
+        max_length=1,
+        description="The delimiter used by the data source file.",
+    )
+    quote_char: Optional[str] = Field(
+        '"',
+        strip_whitespace=True,
+        max_length=1,
+        description="The quote delimiter character used by the data source file.",
+    )
+    interval: Optional[int] = Field(
+        None,
+        gt=0,
+        lt=9999,
+        description="The time interval at which the data source should be loaded.",
+    )
+    interval_units: Optional[Literal["minutes", "hours", "days", "weeks", "months"]] = (
+        Field(None, description="The interval units used by the data source file.")
+    )
+    crontab: Optional[str] = Field(
+        None,
+        strip_whitespace=True,
+        max_length=255,
+        description="The crontab used to schedule when the data source should be loaded.",
+    )
+    start_time: Optional[datetime] = Field(
+        None, description="When the data source should begin being loaded."
+    )
+    end_time: Optional[datetime] = Field(
+        None, description="When the data source should stop being loaded."
+    )
+    paused: Optional[bool] = Field(
+        False, description="Whether loading the data source should be paused or not."
+    )
+    timestamp_column: Union[int, str] = Field(
+        ...,
+        strip_whitespace=True,
+        max_length=255,
+        description="The column of the data source file containing the timestamps.",
+    )
+    timestamp_format: Optional[str] = Field(
+        "%Y-%m-%dT%H:%M:%S%Z",
+        strip_whitespace=True,
+        max_length=255,
+        description="The format of the timestamps, using Python's datetime strftime codes.",
+    )
+    timestamp_offset: Optional[str] = Field(
+        "+0000",
+        strip_whitespace=True,
+        max_length=255,
+        description="An ISO 8601 time zone offset designator code to be applied to timestamps in the data source file.",
+    )
+    data_loader_id: UUID = Field(
+        ...,
+        description="The ID of the data loader responsible for loading this data source.",
+    )
+    data_source_thru: Optional[datetime] = Field(
+        None, description="The timestamp through which the data source contains data."
+    )
+    last_sync_successful: Optional[bool] = Field(
+        None, description="Whether the last data loading attempt was successful of not."
+    )
+    last_sync_message: Optional[str] = Field(
+        None,
+        strip_whitespace=True,
+        description="A message generated by the data loader it attempted to load data from this data source.",
+    )
+    last_synced: Optional[datetime] = Field(
+        None,
+        description="The last time the data loader attempted to load data from this data source.",
+    )
+    next_sync: Optional[datetime] = Field(
+        None,
+        description="The next time the data loader will attempt to load data from this data source.",
+    )
+
+
+class DataSource(HydroServerCoreModel, DataSourceFields):
+    """
+    A model representing a data source, extending the core functionality of HydroServerCoreModel with additional
+    properties and methods.
+
+    :ivar _datastreams: A private attribute to cache the list of datastreams associated with the data source.
+    :ivar _data_loader: A private attribute to cache the data loader associated with the data source.
+    """
+
+    def __init__(self, _endpoint, _uid: Optional[UUID] = None, **data):
+        """
+        Initialize a DataSource instance.
+
+        :param _endpoint: The endpoint associated with the DataSource.
+        :param _uid: The unique identifier for the DataSource.
+        :type _uid: Optional[UUID]
+        :param data: Additional attributes for the DataSource.
+        """
+
+        super().__init__(_endpoint=_endpoint, _uid=_uid, **data)
+        self._datastreams = None
+        self._data_loader = None
+
+    @property
+    def datastreams(self) -> List["Datastream"]:
+        """
+        Retrieve the datastreams associated with the DataSource. If not already cached, fetch the datastreams from the
+        server.
+
+        :return: A list of datastreams associated with the data source.
+        :rtype: List[Datastream]
+        """
+
+        if self._datastreams is None:
+            self._datastreams = self._endpoint.list_datastreams(uid=self.uid)
+
+        return self._datastreams
+
+    @property
+    def data_loader(self) -> "DataLoader":
+        """
+        Retrieve the data loader associated with the data source. If not already cached, fetch the data loader from the
+        server.
+
+        :return: The data loader associated with the data source.
+        :rtype: DataLoader
+        """
+
+        if self._data_loader is None:
+            self._data_loader = self._endpoint._service.dataloaders.get(
+                uid=self.data_loader_id
+            )  # noqa
+
+        return self._data_loader
+
+    def refresh(self) -> None:
+        """
+        Refresh the data source with the latest data from the server and update cached datastreams and data loader if
+        they were previously loaded.
+        """
+
+        entity = self._endpoint.get(uid=self.uid).model_dump(exclude=["uid"])
+        self._original_data = entity
+        self.__dict__.update(entity)
+        if self._datastreams is not None:
+            self._datastreams = self._endpoint.list_datastreams(uid=self.uid)
+        if self._data_loader is not None:
+            self._data_loader = self._endpoint._service.dataloaders.get(
+                uid=self.data_loader_id
+            )  # noqa
+
+    def load_observations(self) -> None:
+        """
+        Load observations data from a local file or a remote URL into HydroServer using this data source configuration.
+        """
+
+        if self.path:
+            with open(self.path, "rb") as f:
+                with io.TextIOWrapper(f, encoding="utf-8") as data_file:
+                    hs_etl = HydroServerETLCSV(
+                        service=getattr(self._endpoint, "_service"),
+                        data_file=data_file,
+                        data_source=self,
+                    )
+                    hs_etl.run()
+        elif self.link:
+            with tempfile.NamedTemporaryFile(mode="w+b") as temp_file:
+                with urlopen(self.link) as response:
+                    chunk_size = 1024 * 1024 * 10  # Use a 10mb chunk size.
+                    while True:
+                        chunk = response.read(chunk_size)
+                        if not chunk:
+                            break
+                        temp_file.write(chunk)
+                temp_file.seek(0)
+                with io.TextIOWrapper(temp_file, encoding="utf-8") as data_file:
+                    hs_etl = HydroServerETLCSV(
+                        service=getattr(self._endpoint, "_service"),
+                        data_file=data_file,
+                        data_source=self,
+                    )
+                    hs_etl.run()
+        else:
+            return None