pypetkitapi 1.6.2__tar.gz → 1.11.2__tar.gz

{pypetkitapi-1.6.2 → pypetkitapi-1.11.2}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Jezza34000
+Copyright (c) 2024 - 2025 Jezza34000
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

pypetkitapi-1.6.2/README.md → pypetkitapi-1.11.2/PKG-INFO

@@ -1,3 +1,24 @@
+Metadata-Version: 2.3
+Name: pypetkitapi
+Version: 1.11.2
+Summary: Python client for PetKit API
+License: MIT
+Author: Jezza34000
+Author-email: info@mail.com
+Requires-Python: >=3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
+Requires-Dist: aiohttp (>=3.10.10,<4.0.0)
+Requires-Dist: m3u8 (>=6.0)
+Requires-Dist: pycryptodome (>=3.19.1,<4.0.0)
+Requires-Dist: pydantic (>=1.10.18,<3.0.0)
+Project-URL: Homepage, https://github.com/Jezza34000/pypetkit
+Description-Content-Type: text/markdown
+
 # Petkit API Client
 
 ---
@@ -12,6 +33,12 @@
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=bugs)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+
+[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
 
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
 [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
@@ -46,9 +73,11 @@ pip install pypetkitapi
 ## Usage Example:
 
 ```python
+import asyncio
+import logging
 import aiohttp
 from pypetkitapi.client import PetKitClient
-from pypetkitapi.command import DeviceCommand, FeederCommand, LBCommand, LBAction, LitterCommand
+from pypetkitapi.command import DeviceCommand, FeederCommand, LBCommand, DeviceAction, LitterCommand
 
 logging.basicConfig(level=logging.DEBUG)
 
@@ -57,37 +86,50 @@ async def main():
         client = PetKitClient(
             username="username",  # Your PetKit account username or id
             password="password",  # Your PetKit account password
-            region="FR",  # Your region or country code (e.g. FR, US, etc.)
-            timezone="Europe/Paris",  # Your timezone
+            region="FR",  # Your region or country code (e.g. FR, US,CN etc.)
+            timezone="Europe/Paris",  # Your timezone(e.g. "Asia/Shanghai")
             session=session,
         )
 
         await client.get_devices_data()
 
-        # Read the account data
-        print(client.account_data)
+        # Lists all devices and pet from account
+
+        for key, value in client.petkit_entities.items():
+            print(f"{key}: {type(value).__name__} - {value.name}")
 
-        # Read the devices data
-        print(client.petkit_entities)
+        # Select a device
+        device_id = key
+        # Read devices or pet information
+        print(client.petkit_entities[device_id])
 
         # Send command to the devices
         ### Example 1 : Turn on the indicator light
         ### Device_ID, Command, Payload
-        await client.send_api_request(123456789, DeviceCommand.UPDATE_SETTING, {"lightMode": 1})
+        await client.send_api_request(device_id, DeviceCommand.UPDATE_SETTING, {"lightMode": 1})
 
         ### Example 2 : Feed the pet
         ### Device_ID, Command, Payload
-        await client.send_api_request(123456789, FeederCommand.MANUAL_FEED, {"amount": 1})
+        # simple hopper :
+        await client.send_api_request(device_id, FeederCommand.MANUAL_FEED, {"amount": 1})
+        # dual hopper :
+        await client.send_api_request(device_id, FeederCommand.MANUAL_FEED, {"amount1": 2})
+        # or
+        await client.send_api_request(device_id, FeederCommand.MANUAL_FEED, {"amount2": 2})
 
         ### Example 3 : Start the cleaning process
         ### Device_ID, Command, Payload
-        await client.send_api_request(123456789, LitterCommand.CONTROL_DEVICE, {LBAction.START: LBCommand.CLEANING})
+        await client.send_api_request(device_id, LitterCommand.CONTROL_DEVICE, {DeviceAction.START: LBCommand.CLEANING})
 
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+## More example usage
+
+Check at the usage in the Home Assistant integration : [here](https://github.com/Jezza34000/homeassistant_petkit)
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request.
@@ -95,3 +137,4 @@ Contributions are welcome! Please open an issue or submit a pull request.
 ## License
 
 This project is licensed under the MIT License. See the LICENSE file for details.
+

pypetkitapi-1.6.2/PKG-INFO → pypetkitapi-1.11.2/README.md

@@ -1,21 +1,3 @@
-Metadata-Version: 2.1
-Name: pypetkitapi
-Version: 1.6.2
-Summary: Python client for PetKit API
-Home-page: https://github.com/Jezza34000/pypetkit
-License: MIT
-Author: Jezza34000
-Author-email: info@mail.com
-Requires-Python: >=3.11
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: aiohttp (>=3.11.0,<4.0.0)
-Requires-Dist: pycryptodome (>=3.21.0,<4.0.0)
-Description-Content-Type: text/markdown
-
 # Petkit API Client
 
 ---
@@ -30,6 +12,12 @@ Description-Content-Type: text/markdown
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=bugs)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
+
+[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=Jezza34000_py-petkit-api&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=Jezza34000_py-petkit-api)
 
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)][pre-commit]
 [![Black](https://img.shields.io/badge/code%20style-black-000000.svg)][black]
@@ -64,9 +52,11 @@ pip install pypetkitapi
 ## Usage Example:
 
 ```python
+import asyncio
+import logging
 import aiohttp
 from pypetkitapi.client import PetKitClient
-from pypetkitapi.command import DeviceCommand, FeederCommand, LBCommand, LBAction, LitterCommand
+from pypetkitapi.command import DeviceCommand, FeederCommand, LBCommand, DeviceAction, LitterCommand
 
 logging.basicConfig(level=logging.DEBUG)
 
@@ -75,37 +65,50 @@ async def main():
         client = PetKitClient(
             username="username",  # Your PetKit account username or id
             password="password",  # Your PetKit account password
-            region="FR",  # Your region or country code (e.g. FR, US, etc.)
-            timezone="Europe/Paris",  # Your timezone
+            region="FR",  # Your region or country code (e.g. FR, US,CN etc.)
+            timezone="Europe/Paris",  # Your timezone(e.g. "Asia/Shanghai")
             session=session,
         )
 
         await client.get_devices_data()
 
-        # Read the account data
-        print(client.account_data)
+        # Lists all devices and pet from account
+
+        for key, value in client.petkit_entities.items():
+            print(f"{key}: {type(value).__name__} - {value.name}")
 
-        # Read the devices data
-        print(client.petkit_entities)
+        # Select a device
+        device_id = key
+        # Read devices or pet information
+        print(client.petkit_entities[device_id])
 
         # Send command to the devices
         ### Example 1 : Turn on the indicator light
         ### Device_ID, Command, Payload
-        await client.send_api_request(123456789, DeviceCommand.UPDATE_SETTING, {"lightMode": 1})
+        await client.send_api_request(device_id, DeviceCommand.UPDATE_SETTING, {"lightMode": 1})
 
         ### Example 2 : Feed the pet
         ### Device_ID, Command, Payload
-        await client.send_api_request(123456789, FeederCommand.MANUAL_FEED, {"amount": 1})
+        # simple hopper :
+        await client.send_api_request(device_id, FeederCommand.MANUAL_FEED, {"amount": 1})
+        # dual hopper :
+        await client.send_api_request(device_id, FeederCommand.MANUAL_FEED, {"amount1": 2})
+        # or
+        await client.send_api_request(device_id, FeederCommand.MANUAL_FEED, {"amount2": 2})
 
         ### Example 3 : Start the cleaning process
         ### Device_ID, Command, Payload
-        await client.send_api_request(123456789, LitterCommand.CONTROL_DEVICE, {LBAction.START: LBCommand.CLEANING})
+        await client.send_api_request(device_id, LitterCommand.CONTROL_DEVICE, {DeviceAction.START: LBCommand.CLEANING})
 
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+## More example usage
+
+Check at the usage in the Home Assistant integration : [here](https://github.com/Jezza34000/homeassistant_petkit)
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request.
@@ -113,4 +116,3 @@ Contributions are welcome! Please open an issue or submit a pull request.
 ## License
 
 This project is licensed under the MIT License. See the LICENSE file for details.
-

pypetkitapi-1.11.2/pypetkitapi/__init__.py

@@ -0,0 +1,107 @@
+"""Pypetkit: A Python library for interfacing with PetKit"""
+
+from .client import PetKitClient
+from .command import (
+    DeviceAction,
+    DeviceCommand,
+    FeederCommand,
+    LBCommand,
+    LitterCommand,
+    PetCommand,
+    PurMode,
+)
+from .const import (
+    CTW3,
+    D3,
+    D4,
+    D4H,
+    D4S,
+    D4SH,
+    DEVICES_FEEDER,
+    DEVICES_LITTER_BOX,
+    DEVICES_PURIFIER,
+    DEVICES_WATER_FOUNTAIN,
+    FEEDER,
+    FEEDER_MINI,
+    FEEDER_WITH_CAMERA,
+    K2,
+    K3,
+    LITTER_NO_CAMERA,
+    LITTER_WITH_CAMERA,
+    T3,
+    T4,
+    T5,
+    T6,
+    W5,
+    MediaType,
+    RecordType,
+)
+from .containers import Pet
+from .exceptions import (
+    PetkitAuthenticationUnregisteredEmailError,
+    PetkitRegionalServerNotFoundError,
+    PetkitSessionError,
+    PetkitSessionExpiredError,
+    PetkitTimeoutError,
+    PypetkitError,
+)
+from .feeder_container import Feeder, RecordsItems
+from .litter_container import Litter, LitterRecord, WorkState
+from .media import DownloadDecryptMedia, MediaCloud, MediaFile, MediaManager
+from .purifier_container import Purifier
+from .water_fountain_container import WaterFountain
+
+__version__ = "1.11.2"
+
+__all__ = [
+    "CTW3",
+    "D3",
+    "D4",
+    "D4H",
+    "D4S",
+    "D4SH",
+    "DEVICES_FEEDER",
+    "DEVICES_LITTER_BOX",
+    "DEVICES_PURIFIER",
+    "DEVICES_WATER_FOUNTAIN",
+    "FEEDER_WITH_CAMERA",
+    "LITTER_WITH_CAMERA",
+    "LITTER_NO_CAMERA",
+    "DeviceAction",
+    "DeviceCommand",
+    "FEEDER",
+    "FEEDER_MINI",
+    "Feeder",
+    "FeederCommand",
+    "K2",
+    "K3",
+    "LBCommand",
+    "Litter",
+    "LitterCommand",
+    "LitterRecord",
+    "MediaManager",
+    "DownloadDecryptMedia",
+    "MediaCloud",
+    "MediaFile",
+    "MediaType",
+    "Pet",
+    "PetCommand",
+    "PetKitClient",
+    "PetkitAuthenticationUnregisteredEmailError",
+    "PetkitRegionalServerNotFoundError",
+    "PetkitSessionError",
+    "PetkitSessionExpiredError",
+    "PetkitTimeoutError",
+    "PurMode",
+    "Purifier",
+    "PypetkitError",
+    "RecordType",
+    "RecordsItems",
+    "T3",
+    "T4",
+    "T5",
+    "T6",
+    "W5",
+    "WaterFountain",
+    "WorkState",
+]

pypetkitapi-1.11.2/pypetkitapi/bluetooth.py

@@ -0,0 +1,194 @@
+"""Module for handling Bluetooth communication with PetKit devices."""
+
+import asyncio
+import base64
+from datetime import datetime
+from http import HTTPMethod
+import logging
+from typing import TYPE_CHECKING
+import urllib.parse
+
+from pypetkitapi.command import FOUNTAIN_COMMAND, FountainAction
+from pypetkitapi.const import (
+    BLE_CONNECT_ATTEMPT,
+    BLE_END_TRAME,
+    BLE_START_TRAME,
+    PetkitEndpoint,
+)
+from pypetkitapi.containers import BleRelay
+
+if TYPE_CHECKING:
+    from pypetkitapi import PetKitClient, WaterFountain
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BluetoothManager:
+    """Class for handling Bluetooth communication with PetKit devices."""
+
+    def __init__(self, client: "PetKitClient"):
+        """Initialize the BluetoothManager class."""
+        self.client = client
+
+    async def _get_fountain_instance(self, fountain_id: int) -> "WaterFountain":
+        """Get the WaterFountain instance for the given fountain_id."""
+        from pypetkitapi.water_fountain_container import WaterFountain
+
+        water_fountain = self.client.petkit_entities.get(fountain_id)
+        if not isinstance(water_fountain, WaterFountain):
+            _LOGGER.error("Water fountain with ID %s not found.", fountain_id)
+            raise TypeError(f"Water fountain with ID {fountain_id} not found.")
+        return water_fountain
+
+    async def check_relay_availability(self, fountain_id: int) -> bool:
+        """Check if BLE relay is available for the given fountain_id."""
+        fountain = None
+        for account in self.client.account_data:
+            if account.device_list:
+                fountain = next(
+                    (
+                        device
+                        for device in account.device_list
+                        if device.device_id == fountain_id
+                    ),
+                    None,
+                )
+                if fountain:
+                    break
+        if not fountain:
+            raise ValueError(
+                f"Fountain with device_id {fountain_id} not found for the current account"
+            )
+        group_id = fountain.group_id
+        response = await self.client.req.request(
+            method=HTTPMethod.POST,
+            url=f"{PetkitEndpoint.BLE_AS_RELAY}",
+            params={"groupId": group_id},
+            headers=await self.client.get_session_id(),
+        )
+        ble_relays = [BleRelay(**relay) for relay in response]
+        if len(ble_relays) == 0:
+            _LOGGER.warning("No BLE relay devices found.")
+            return False
+        return True
+
+    async def open_ble_connection(self, fountain_id: int) -> bool:
+        """Open a BLE connection to the given fountain_id."""
+        _LOGGER.info("Opening BLE connection to fountain %s", fountain_id)
+        water_fountain = await self._get_fountain_instance(fountain_id)
+        if await self.check_relay_availability(fountain_id) is False:
+            _LOGGER.error("BLE relay not available (id: %s).", fountain_id)
+            return False
+        if water_fountain.is_connected is True:
+            _LOGGER.error("BLE connection already established (id %s)", fountain_id)
+            return True
+        response = await self.client.req.request(
+            method=HTTPMethod.POST,
+            url=PetkitEndpoint.BLE_CONNECT,
+            data={"bleId": fountain_id, "type": 24, "mac": water_fountain.mac},
+            headers=await self.client.get_session_id(),
+        )
+        if response != {"state": 1}:
+            _LOGGER.error("Unable to open a BLE connection (id %s)", fountain_id)
+            water_fountain.is_connected = False
+            return False
+        for attempt in range(BLE_CONNECT_ATTEMPT):
+            _LOGGER.debug(
+                "BLE connection... %s/%s (id %s)",
+                attempt,
+                BLE_CONNECT_ATTEMPT,
+                fountain_id,
+            )
+            response = await self.client.req.request(
+                method=HTTPMethod.POST,
+                url=PetkitEndpoint.BLE_POLL,
+                data={"bleId": fountain_id, "type": 24, "mac": water_fountain.mac},
+                headers=await self.client.get_session_id(),
+            )
+            if response == 1:
+                _LOGGER.info(
+                    "BLE connection established successfully (id %s)", fountain_id
+                )
+                water_fountain.is_connected = True
+                water_fountain.last_ble_poll = datetime.now().strftime(
+                    "%Y-%m-%dT%H:%M:%S.%f"
+                )
+                return True
+            await asyncio.sleep(4)
+        _LOGGER.error(
+            "Failed to establish BLE connection after %s attempts (id %s)",
+            BLE_CONNECT_ATTEMPT,
+            fountain_id,
+        )
+        water_fountain.is_connected = False
+        return False
+
+    async def close_ble_connection(self, fountain_id: int) -> None:
+        """Close the BLE connection to the given fountain_id."""
+        _LOGGER.info("Closing BLE connection to fountain %s", fountain_id)
+        water_fountain = await self._get_fountain_instance(fountain_id)
+
+        if water_fountain.is_connected is False:
+            _LOGGER.error(
+                "BLE connection not established. Cannot close (id %s)", fountain_id
+            )
+            return
+
+        await self.client.req.request(
+            method=HTTPMethod.POST,
+            url=PetkitEndpoint.BLE_CANCEL,
+            data={"bleId": fountain_id, "type": 24, "mac": water_fountain.mac},
+            headers=await self.client.get_session_id(),
+        )
+        _LOGGER.info("BLE connection closed successfully (id %s)", fountain_id)
+
+    async def get_ble_cmd_data(
+        self, fountain_command: list, counter: int
+    ) -> tuple[int, str]:
+        """Get the BLE command data for the given fountain_command."""
+        cmd_code = fountain_command[0]
+        modified_command = fountain_command[:2] + [counter] + fountain_command[2:]
+        ble_data = [*BLE_START_TRAME, *modified_command, *BLE_END_TRAME]
+        encoded_data = await self._encode_ble_data(ble_data)
+        return cmd_code, encoded_data
+
+    @staticmethod
+    async def _encode_ble_data(byte_list: list) -> str:
+        """Encode the given byte_list to a base64 encoded string."""
+        byte_array = bytearray(byte_list)
+        b64_encoded = base64.b64encode(byte_array)
+        return urllib.parse.quote(b64_encoded)
+
+    async def send_ble_command(self, fountain_id: int, command: FountainAction) -> bool:
+        """Send the given BLE command to the fountain_id."""
+        _LOGGER.info("Sending BLE command to fountain %s", fountain_id)
+        water_fountain = await self._get_fountain_instance(fountain_id)
+        if water_fountain.is_connected is False:
+            _LOGGER.error("BLE connection not established (id %s)", fountain_id)
+            return False
+        command_data = FOUNTAIN_COMMAND.get(command)
+        if command_data is None:
+            _LOGGER.error(
+                "BLE fountain command '%s' not found (id %s)", command, fountain_id
+            )
+            return False
+        cmd_code, cmd_data = await self.get_ble_cmd_data(
+            list(command_data), water_fountain.ble_counter
+        )
+        response = await self.client.req.request(
+            method=HTTPMethod.POST,
+            url=PetkitEndpoint.BLE_CONTROL_DEVICE,
+            data={
+                "bleId": water_fountain.id,
+                "cmd": cmd_code,
+                "data": cmd_data,
+                "mac": water_fountain.mac,
+                "type": 24,
+            },
+            headers=await self.client.get_session_id(),
+        )
+        if response != 1:
+            _LOGGER.error("Failed to send BLE command (id %s)", fountain_id)
+            return False
+        _LOGGER.info("BLE command sent successfully (id %s)", fountain_id)
+        return True