pyocat 0.1.0__tar.gz

pyocat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WATERCryst GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyocat-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: pyocat
+Version: 0.1.0
+Summary: 
+License-File: LICENSE
+Author: Mathias Hörtnagl
+Author-email: mathias.hoertnagl@watercryst.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.13.3,<3.0.0)
+Description-Content-Type: text/markdown
+
+Execute to download dependencies:
+
+```bash
+poetry install
+```
+
+Execute to run the unit tests:
+
+```bash
+poetry run pytest
+```
+
+Execute to build the library:
+
+```bash
+poetry build
+```
+

pyocat-0.1.0/README.md

@@ -0,0 +1,17 @@
+Execute to download dependencies:
+
+```bash
+poetry install
+```
+
+Execute to run the unit tests:
+
+```bash
+poetry run pytest
+```
+
+Execute to build the library:
+
+```bash
+poetry build
+```

pyocat-0.1.0/pyocat/__init__.py

@@ -0,0 +1,5 @@
+from .auth       import Auth      # type: ignore
+from .api_client import ApiClient # type: ignore
+
+from .async_auth       import AsyncAuth      # type: ignore
+from .async_api_client import AsyncApiClient # type: ignore

pyocat-0.1.0/pyocat/api_client.py

@@ -0,0 +1,193 @@
+from typing import Literal
+
+from .auth import Auth
+
+from .models import MeasurementResponse
+from .models import StatisticsResponse
+from .models import StateResponse
+
+
+class ApiClient:
+    """
+    Synchronous Biocat REST API v1 client.
+    """
+
+    def __init__(self, auth: Auth):
+        self.auth = auth
+
+
+    def acknowledge_event(self):
+        """
+        Acknowledges the current device warning or error.
+        """
+        self.auth.get('v1/ackevent')
+
+
+    def enable_absence(self):
+        """
+        Enables absence mode and raises leakage detector sensitivity.
+        """
+        self.auth.get('v1/absence/enable')
+
+
+    def disable_absence(self):
+        """
+        Disables absence mode and reverts leakage detector 
+        sensitivity to its default level.
+        """
+        self.auth.get('v1/absence/disable')
+
+
+    def pause_leakage_protection(
+        self, 
+        minutes: int
+    ):
+        """
+        Pauses leakage protection for a given duration of minutes.
+
+        Parameters
+        ----------
+        minutes : int
+            The pause duration in minutes. Must be within the range
+            [1 .. 4320].
+        """
+        self.auth.get('v1/leakageprotection/pause', { 'minutes': minutes })
+
+
+    def unpause_leakage_protection(self):
+        """
+        Reactivates leakage protection.
+        """
+        self.auth.get('v1/leakageprotection/unpause')
+
+
+    def start_self_test(self):
+        """
+        Starts the self test routine. Automatically checks all 
+        actuators and sensors and fills the active unit with drinking 
+        water over a defined flushing time.
+        
+        Requires 2 minutes for completion. 
+        
+        The device will return to water treatment if no errors could 
+        be detected.  
+        
+        In the case of errors, the current error will be reported
+        via the webhook endpoint. Additionally it can be queried
+        at any time with `GET v1/state`.        
+        """
+        self.auth.get('v1/selftest')
+
+
+    def get_measurements(self) -> MeasurementResponse:
+        """
+        Fetches current measurement data.
+
+        Returns
+        -------
+        The current measurement data.
+        """
+        response = self.auth.get('v1/measurements/direct')
+        return MeasurementResponse.model_validate(response.json())
+
+
+    def start_micro_leakage_measurement(self):
+        """
+        Starts the micro-leakage measurement to check the leak-
+        tightness of the piping. This allows the detection of micro-
+        leaks such as dripping taps or pipe fittings.  
+        For this measurements, water supply is briefly shut off.
+        
+        An unexpected water consumption during the measuring process, 
+        e.g. flushing the toilet or opening a tap, is automatically 
+        detected and the water supply is restored within a few seconds.
+        However, the test fails and the API call has to be repeated.
+        
+        ### Notice
+        
+        If you use a drip irrigation system in your household, this 
+        can be detected as a micro leak.
+        """
+        self.auth.get('v1/mlmeasurement/start')
+
+
+    def get_daily_statistics(self) -> StatisticsResponse:
+        """
+        Fetches the daily statistics.
+
+        Returns
+        -------
+        Water consumption statistics of the trailing 30 days.
+        """
+        response = self.auth.get('v1/statistics/daily/direct')
+        return StatisticsResponse.model_validate(response.json())
+
+
+    def get_todays_consumption(self) -> float:
+        """
+        Fetches the total consumption for today.
+
+        Returns
+        -------
+        Todays total water consumption in [L].
+        """
+        response = self.auth.get('v1/statistics/cumulative/daily')
+        return float(response.json())
+
+
+    def get_total_consumption(self) -> float:
+        """
+        Fetches the total water consumption since the device was 
+        installed.
+
+        Returns
+        -------
+        Total water consumption in [L].
+        """
+        response = self.auth.get('v1/statistics/cumulative/total')
+        return float(response.json())
+
+
+    def open_water_supply(self):
+        """
+        Connects the device with the water supply.
+        Confirms pending warnings and errors.
+        """
+        self.auth.get('v1/watersupply/open')
+
+
+    def close_water_supply(self):
+        """
+        Disconnects the device from the water supply.
+        """
+        self.auth.get('v1/watersupply/close')
+
+
+    def get_state(
+        self,
+        locale: str = 'de',
+        format: Literal['plain', 'md', 'html'] = 'plain'    
+    ) -> StateResponse:
+        """
+        Returns the current state of the device.
+
+        Parameters
+        ----------
+        locale : str
+            The language of the event message. Defaults to `de`.
+        format : `plain` | `md` | `html`
+            The format of the event message. Defaults to `plain`.
+            * `plain` - Renders the event message as plain text.
+            * `md`    - Renders the event message as Markdown.
+            * `html`  - Renders the event message as HTML.
+
+        Returns
+        -------
+        The current device state.
+        """
+        response = self.auth.get(
+            path='v1/state', 
+            params={ 'locale': locale, 'format': format }
+        )
+        return StateResponse.model_validate(response.json())
+

pyocat-0.1.0/pyocat/async_api_client.py

@@ -0,0 +1,193 @@
+from typing import Literal
+
+from .async_auth import AsyncAuth
+
+from .models import MeasurementResponse
+from .models import StatisticsResponse
+from .models import StateResponse
+
+
+class AsyncApiClient:
+    """
+    Asynchronous Biocat REST API v1 client.
+    """
+
+    def __init__(self, auth: AsyncAuth):
+        self.auth = auth
+
+
+    async def acknowledge_event(self):
+        """
+        Acknowledges the current device warning or error.
+        """
+        await self.auth.get('v1/ackevent')
+
+
+    async def enable_absence(self):
+        """
+        Enables absence mode and raises leakage detector sensitivity.
+        """
+        await self.auth.get('v1/absence/enable')
+
+
+    async def disable_absence(self):
+        """
+        Disables absence mode and reverts leakage detector 
+        sensitivity to its default level.
+        """
+        await self.auth.get('v1/absence/disable')
+
+
+    async def pause_leakage_protection(
+        self, 
+        minutes: int
+    ):
+        """
+        Pauses leakage protection for a given duration of minutes.
+
+        Parameters
+        ----------
+        minutes : int
+            The pause duration in minutes. Must be within the range
+            [1 .. 4320].
+        """
+        await self.auth.get('v1/leakageprotection/pause', { 'minutes': minutes })
+
+
+    async def unpause_leakage_protection(self):
+        """
+        Reactivates leakage protection.
+        """
+        await self.auth.get('v1/leakageprotection/unpause')
+
+
+    async def start_self_test(self):
+        """
+        Starts the self test routine. Automatically checks all 
+        actuators and sensors and fills the active unit with drinking 
+        water over a defined flushing time.
+        
+        Requires 2 minutes for completion. 
+        
+        The device will return to water treatment if no errors could 
+        be detected.  
+        
+        In the case of errors, the current error will be reported
+        via the webhook endpoint. Additionally it can be queried
+        at any time with `GET v1/state`.        
+        """
+        await self.auth.get('v1/selftest')
+
+
+    async def get_measurements(self) -> MeasurementResponse:
+        """
+        Fetches current measurement data.
+
+        Returns
+        -------
+        The current measurement data.
+        """
+        response = await self.auth.get('v1/measurements/direct')
+        return MeasurementResponse.model_validate(response.json())
+
+
+    async def start_micro_leakage_measurement(self):
+        """
+        Starts the micro-leakage measurement to check the leak-
+        tightness of the piping. This allows the detection of micro-
+        leaks such as dripping taps or pipe fittings.  
+        For this measurements, water supply is briefly shut off.
+        
+        An unexpected water consumption during the measuring process, 
+        e.g. flushing the toilet or opening a tap, is automatically 
+        detected and the water supply is restored within a few seconds.
+        However, the test fails and the API call has to be repeated.
+        
+        ### Notice
+        
+        If you use a drip irrigation system in your household, this 
+        can be detected as a micro leak.
+        """
+        await self.auth.get('v1/mlmeasurement/start')
+
+
+    async def get_daily_statistics(self) -> StatisticsResponse:
+        """
+        Fetches the daily statistics.
+
+        Returns
+        -------
+        Water consumption statistics of the trailing 30 days.
+        """
+        response = await self.auth.get('v1/statistics/daily/direct')
+        return StatisticsResponse.model_validate(response.json())
+
+
+    async def get_todays_consumption(self) -> float:
+        """
+        Fetches the total consumption for today.
+
+        Returns
+        -------
+        Todays total water consumption in [L].
+        """
+        response = await self.auth.get('v1/statistics/cumulative/daily')
+        return float(response.json())
+
+
+    async def get_total_consumption(self) -> float:
+        """
+        Fetches the total water consumption since the device was 
+        installed.
+
+        Returns
+        -------
+        Total water consumption in [L].
+        """
+        response = await self.auth.get('v1/statistics/cumulative/total')
+        return float(response.json())
+
+
+    async def open_water_supply(self):
+        """
+        Connects the device with the water supply.
+        Confirms pending warnings and errors.
+        """
+        await self.auth.get('v1/watersupply/open')
+
+
+    async def close_water_supply(self):
+        """
+        Disconnects the device from the water supply.
+        """
+        await self.auth.get('v1/watersupply/close')
+
+
+    async def get_state(
+        self,
+        locale: str = 'de',
+        format: Literal['plain', 'md', 'html'] = 'plain'    
+    ) -> StateResponse:
+        """
+        Returns the current state of the device.
+
+        Parameters
+        ----------
+        locale : str
+            The language of the event message. Defaults to `de`.
+        format : `plain` | `md` | `html`
+            The format of the event message. Defaults to `plain`.
+            * `plain` - Renders the event message as plain text.
+            * `md`    - Renders the event message as Markdown.
+            * `html`  - Renders the event message as HTML.
+
+        Returns
+        -------
+        The current device state.
+        """
+        response = await self.auth.get(
+            path='v1/state', 
+            params={ 'locale': locale, 'format': format }
+        )
+        return StateResponse.model_validate(response.json())
+

pyocat-0.1.0/pyocat/async_auth.py

@@ -0,0 +1,63 @@
+from typing import Mapping, Union
+
+from httpx import AsyncClient, Response
+
+class AsyncAuth:
+    """
+    Make asynchronous authenticated requests.
+    """
+
+    def __init__(
+        self,
+        client: AsyncClient,
+        api_key: str,
+        host: str = 'https://appapi.watercryst.com'
+    ):
+        """
+        Creates a new authenticated request sender.
+
+        Parameters
+        ----------
+        client: `httpx.AsyncClient`
+            Instance of an asynchronous HTTP client.
+        api_key : str
+            The api key.
+        host : str
+            The Biocat SmartHome API host. 
+            Defaults to `https://appapi.watercryst.com`.
+        """
+        self.client = client
+        self.api_key = api_key
+        self.host = host
+
+
+    async def get(
+        self,
+        path: str,
+        params: Mapping[str, Union[str, int, float, bool]] | None = None,
+    ) -> Response:
+        """
+        Send an asynchronous `GET` request.
+
+        Parameters
+        ----------
+        path : str
+            The relative path.
+        params : Mapping[str, Union[str, int, float, bool]]
+            Optional query parameters. 
+
+        Returns
+        -------
+        An `httpx.Response`.
+        """
+        headers = dict[str, str]()
+        headers['X-API-KEY'] = self.api_key
+
+        response = await self.client.get(
+            url=f'{self.host}/{path}', 
+            params=params,
+            headers=headers
+        )
+        response.raise_for_status()
+
+        return response

pyocat-0.1.0/pyocat/auth.py

@@ -0,0 +1,63 @@
+from typing import Mapping, Union
+
+from httpx import Client, Response
+
+class Auth:
+    """
+    Make authenticated requests.
+    """
+
+    def __init__(
+        self,
+        client: Client,
+        api_key: str,
+        host: str = 'https://appapi.watercryst.com'
+    ):
+        """
+        Creates a new authenticated request sender.
+
+        Parameters
+        ----------
+        client: `httpx.Client`
+            Instance of a synchronous HTTP client.
+        api_key : str
+            The api key.
+        host : str
+            The Biocat SmartHome API host. 
+            Defaults to `https://appapi.watercryst.com`.
+        """
+        self.client = client
+        self.api_key = api_key
+        self.host = host
+
+
+    def get(
+        self,
+        path: str,
+        params: Mapping[str, Union[str, int, float, bool]] | None = None,
+    ) -> Response:
+        """
+        Send a `GET` request.
+
+        Parameters
+        ----------
+        path : str
+            The relative path.
+        params : Mapping[str, Union[str, int, float, bool]]
+            Optional query parameters. 
+
+        Returns
+        -------
+        An `httpx.Response`.
+        """
+        headers = dict[str, str]()
+        headers['X-API-KEY'] = self.api_key
+
+        response = self.client.get(
+            url=f'{self.host}/{path}', 
+            params=params,
+            headers=headers
+        )
+        response.raise_for_status()
+
+        return response

pyocat-0.1.0/pyocat/models/__init__.py

@@ -0,0 +1,7 @@
+from .event_response            import EventResponse, EventCategory # type: ignore
+from .measurement_response      import MeasurementResponse          # type: ignore
+from .message_response          import MessageResponse              # type: ignore
+from .mode_response             import ModeResponse, ModeId         # type: ignore
+from .state_response            import StateResponse, MlState       # type: ignore
+from .statistics_response       import StatisticsResponse           # type: ignore
+from .water_protection_response import WaterProtectionResponse      # type: ignore

pyocat-0.1.0/pyocat/models/event_response.py

@@ -0,0 +1,34 @@
+from datetime import datetime
+from typing import Annotated, Literal
+from pydantic import BaseModel, Field
+
+
+EventCategory = Literal['error', 'warning', 'info']
+
+
+class EventResponse(BaseModel):
+    """
+    Represents an event.
+
+    Attributes
+    ----------
+    type : str 
+        Denotes the type of the response.
+    event_id : int 
+        Identifies the type of the event.
+    category : Literal['error', 'warning', 'info'] 
+        The event category.
+    title : str 
+        Event summary.
+    description : str 
+        Detailed description.
+    timestamp : datetime
+        UTC date time of the event.
+    """
+
+    type:        Annotated[str,           Field(alias='type')]
+    event_id:    Annotated[int,           Field(alias='eventId')]
+    category:    Annotated[EventCategory, Field(alias='category')]
+    title:       Annotated[str,           Field(alias='title')]
+    description: Annotated[str,           Field(alias='description')]
+    timestamp:   Annotated[datetime,      Field(alias='timestamp')]

pyocat-0.1.0/pyocat/models/measurement_response.py

@@ -0,0 +1,27 @@
+from typing import Annotated, Union
+from pydantic import BaseModel, Field
+
+
+class MeasurementResponse(BaseModel):
+    """
+    Represents current measurement data.
+
+    Attributes
+    ----------
+    water_temp : int 
+        Water temperature in degree celsius [°C].
+    pressure : float
+        Pressure in [bar].
+    flow_rate : float 
+        Flow rate in liters per minute [L/min].
+    last_water_tap_volume : float
+        Volume of the last water tapping in liters [L].
+    last_water_tap_duration : float 
+        Duration of the last water tapping in seconds [sec].
+    """
+
+    water_temp:              Annotated[Union[int,   None], Field(alias='waterTemp')]            = None
+    pressure:                Annotated[Union[float, None], Field(alias='pressure')]             = None
+    flow_rate:               Annotated[Union[float, None], Field(alias='flowRate')]             = None
+    last_water_tap_volume:   Annotated[Union[float, None], Field(alias='lastWaterTapVolume')]   = None
+    last_water_tap_duration: Annotated[Union[float, None], Field(alias='lastWaterTapDuration')] = None

pyocat-0.1.0/pyocat/models/message_response.py

@@ -0,0 +1,23 @@
+from datetime import datetime
+from typing import Annotated
+from pydantic import BaseModel, Field
+
+
+class MessageResponse(BaseModel):
+    """
+    Represents a message.
+
+    Attributes
+    ----------
+    type : str 
+        Denotes the type of the response.
+    absence_mode_enabled : bool 
+        Indicates the state of the absence mode.
+    pause_leakage_protection_until_utc : datetime
+        UTC date time string when the leakage protection 
+        will be active again.
+    """
+
+    type:                               Annotated[str,      Field(alias='type')]
+    absence_mode_enabled:               Annotated[bool,     Field(alias='absenceModeEnabled')]
+    pause_leakage_protection_until_utc: Annotated[datetime, Field(alias='pauseLeakageProtectionUntilUTC')]

pyocat-0.1.0/pyocat/models/mode_response.py

@@ -0,0 +1,21 @@
+from typing import Annotated, Literal
+from pydantic import BaseModel, Field
+
+
+ModeId = Literal['ER', 'FS', 'MC', 'RS', 'ST', 'TD', 'UD', 'WO', 'WT']
+
+
+class ModeResponse(BaseModel):
+    """
+    Represents the current mode of operation.
+
+    Attributes
+    ----------
+    id : Literal['ER', 'FS', 'MC', 'RS', 'ST', 'TD', 'UD', 'WO', 'WT'] 
+        Mode identifier.
+    name : str 
+        Mode display name.
+    """
+
+    id:   Annotated[ModeId, Field(alias='id')] 
+    name: Annotated[str,    Field(alias='name')]

pyocat-0.1.0/pyocat/models/state_response.py

@@ -0,0 +1,44 @@
+from typing import Annotated, Literal, Union
+from pydantic import BaseModel, Field
+
+from .event_response import EventResponse
+from .mode_response import ModeResponse
+from .water_protection_response import WaterProtectionResponse
+
+
+MlState = Literal[ 
+    "cancelled",
+    "failure-pressure-drop",
+    "failure-start-pressure",
+    "failure-unknown",
+    "failure-water-tap",
+    "idle",
+    "leakage",
+    "running",
+    "success"
+]
+
+
+class StateResponse(BaseModel):
+    """
+    Represents the current device state.
+
+    Attributes
+    ----------
+    online : bool 
+        Indicates whether the device is online or offline right now.
+    mode : ModeResponse
+        Represents the current mode of operation.
+    event : EventResponse
+        Represents an event.
+    water_protection : WaterProtectionResponse | None
+        Represents the current state of the water protection subsystem. 
+    ml_state : Literal["cancelled", "failure-pressure-drop", "failure-start-pressure", "failure-unknown", "failure-water-tap", "idle", "leakage", "running", "success"] | None
+        The state of the current (or last) micro leakage measurement.
+    """
+
+    online:           Annotated[bool,                                 Field(alias='online')]
+    mode:             Annotated[ModeResponse,                         Field(alias='mode')]
+    event:            Annotated[EventResponse,                        Field(alias='event')]
+    water_protection: Annotated[Union[WaterProtectionResponse, None], Field(alias='waterProtection')] = None
+    ml_state:         Annotated[Union[MlState, None],                 Field(alias='mlState')]         = None

pyocat-0.1.0/pyocat/models/statistics_response.py

@@ -0,0 +1,35 @@
+from datetime import datetime
+from typing import Annotated
+from pydantic import BaseModel, Field
+
+
+class StatisticsResponseEntry(BaseModel):
+    """
+    A consumption statistics data point.
+
+    Attributes
+    ----------
+    consumption : float 
+        Water consumption for this day in liters [L].
+    date : datetime 
+        UTC date of the measurement. 
+    """
+
+    consumption: Annotated[float,    Field(alias='consumption')]
+    date:        Annotated[datetime, Field(alias='date')]
+
+
+class StatisticsResponse(BaseModel):
+    """
+    Represents a list of consumption statistics data points.
+
+    Attributes
+    ----------
+    type : str 
+        Denotes the type of the response.
+    entries : list[StatisticsResponseEntry] 
+        List of data points.    
+    """
+
+    type:    Annotated[str,                           Field(alias='type')]
+    entries: Annotated[list[StatisticsResponseEntry], Field(alias='entries')] = []

pyocat-0.1.0/pyocat/models/water_protection_response.py

@@ -0,0 +1,19 @@
+from datetime import datetime
+from typing import Annotated
+from pydantic import BaseModel, Field
+
+
+class WaterProtectionResponse(BaseModel):
+    """
+    Represents the current state of the water protection subsystem.
+
+    Attributes
+    ----------
+    absence_mode_enabled : bool 
+        Indicates the state of the absence mode.
+    pause_leakage_protection_until_utc : datetime
+        UTC date time when the leakage protection will be active again.     
+    """
+
+    absence_mode_enabled:               Annotated[bool,     Field(alias='absenceModeEnabled')]
+    pause_leakage_protection_until_utc: Annotated[datetime, Field(alias='pauseLeakageProtectionUntilUTC')]

pyocat-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "pyocat"
+version = "0.1.0"
+description = ""
+authors = [
+    { name = "Mathias Hörtnagl", email = "mathias.hoertnagl@watercryst.com" },
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx (>=0.28.1,<0.29.0)", 
+    "pydantic (>=2.13.3,<3.0.0)"
+]
+
+[tool.poetry.scripts]
+main = "python_biocat_rest_api_client:main"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.3,<10.0.0)",
+    "pytest-asyncio (>=1.3.0,<2.0.0)",
+    "pytest-httpx (>=0.36.2,<0.37.0)"
+]