hinen-open-api 1.0.0__tar.gz

hinen_open_api-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hinen
+
+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.

hinen_open_api-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include requirements.txt
+include LICENSE

hinen_open_api-1.0.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: hinen-open-api
+Version: 1.0.0
+Summary: Hinen Open API Client
+Author: Hinen-WeiFeng
+License: MIT
+Project-URL: Homepage, https://github.com/Hinen-IoT/hinen_open_api.git
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0.0,>=3.8.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: yarl<2.0.0,>=1.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.15; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.9; extra == "dev"
+Dynamic: license-file
+
+# Hinen Open API Client
+
+A Python client library for the Hinen Open API.
+
+## Installation
+
+```bash
+pip install hinen-open-api
+```
+
+## Usage
+
+```python
+import asyncio
+from hinen_open_api import HinenOpen
+
+async def main():
+    async with HinenOpen(
+        host="https://api.hinen.com",
+        app_id="your_app_id",
+        app_secret="your_app_secret"
+    ) as client:
+        # Set user authentication if needed
+        await client.set_user_authentication(
+            token="user_token",
+            refresh_token="refresh_token"
+        )
+        
+        # Use the client to make requests
+        print("Hinen Open API client initialized successfully!")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Development
+
+To install the package in development mode:
+
+```bash
+pip install -e .
+```
+
+To run tests:
+
+```bash
+pytest tests/
+```
+
+This project uses `pyproject.toml` for packaging configuration instead of `setup.py`.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hinen_open_api-1.0.0/README.md

@@ -0,0 +1,54 @@
+# Hinen Open API Client
+
+A Python client library for the Hinen Open API.
+
+## Installation
+
+```bash
+pip install hinen-open-api
+```
+
+## Usage
+
+```python
+import asyncio
+from hinen_open_api import HinenOpen
+
+async def main():
+    async with HinenOpen(
+        host="https://api.hinen.com",
+        app_id="your_app_id",
+        app_secret="your_app_secret"
+    ) as client:
+        # Set user authentication if needed
+        await client.set_user_authentication(
+            token="user_token",
+            refresh_token="refresh_token"
+        )
+        
+        # Use the client to make requests
+        print("Hinen Open API client initialized successfully!")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Development
+
+To install the package in development mode:
+
+```bash
+pip install -e .
+```
+
+To run tests:
+
+```bash
+pytest tests/
+```
+
+This project uses `pyproject.toml` for packaging configuration instead of `setup.py`.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hinen_open_api-1.0.0/hinen_open_api/__init__.py

@@ -0,0 +1,5 @@
+"""Hinen Open API client library."""
+
+__version__ = "1.0.0"
+
+from .client import HinenOpen  

hinen_open_api-1.0.0/hinen_open_api/client.py

@@ -0,0 +1,246 @@
+"""Hinen Open API client."""
+
+import asyncio
+from collections.abc import AsyncGenerator, Callable, Coroutine
+from logging import getLogger
+from typing import Any, TypeVar
+
+from aiohttp import ClientError, ClientResponse, ClientSession
+from yarl import URL
+from .exceptions import (
+    ForbiddenError,
+    HinenAPIError,
+    HinenBackendError,
+    HinenResourceNotFoundError,
+    UnauthorizedError,
+)
+from .models import HinenDeviceControl, HinenDeviceDetail, HinenDeviceInfo
+
+T = TypeVar("T")
+
+class HinenOpen:
+    """HinenOpen API client."""
+
+    _close_session: bool = False
+
+    logger = getLogger(__name__)
+
+    _user_auth_token: str | None = None
+    _user_auth_refresh_token: str | None = None
+    _has_user_auth = False
+
+    def __init__(
+        self,
+        host: str | None = None,
+        app_id: str | None = None,
+        app_secret: str | None = None,
+        session: ClientSession | None = None,
+        session_timeout: int = 10,
+        auto_refresh_auth: bool | None = None,
+    ) -> None:
+        """Initialize Hinen Open object."""
+        self.host = host
+        self.app_id = app_id
+        self.app_secret = app_secret
+        if session is None:
+            session = ClientSession()
+        self.session = session
+        self.session_timeout = session_timeout
+
+        if auto_refresh_auth is None:
+            self.auto_refresh_auth = app_id is not None and app_secret is not None
+        else:
+            self.auto_refresh_auth = auto_refresh_auth
+
+        self._r_lookup: dict[
+            str,
+            Callable[
+                [ClientSession, str, dict[str, Any] | None],
+                Coroutine[Any, Any, ClientResponse],
+            ],
+        ] = {
+            "get": self._api_get_request,
+            "put": self._api_put_request,
+        }
+
+    async def _api_get_request(
+        self,
+        session: ClientSession,
+        url: str,
+        data: dict[str, Any] | None = None,
+    ) -> ClientResponse:
+        """Make GET request with authorization."""
+        headers = {"Authorization": f"{self._user_auth_token}"}
+        self.logger.debug("making GET request to %s", url)
+        response = await session.get(url, headers=headers, json=data)
+        return await self._check_request_return(response)
+
+    async def _api_put_request(
+        self,
+        session: ClientSession,
+        url: str,
+        data: dict[str, Any] | None = None,
+    ) -> ClientResponse:
+        """Make post request with authorization."""
+        headers = {"Authorization": f"{self._user_auth_token}"}
+        self.logger.debug("making PUT request to %s", url)
+        response = await session.put(url, headers=headers, json=data)
+        return await self._check_request_return(response)
+
+    async def _check_request_return(self, response: ClientResponse) -> ClientResponse:
+        if response.status == 500:
+            msg = (await response.json()).get("msg")
+            traceId = (await response.json()).get("traceId")
+            raise HinenBackendError(
+                "Internal Server Error"
+                + ("" if msg is None else f" - {msg!s}")
+                + ("" if traceId is None else f" - {traceId!s}"),
+            )
+        if response.status == 400:
+            msg = (await response.json()).get("msg")
+            traceId = (await response.json()).get("traceId")
+            raise HinenBackendError(
+                "Bad Request"
+                + ("" if msg is None else f" - {msg!s}")
+                + ("" if traceId is None else f" - {traceId!s}"),
+            )
+        if response.status == 404:
+            raise HinenResourceNotFoundError
+        if response.status == 401:
+            raise UnauthorizedError
+        if response.status == 403:
+            response_json = await response.json()
+            error_message = response_json["error"]["errors"][0]["message"]
+            raise ForbiddenError(error_message)
+        if 400 <= response.status < 500:
+            try:
+                response.raise_for_status()
+            except ClientError as exc:
+                raise HinenAPIError from exc
+        if (await response.json()).get("code") != "00000":
+            msg = (await response.json()).get("msg")
+            traceId = (await response.json()).get("traceId")
+            raise HinenBackendError(
+                ("" if msg is None else f" - {msg!s}")
+                + ("" if traceId is None else f" - {traceId!s}")
+            )
+
+        return response
+
+    async def set_user_authentication(
+        self,
+        token: str,
+        refresh_token: str | None = None,
+    ) -> None:
+        """Set a user token to be used.
+
+        :param token: the generated user token
+        :param refresh_token: The generated refresh token, has to be provided if
+        :attr:`auto_refresh_auth` is True |default| :code:`None`
+        """
+        if refresh_token is None and self.auto_refresh_auth:
+            msg = "refresh_token has to be provided when auto_refresh_auth is True"
+            raise ValueError(msg)
+
+        self._user_auth_token = token
+        self._user_auth_refresh_token = refresh_token
+        self._has_user_auth = True
+
+    async def _build_generator(
+        self,
+        req: str,
+        url: str,
+        url_params: dict[str, Any],
+        return_type: T,
+        body_data: dict[str, Any] | None = None,
+    ) -> AsyncGenerator[T]:
+        method = self._r_lookup.get(req.lower(), self._api_get_request)
+        if not self.session:
+            self.session = ClientSession()
+            self._close_session = True
+        try:
+            _url = f"{self.host}{url}"
+            if url_params:
+                _url = await self.build_url(_url, url_params)
+            async with asyncio.timeout(self.session_timeout):
+                response = await method(self.session, _url, body_data)
+
+            if response.content_type != "application/json":
+                msg = "Unexpected response type"
+                raise HinenAPIError(msg)
+            resp_data = (await response.json()).get("data")
+
+            if not isinstance(resp_data, list):
+                resp_data = [resp_data]
+            if not return_type:
+                return
+            for entry in resp_data:
+                yield return_type(**entry)  # type: ignore[operator]
+        except TimeoutError as exc:
+            msg = "Timeout occurred"
+            raise HinenBackendError(msg) from exc
+
+    async def build_url(self, url: str, params: dict[str, Any], **kwargs: Any) -> str:
+        """Build url from host and path."""
+        return str(URL(url).with_query(**params).update_query(**kwargs))
+
+    async def get_device_infos(self) -> AsyncGenerator[HinenDeviceInfo]:
+        """Get device infos."""
+        async for item in self._build_generator(
+            "GET",
+            "/iot-device/open-api/devices",
+            {},
+            HinenDeviceInfo,
+        ):
+            yield item  # type: ignore[misc]
+
+    async def get_device_details(
+        self,
+        device_ids: list[str],
+    ) -> AsyncGenerator[HinenDeviceDetail]:
+        """Get device infos."""
+        async for item in self._build_generator(
+            "GET",
+            f"/iot-device/open-api/devices/info/{device_ids[0]}",
+            {},
+            HinenDeviceDetail,
+        ):
+            yield item  # type: ignore[misc]
+
+    async def set_property(self, value: Any, device_id: str, key: str):
+        """Set device work mode."""
+        hinen_device_control = HinenDeviceControl(
+            deviceId=device_id, map={key: value}
+        )
+
+        async for _ in self._build_generator(
+            "PUT",
+            "/iot-device/open-api/devices/property_set",
+            {},
+            None,
+            hinen_device_control.model_dump(by_alias=True),
+        ):
+            pass
+
+    async def close(self) -> None:
+        """Close open client session."""
+        if self.session and self._close_session:
+            await self.session.close()
+
+    async def __aenter__(self) -> "HinenOpen":
+        """Async enter.
+
+        Returns:
+        ----
+            The Hinen Open object.
+        """
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        """Async exit.
+
+        Args:
+        ----
+            _exc_info: Exec type.
+        """
+        await self.close()

hinen_open_api-1.0.0/hinen_open_api/exceptions.py

@@ -0,0 +1,49 @@
+"""Hinen Open API exceptions."""
+
+
+class HinenAPIError(Exception):
+    """Base class for all Hinen API errors."""
+
+
+class HinenBackendError(HinenAPIError):
+    """Raised when the Hinen backend returns an error."""
+
+
+class HinenResourceNotFoundError(HinenAPIError):
+    """Raised when a resource is not found."""
+
+
+class UnauthorizedError(HinenAPIError):
+    """Raised when the user is not authorized."""
+
+
+class ForbiddenError(HinenAPIError):
+    """Raised when the user is forbidden from accessing a resource."""
+
+
+class InvalidCredentialsError(HinenAPIError):
+    """Raised when the credentials are invalid."""
+
+
+class InvalidClientIdError(HinenAPIError):
+    """Raised when the client ID is invalid."""
+
+
+class InvalidClientSecretError(HinenAPIError):
+    """Raised when the client secret is invalid."""
+
+
+class InvalidGrantError(HinenAPIError):
+    """Raised when the grant is invalid."""
+
+
+class InvalidScopeError(HinenAPIError):
+    """Raised when the scope is invalid."""
+
+
+class ExpiredTokenError(HinenAPIError):
+    """Raised when the token is expired."""
+
+
+class InvalidTokenError(HinenAPIError):
+    """Raised when the token is invalid."""

hinen_open_api-1.0.0/hinen_open_api/models.py

@@ -0,0 +1,59 @@
+"""Models for Hinen Open API."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class HinenDeviceInfo(BaseModel):
+    """hinen device info."""
+
+    id: str = Field(...)
+    device_name: str = Field(..., alias="deviceName")
+    serial_number: str = Field(..., alias="serialNumber")
+
+    @property
+    def get_device_name(self) -> str:
+        """Return device_name."""
+        return self.device_name
+
+    @property
+    def get_id(self) -> str:
+        """Return id."""
+        return self.id
+
+    @property
+    def get_serial_number(self) -> str:
+        """Return serial_number."""
+        return self.serial_number
+
+class HinenDeviceProperty(BaseModel):
+    """hinen device property."""
+
+    identifier: str = Field(..., description="property key")
+    name: str = Field(..., description="name")
+    value: Any = Field(..., description="value")
+
+
+class HinenDeviceDetail(BaseModel):
+    """hinen device detail."""
+
+    id: str = Field(...)
+    device_name: str = Field(..., alias="deviceName")
+    serial_number: str = Field(..., alias="serialNumber")
+    status: int = Field(...)
+    alert_status: int = Field(..., alias="alertStatus")
+    properties: list[HinenDeviceProperty] = Field(..., alias="properties")
+
+
+class HinenDeviceControl(BaseModel):
+    """hinen device control."""
+
+    device_id: str = Field(..., alias="deviceId", description="设备ID")
+    map: dict[str, Any] = Field(..., description="控制参数映射")
+
+    class Config:
+        """配置信息."""
+
+        allow_population_by_field_name = True
+

hinen_open_api-1.0.0/hinen_open_api/utils.py

@@ -0,0 +1,17 @@
+"""Hinen Open API utils."""
+
+import re
+from typing import Any
+
+class RespUtil:
+    """Utility functions for responses."""
+
+    @staticmethod
+    def convert_to_snake_case(data: dict[str, Any]) -> dict[str, str]:
+        """Converts the dictionary's keys from camel naming to underscore naming."""
+
+        def camel_to_snake(name: str) -> str:
+            name = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
+            return re.sub("([a-z0-9])([A-Z])", r"\1_\2", name).lower()
+
+        return {camel_to_snake(k): v for k, v in data.items()}

hinen_open_api-1.0.0/hinen_open_api.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: hinen-open-api
+Version: 1.0.0
+Summary: Hinen Open API Client
+Author: Hinen-WeiFeng
+License: MIT
+Project-URL: Homepage, https://github.com/Hinen-IoT/hinen_open_api.git
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0.0,>=3.8.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: yarl<2.0.0,>=1.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.15; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.9; extra == "dev"
+Dynamic: license-file
+
+# Hinen Open API Client
+
+A Python client library for the Hinen Open API.
+
+## Installation
+
+```bash
+pip install hinen-open-api
+```
+
+## Usage
+
+```python
+import asyncio
+from hinen_open_api import HinenOpen
+
+async def main():
+    async with HinenOpen(
+        host="https://api.hinen.com",
+        app_id="your_app_id",
+        app_secret="your_app_secret"
+    ) as client:
+        # Set user authentication if needed
+        await client.set_user_authentication(
+            token="user_token",
+            refresh_token="refresh_token"
+        )
+        
+        # Use the client to make requests
+        print("Hinen Open API client initialized successfully!")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Development
+
+To install the package in development mode:
+
+```bash
+pip install -e .
+```
+
+To run tests:
+
+```bash
+pytest tests/
+```
+
+This project uses `pyproject.toml` for packaging configuration instead of `setup.py`.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.