switchbot-api 2.3.0__tar.gz → 2.4.0__tar.gz

{switchbot_api-2.3.0 → switchbot_api-2.4.0}/PKG-INFO

@@ -1,8 +1,7 @@
 Metadata-Version: 2.3
 Name: switchbot_api
-Version: 2.3.0
+Version: 2.4.0
 Summary: An asynchronous library to use Switchbot API
-Home-page: https://github.com/SeraphicCorp/py-switchbot-api
 License: MIT
 Author: Ravaka Razafimanantsoa
 Author-email: contact@ravaka.dev
@@ -13,7 +12,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: aiohttp (>=3.8.4,<4.0.0)
+Requires-Dist: aiohttp (>=3.0.0)
 Project-URL: Repository, https://github.com/SeraphicCorp/py-switchbot-api
 Description-Content-Type: text/markdown
 
@@ -46,3 +45,4 @@ poetry install
 poetry run black switchbot_api/
 poetry run mypy switchbot_api/
 ```
+

{switchbot_api-2.3.0 → switchbot_api-2.4.0}/README.md

@@ -26,4 +26,4 @@ poetry install
 ```bash
 poetry run black switchbot_api/
 poetry run mypy switchbot_api/
-```
+```

switchbot_api-2.4.0/pyproject.toml

@@ -0,0 +1,106 @@
+[tool.poetry]
+name = "switchbot_api"
+version = "2.4.0"
+description = "An asynchronous library to use Switchbot API"
+authors = ["Ravaka Razafimanantsoa <contact@ravaka.dev>"]
+license = "MIT"
+readme = "README.md"
+packages = [{include = "switchbot_api"}]
+repository = "https://github.com/SeraphicCorp/py-switchbot-api"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+aiohttp = ">=3.0.0"
+
+
+[tool.poetry.group.dev.dependencies]
+coverage = {version = "7.6.10", extras = ["toml"]}
+mypy = "^1.4.1"
+pytest-asyncio = "^0.25.2"
+pytest-freezer = "^0.4.9"
+pytest = "^8.3.4"
+syrupy = "^4.8.1"
+aioresponses = "^0.7.7"
+ruff = "^0.9.2"
+pytest-cov = "^6.0.0"
+covdefaults = "^2.3.0"
+codespell = "^2.3.0"
+pre-commit = "^4.0.1"
+pre-commit-hooks = "^5.0.0"
+yamllint = "^1.35.1"
+
+[tool.mypy]
+# Specify the target platform details in config, so your developers are
+# free to run mypy on Windows, Linux, or macOS and get consistent
+# results.
+platform = "linux"
+python_version = "3.11"
+
+# show error messages from unrelated files
+follow_imports = "normal"
+
+# suppress errors about unsatisfied imports
+ignore_missing_imports = true
+
+# be strict
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+strict_optional = true
+warn_incomplete_stub = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+
+[tool.pytest.ini_options]
+addopts = "--cov"
+asyncio_mode = "auto"
+pythonpath = ["switchbot_api"]
+
+[tool.coverage.report]
+skip_empty = true
+show_missing = true
+fail_under = 50
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["switchbot_api"]
+
+
+[tool.ruff.lint]
+ignore = [
+  "ANN401", # Opinioated warning on disallowing dynamically typed expressions
+  "COM812", # Conflicts with other rules
+  "D203", # Conflicts with other rules
+  "D213", # Conflicts with other rules
+  "D417", # False positives in some occasions
+  "ISC001", # Conflicts with other rules
+  "PLR2004", # Just annoying, not really useful
+]
+select = ["ALL"]
+
+[tool.ruff.lint.flake8-pytest-style]
+fixture-parentheses = false
+mark-parentheses = false
+
+[tool.ruff.lint.isort]
+known-first-party = ["switchbot_api"]
+force-sort-within-sections = true
+split-on-trailing-comma = false
+combine-as-imports = true
+
+[tool.ruff.lint.mccabe]
+max-complexity = 25
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

{switchbot_api-2.3.0 → switchbot_api-2.4.0}/switchbot_api/__init__.py

@@ -1,16 +1,26 @@
 """Tools to query the SwitchBot API."""
 
+from __future__ import annotations
+
 import base64
+from dataclasses import dataclass
+from enum import Enum, StrEnum
 import hashlib
 import hmac
 import logging
+import socket
 import time
+from typing import Any, Self, TypeVar
 import uuid
-from dataclasses import dataclass
-from enum import Enum
-from typing import TypeVar
 
-from aiohttp import ClientSession
+from aiohttp import ClientError, ClientResponseError, ClientSession
+from aiohttp.hdrs import METH_GET, METH_POST
+
+from switchbot_api.exceptions import (
+    SwitchBotAuthenticationError,
+    SwitchBotConnectionError,
+    SwitchBotDeviceOfflineError,
+)
 
 _API_HOST = "https://api.switch-bot.com"
 
@@ -18,18 +28,6 @@ _LOGGER = logging.getLogger(__name__)
 NON_OBSERVED_REMOTE_TYPES = ["Others"]
 
 
-class CannotConnect(Exception):
-    """Cannot connect to the SwitchBot API."""
-
-
-class InvalidAuth(Exception):
-    """Invalid auth for the SwitchBot API."""
-
-
-class DeviceOffline(Exception):
-    """Device currently offline."""
-
-
 @dataclass
 class Device:
     """Device."""
@@ -39,7 +37,7 @@ class Device:
     device_type: str
     hub_device_id: str
 
-    def __init__(self, **kwargs) -> None:
+    def __init__(self, **kwargs: Any) -> None:
         """Initialize."""
         self.device_id = kwargs["deviceId"]
         self.device_name = kwargs["deviceName"]
@@ -56,7 +54,7 @@ class Remote:
     device_type: str
     hub_device_id: str
 
-    def __init__(self, **kwargs) -> None:
+    def __init__(self, **kwargs: Any) -> None:
         """Initialize."""
         self.device_id = kwargs["deviceId"]
         self.device_name = kwargs["deviceName"]
@@ -72,7 +70,7 @@ class PowerState(Enum):
 
 
 class Commands(Enum):
-    pass
+    """Base command class."""
 
 
 class CommonCommands(Commands):
@@ -97,7 +95,11 @@ class AirConditionerCommands(Commands):
 class HumidifierCommands(Commands):
     """Humidifier commands."""
 
-    SET_MODE = "setMode"  # parameter: auto, set to Auto Mode, 101, set atomization efficiency to 34%,102, set atomization efficiency to 67%, 103, set atomization efficiency to 100%
+    # parameter: auto, set to Auto Mode
+    # 101, set atomization efficiency to 34%
+    # 102, set atomization efficiency to 67%
+    # 103, set atomization efficiency to 100%
+    SET_MODE = "setMode"
 
 
 class TVCommands(Commands):
@@ -140,6 +142,14 @@ class FanCommands(Commands):
     HIGH_SPEED = "highSpeed"
 
 
+class BatteryCirculatorFanCommands(Commands):
+    """Command types for [Battery Circulator Fan] API."""
+
+    SET_WIND_SPEED = "setWindSpeed"
+    SET_WIND_MODE = "setWindMode"
+    SET_NIGHT_LIGHT_MODE = "setNightLightMode"
+
+
 class LightCommands(Commands):
     """Light commands."""
 
@@ -148,7 +158,7 @@ class LightCommands(Commands):
 
 
 class LockCommands(Commands):
-    """Lock commands"""
+    """Lock commands."""
 
     LOCK = "lock"
     UNLOCK = "unlock"
@@ -178,25 +188,43 @@ class BotCommands(Commands):
     PRESS = "press"
 
 
+class BatteryCirculatorFanMode(StrEnum):
+    """Fan mode types [Battery Circulator Fan] API."""
+
+    DIRECT = "direct"
+    NATURAL = "natural"
+    SLEEP = "sleep"
+    BABY = "baby"
+
+
 T = TypeVar("T", bound=CommonCommands)
 
 
 class SwitchBotAPI:
     """SwitchBot API."""
 
-    def __init__(self, token: str, secret: str) -> None:
+    _close_session: bool = False
+
+    def __init__(
+        self, token: str, secret: str, session: ClientSession | None = None
+    ) -> None:
         """Initialize."""
         self.token = token
         self.secret = secret
+        self.session = session
 
-    def make_headers(self, token: str, secret: str):
+    def make_headers(self, token: str, secret: str) -> dict[str, Any]:
         """Make headers."""
         nonce = uuid.uuid4()
         timestamp = int(round(time.time() * 1000))
         string_to_sign = bytes(f"{token}{timestamp}{nonce}", "utf-8")
         secret_bytes = bytes(secret, "utf-8")
 
-        sign = base64.b64encode(hmac.new(secret_bytes, msg=string_to_sign, digestmod=hashlib.sha256).digest())
+        sign = base64.b64encode(
+            hmac.new(
+                secret_bytes, msg=string_to_sign, digestmod=hashlib.sha256
+            ).digest()
+        )
 
         return {
             "Authorization": token,
@@ -207,80 +235,95 @@ class SwitchBotAPI:
             "nonce": str(nonce),
         }
 
-    async def _request(self, path: str = "", callback: str = "get", json=None):
-        async with ClientSession() as session:
-            async with getattr(session, callback)(
+    async def _request(
+        self, method: str, path: str, json: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        if not self.session:
+            self.session = ClientSession()
+            self._close_session = True
+        try:
+            response = await self.session.request(
+                method,
                 f"{_API_HOST}/v1.1/{path}",
                 headers=self.make_headers(self.token, self.secret),
                 json=json,
-            ) as response:
-                if response.status == 403:
-                    raise InvalidAuth()
-
-                body = await response.json()
-
-                if response.status >= 400:
-                    raise CannotConnect()
-
-                match body.get("statusCode"):
-                    case 100:
-                        return body.get("body")
-                    case 161 | 171:
-                        # SwitchBot docs claim that 161 is the code for device
-                        # being offline, and 171 for a _hub_ being offline.
-                        # In testing, the Plug Mini (JP) return 171 when not
-                        # online too.
-                        raise DeviceOffline()
-                    case _:
-                        _LOGGER.error("Error %s: %s", response.status, body)
-                        raise CannotConnect()
+            )
+        except (
+            ClientError,
+            ClientResponseError,
+            socket.gaierror,
+        ) as exception:
+            msg = "Error occurred while communicating with the SwitchBot API"
+            raise SwitchBotConnectionError(msg) from exception
+        if response.status == 403:
+            raise SwitchBotAuthenticationError
+
+        body = await response.json()
+
+        if response.status >= 400:
+            _LOGGER.error("Error %d: %s", response.status, body)
+            raise SwitchBotConnectionError
+
+        match body.get("statusCode"):
+            case 100:
+                return body["body"]  # type: ignore[no-any-return]
+            case 161 | 171:
+                # SwitchBot docs claim that 161 is the code for device
+                # being offline, and 171 for a _hub_ being offline.
+                # In testing, the Plug Mini (JP) return 171 when not
+                # online too.
+                raise SwitchBotDeviceOfflineError
+            case _:
+                _LOGGER.error("Error %d: %s", response.status, body)
+                raise SwitchBotConnectionError
 
     async def list_devices(self) -> list[Device | Remote]:
         """List devices."""
-        body = await self._request("devices")
+        body = await self._request(METH_GET, "devices")
         _LOGGER.debug("Devices: %s", body)
-        devices = [Device(**device) for device in body.get("deviceList")]
+        devices = [Device(**device) for device in body.get("deviceList")]  # type: ignore[union-attr]
         remotes = [
             Remote(**remote)
-            for remote in body.get("infraredRemoteList")
+            for remote in body.get("infraredRemoteList")  # type: ignore[union-attr]
             if remote.get("remoteType") not in NON_OBSERVED_REMOTE_TYPES
         ]
         return [*devices, *remotes]
 
-    async def get_status(self, device_id: str):
+    async def get_status(self, device_id: str) -> dict[str, Any]:
         """No status for IR devices."""
-        body = await self._request(f"devices/{device_id}/status")
-        return body
+        return await self._request(METH_GET, f"devices/{device_id}/status")
 
-    async def get_webook_configuration(self):
+    async def get_webook_configuration(self) -> dict[str, Any]:
         """List webhooks."""
         json = {"action": "queryUrl"}
-        return await self._request("webhook/queryWebhook", callback="post", json=json)
+        return await self._request(METH_POST, "webhook/queryWebhook", json=json)
 
-    async def setup_webhook(self, url: str):
-        """Setup webhook to receive device status updates."""
+    async def setup_webhook(self, url: str) -> None:
+        """Set up webhook to receive device status updates."""
         json = {"deviceList": "ALL", "action": "setupWebhook", "url": url}
-        await self._request("webhook/setupWebhook", callback="post", json=json)
+        await self._request(METH_POST, "webhook/setupWebhook", json=json)
 
-    async def delete_webhook(self, url: str):
+    async def delete_webhook(self, url: str) -> None:
         """Delete webhook."""
         json = {"action": "deleteWebhook", "url": url}
-        await self._request("webhook/deleteWebhook", callback="post", json=json)
+        await self._request(METH_POST, "webhook/deleteWebhook", json=json)
 
     async def send_command(
         self,
         device_id: str,
         command: T | str,
         command_type: str = "command",
-        parameters: dict | str = "default",
-    ):
+        parameters: dict | str = "default",  # type: ignore[type-arg]
+    ) -> None:
         """Send command to device.
 
         Args:
             device_id (str): The ID of the device.
             command (string | extends CommonCommands): The command to be sent.
-            command_type (str, optional): The type of the command. Defaults to "command".
-            parameters (dict | str, optional): The parameters for the command. Defaults to "default".
+            command_type (str, optional): The type of the command.
+            Defaults to "command".
+            parameters (dict | str, optional): The parameters for the command.
+            Defaults to "default".
 
         Example JSON:
             {
@@ -288,10 +331,36 @@ class SwitchBotAPI:
                 "command": "ボタン", // the name of the customized button
                 "parameter": "default"
             }
+
         """
         json = {
             "commandType": command_type,
             "command": command.value if isinstance(command, Commands) else command,
             "parameter": parameters,
         }
-        await self._request(f"devices/{device_id}/commands", callback="post", json=json)
+        await self._request(METH_POST, f"devices/{device_id}/commands", json=json)
+
+    async def close(self) -> None:
+        """Close the client session."""
+        if self.session and self._close_session:
+            await self.session.close()
+
+    async def __aenter__(self) -> Self:
+        """Async enter.
+
+        Returns
+        -------
+            The SwitchBotAPI object.
+
+        """
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        """Async exit.
+
+        Args:
+        ----
+            _exc_info: Exec type.
+
+        """
+        await self.close()

switchbot_api-2.4.0/switchbot_api/exceptions.py

@@ -0,0 +1,17 @@
+"""Exceptions for the SwitchBot API."""
+
+
+class SwitchBotError(Exception):
+    """General SwitchBot error occurred."""
+
+
+class SwitchBotConnectionError(SwitchBotError):
+    """Cannot connect to the SwitchBot API."""
+
+
+class SwitchBotAuthenticationError(SwitchBotError):
+    """Invalid auth for the SwitchBot API."""
+
+
+class SwitchBotDeviceOfflineError(SwitchBotError):
+    """Device currently offline."""

switchbot_api-2.3.0/pyproject.toml

@@ -1,51 +0,0 @@
-[tool.poetry]
-name = "switchbot_api"
-version = "2.3.0"
-description = "An asynchronous library to use Switchbot API"
-authors = ["Ravaka Razafimanantsoa <contact@ravaka.dev>"]
-license = "MIT"
-readme = "README.md"
-packages = [{include = "switchbot_api"}]
-repository = "https://github.com/SeraphicCorp/py-switchbot-api"
-
-[tool.poetry.dependencies]
-python = "^3.10"
-aiohttp = "^3.8.4"
-
-
-[tool.poetry.group.dev.dependencies]
-pytest = "^7.2.2"
-flake8 = "^6.0.0"
-black = ">=23.1,<25.0"
-coverage = "^7.2.1"
-parameterized = "^0.8.1"
-isort = "^5.12.0"
-mypy = "^1.4.1"
-
-[tool.black]
-line-length = 120
-
-[tool.isort]
-profile = "black"
-
-[tool.mypy]
-check_untyped_defs = true
-
-[tool.pytest.ini_options]
-pythonpath = ["switchbot_api"]
-
-[tool.coverage.run]
-branch = true
-omit = [
-    "*/test_*.py",
-]
-
-[tool.coverage.report]
-skip_empty = true
-show_missing = true
-fail_under = 0
-
-
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"