diff --git a/examples/switchbot/switchbot_client/switchbot_base_client.py b/examples/switchbot/switchbot_client/switchbot_base_client.py index 8aae030..5940c2d 100644 --- a/examples/switchbot/switchbot_client/switchbot_base_client.py +++ b/examples/switchbot/switchbot_client/switchbot_base_client.py @@ -12,31 +12,113 @@ class SwitchBotClientProtocol(Protocol): + """ + Protocol defining the interface for SwitchBot client implementations. + SwitchBotクライアントの実装に必要なインターフェースを定義するプロトコル。 + """ def list_devices(self) -> SBListDeviceResponse: + """ + List all available SwitchBot devices. + 利用可能なすべてのSwitchBotデバイスを一覧表示する。 + + Returns: + SBListDeviceResponse: Response containing list of devices. + SBListDeviceResponse: デバイスリストを含むレスポンス。 + """ pass def get_device_status(self, device_id: str): + """ + Get the current status of a specific device. + 特定のデバイスの現在のステータスを取得する。 + + Args: + device_id (str): ID of the device to query. + device_id (str): クエリするデバイスのID。 + """ pass def _get_device_status_typed[T: BaseModel](self, device_id: str, cls: Type[T]) -> T: + """ + Get device status with type validation using Pydantic models. + Pydanticモデルを使用して型検証付きでデバイスステータスを取得する。 + + Args: + device_id (str): ID of the device to query. + device_id (str): クエリするデバイスのID。 + cls (Type[T]): Pydantic model class for response validation. + cls (Type[T]): レスポンス検証用のPydanticモデルクラス。 + + Returns: + T: Validated device status response of type T. + T: 型Tの検証済みデバイスステータスレスポンス。 + """ pass def commands(self, device_id: str, command: str, command_type: str = "command", parameter: str | int = "default"): + """ + Send a command to a specific device. + 特定のデバイスにコマンドを送信する。 + + Args: + device_id (str): ID of the target device. + device_id (str): ターゲットデバイスのID。 + command (str): Command to execute. + command (str): 実行するコマンド。 + command_type (str): Type of command (default: "command"). + command_type (str): コマンドの種類（デフォルト: "command"）。 + parameter (str | int): Command parameter (default: "default"). + parameter (str | int): コマンドパラメータ（デフォルト: "default"）。 + """ pass def execute_scene(self, scene_id: str): + """ + Execute a specific scene by its ID. + IDで指定したシーンを実行する。 + + Args: + scene_id (str): ID of the scene to execute. + scene_id (str): 実行するシーンのID。 + """ pass def list_scenes(self): + """ + List all available scenes. + 利用可能なすべてのシーンを一覧表示する。 + """ pass class SwitchBotBaseClient(SwitchBotClientProtocol): + """ + Base implementation of the SwitchBot client providing core API functionality. + コアAPIの機能を提供するSwitchBotクライアントの基本実装。 + """ def __init__(self, token: str, secret: str): + """ + Initialize the SwitchBot client with authentication credentials. + 認証情報でSwitchBotクライアントを初期化する。 + + Args: + token (str): SwitchBot API token. + token (str): SwitchBot APIトークン。 + secret (str): SwitchBot API secret. + secret (str): SwitchBot APIシークレット。 + """ self._token = token self._secret = secret self._api_url = "https://api.switch-bot.com/v1.1" def _generate_sign(self): + """ + Generate authentication signature for API requests. + APIリクエスト用の認証署名を生成する。 + + Returns: + tuple: Token, timestamp, nonce, and signature. + tuple: トークン、タイムスタンプ、ノンス、署名。 + """ token = self._token secret = self._secret nonce = uuid.uuid4() @@ -50,6 +132,14 @@ def _generate_sign(self): return token, t, nonce, sign def _generate_headers(self): + """ + Generate HTTP headers for API requests including authentication. + 認証情報を含むAPIリクエスト用のHTTPヘッダーを生成する。 + + Returns: + dict: Headers required for API authentication. + dict: API認証に必要なヘッダー。 + """ token, t, nonce, sign = self._generate_sign() return { 'Authorization': token, @@ -61,18 +151,62 @@ def _generate_headers(self): } def list_devices(self) -> SBListDeviceResponse: + """ + List all available SwitchBot devices. + 利用可能なすべてのSwitchBotデバイスを一覧表示する。 + + Returns: + SBListDeviceResponse: Response containing list of devices. + SBListDeviceResponse: デバイスリストを含むレスポンス。 + """ res = httpx.get(f'{self._api_url}/devices', headers=self._generate_headers()) return SBListDeviceResponse.model_validate(res.json()) def get_device_status(self, device_id: str): + """ + Get the current status of a specific device. + 特定のデバイスの現在のステータスを取得する。 + + Args: + device_id (str): ID of the device to query. + device_id (str): クエリするデバイスのID。 + """ res = httpx.get(f'{self._api_url}/devices/{device_id}/status', headers=self._generate_headers()) return res.json() def _get_device_status_typed[T: BaseModel](self, device_id: str, cls: Type[T]) -> T: + """ + Get device status with type validation using Pydantic models. + Pydanticモデルを使用して型検証付きでデバイスステータスを取得する。 + + Args: + device_id (str): ID of the device to query. + device_id (str): クエリするデバイスのID。 + cls (Type[T]): Pydantic model class for response validation. + cls (Type[T]): レスポンス検証用のPydanticモデルクラス。 + + Returns: + T: Validated device status response of type T. + T: 型Tの検証済みデバイスステータスレスポンス。 + """ res = self.get_device_status(device_id) return cls.model_validate(res) def commands(self, device_id: str, command: str, command_type: str = "command", parameter: str | int = "default"): + """ + Send a command to a specific device. + 特定のデバイスにコマンドを送信する。 + + Args: + device_id (str): ID of the target device. + device_id (str): ターゲットデバイスのID。 + command (str): Command to execute. + command (str): 実行するコマンド。 + command_type (str): Type of command (default: "command"). + command_type (str): コマンドの種類（デフォルト: "command"）。 + parameter (str | int): Command parameter (default: "default"). + parameter (str | int): コマンドパラメータ（デフォルト: "default"）。 + """ request_body = { "command_type": command_type, "command": command, @@ -82,10 +216,26 @@ def commands(self, device_id: str, command: str, command_type: str = "command", return res.json() def execute_scene(self, scene_id: str): + """ + Execute a specific scene by its ID. + IDで指定したシーンを実行する。 + + Args: + scene_id (str): ID of the scene to execute. + scene_id (str): 実行するシーンのID。 + """ res = httpx.post(f'{self._api_url}/scenes/{scene_id}/execute', headers=self._generate_headers()) return res.json() def list_scenes(self): + """ + List all available scenes. + 利用可能なすべてのシーンを一覧表示する。 + + Returns: + dict: Response containing list of scenes. + dict: シーンリストを含むレスポンス。 + """ res = httpx.get(f'{self._api_url}/scenes', headers=self._generate_headers()) return res.json() diff --git a/examples/switchbot/switchbot_client/switchbot_client.py b/examples/switchbot/switchbot_client/switchbot_client.py index 3b2e543..dc2b002 100644 --- a/examples/switchbot/switchbot_client/switchbot_client.py +++ b/examples/switchbot/switchbot_client/switchbot_client.py @@ -4,12 +4,39 @@ class SwitchBotClient(SwitchBotBaseClient, SwitchBotDeviceOpsMixin, CaseInsensitiveInvokeMixin): + """ + Main SwitchBot client implementation combining base functionality, device operations, and case-insensitive method invocation. + 基本機能、デバイス操作、大文字小文字を区別しないメソッド呼び出しを組み合わせたメインのSwitchBotクライアント実装。 + + This class inherits from: + - SwitchBotBaseClient: Provides core API communication + - SwitchBotDeviceOpsMixin: Adds device-specific operations + - CaseInsensitiveInvokeMixin: Enables case-insensitive method calls + + このクラスは以下のクラスを継承します： + - SwitchBotBaseClient: コアAPIの通信機能を提供 + - SwitchBotDeviceOpsMixin: デバイス固有の操作を追加 + - CaseInsensitiveInvokeMixin: 大文字小文字を区別しないメソッド呼び出しを可能にする + """ def __init__(self, token: str, secret: str): - # 多重継承した場合、super()は最初に指定したクラスのメソッドを呼び出すのでsuperで1個ずらしで呼び出すと、 - # SwitchBotBaseClient -> SwitchBotClientMixin -> CaseInsensitiveInvokeMixin の順に__init__()が呼び出される - # When multiple inheritance, super() calls the method of the first specified class, so if you call it with a shift of one with super(), - # __init__() is called in the order of SwitchBotBaseClient -> SwitchBotClientMixin -> CaseInsensitiveInvokeMixin - super(SwitchBotClient, self).__init__(token, secret) # SwitchBotBaseClient.__init__(self, token, secret) - super(SwitchBotBaseClient, self).__init__() # SwitchBotClientMixin.__init__(self) - super(SwitchBotDeviceOpsMixin, self).__init__() # CaseInsensitiveInvokeMixin.__init__(self) + """ + Initialize the SwitchBot client with authentication credentials. + 認証情報を使用してSwitchBotクライアントを初期化します。 + + Args: + token (str): SwitchBot API token / SwitchBot APIトークン + secret (str): SwitchBot API secret / SwitchBot APIシークレット + + Note: + When using multiple inheritance, super() calls are made in sequence to properly initialize all parent classes: + 多重継承を使用する場合、すべての親クラスを適切に初期化するために、super()呼び出しは順番に行われます： + 1. SwitchBotBaseClient.__init__(token, secret) + 2. SwitchBotDeviceOpsMixin.__init__() + 3. CaseInsensitiveInvokeMixin.__init__() + """ + # Initialize parent classes in sequence + # 親クラスを順番に初期化 + super(SwitchBotClient, self).__init__(token, secret) # SwitchBotBaseClient.__init__(token, secret) + super(SwitchBotBaseClient, self).__init__() # SwitchBotDeviceOpsMixin.__init__() + super(SwitchBotDeviceOpsMixin, self).__init__() # CaseInsensitiveInvokeMixin.__init__() diff --git a/examples/switchbot/switchbot_client/switchbot_mixin.py b/examples/switchbot/switchbot_client/switchbot_mixin.py index a9d8951..6bc473b 100644 --- a/examples/switchbot/switchbot_client/switchbot_mixin.py +++ b/examples/switchbot/switchbot_client/switchbot_mixin.py @@ -12,23 +12,77 @@ class SwitchBotDeviceOpsMixin: """ def _turn_on(self: SwitchBotClientProtocol, device_id: str): + """ + Turn on a SwitchBot device. + SwitchBotデバイスの電源をオンにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self.commands(device_id, "turnOn") def _turn_off(self: SwitchBotClientProtocol, device_id: str): + """ + Turn off a SwitchBot device. + SwitchBotデバイスの電源をオフにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self.commands(device_id, "turnOff") def _toggle(self: SwitchBotClientProtocol, device_id: str): + """ + Toggle the power state of a SwitchBot device. + SwitchBotデバイスの電源状態を切り替える。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self.commands(device_id, "toggle") def _set_brightness(self: SwitchBotClientProtocol, device_id: str, brightness: int): + """ + Set the brightness level of a light device. + 照明デバイスの明るさを設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + brightness (int): Brightness level (1-100). + brightness (int): 明るさレベル（1-100）。 + """ assert 1 <= brightness <= 100, "Invalid brightness, should be 1-100" return self.commands(device_id, "setBrightness", parameter=brightness) def _set_color_temperature(self: SwitchBotClientProtocol, device_id: str, color_temperature: int): + """ + Set the color temperature of a light device. + 照明デバイスの色温度を設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + color_temperature (int): Color temperature in Kelvin (2700-6500). + color_temperature (int): 色温度（ケルビン、2700-6500）。 + """ assert 2700 <= color_temperature <= 6500, "Invalid color temperature, should be 2700-6500" return self.commands(device_id, "setColorTemperature", parameter=color_temperature) def _set_color(self: SwitchBotClientProtocol, device_id: str, color: str): + """ + Set the RGB color of a light device. + 照明デバイスのRGB色を設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + color (str): RGB color in format "R:G:B" (0-255 each). + color (str): RGB色、"R:G:B"形式（各0-255）。 + """ assert re.match(r"\d{1,3}:\d{1,3}:\d{1,3}", color), "Invalid color format, should be '{0-255}:{0-255}:{0-255}'" assert any(0 <= int(c) <= 255 for c in color.split(":")), "Invalid color value, should be 0-255)" return self.commands(device_id, "setColor", parameter=color) @@ -36,124 +90,461 @@ def _set_color(self: SwitchBotClientProtocol, device_id: str, color: str): # Humidifier def humidifier_turn_on(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn on a SwitchBot Humidifier. + SwitchBot加湿器の電源をオンにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_on(device_id) def humidifier_set_mode(self: SwitchBotClientProtocol | Self, device_id: str, mode: str | int): + """ + Set the operation mode of a SwitchBot Humidifier. + SwitchBot加湿器の動作モードを設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + mode (str | int): Mode setting ('auto' or 0-103). + mode (str | int): モード設定（'auto'または0-103）。 + """ assert mode == "auto" or 0 <= int(mode) <= 103, "Invalid mode, should be 'auto' or 0-103" return self.commands(device_id, "set", parameter=mode) def humidifier_turn_off(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn off a SwitchBot Humidifier. + SwitchBot加湿器の電源をオフにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_off(device_id) # Color Bulb def bulb_turn_on(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn on a SwitchBot Color Bulb. + SwitchBotカラー電球の電源をオンにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_on(device_id) def bulb_turn_off(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn off a SwitchBot Color Bulb. + SwitchBotカラー電球の電源をオフにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_off(device_id) def bulb_toggle(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Toggle the power state of a SwitchBot Color Bulb. + SwitchBotカラー電球の電源状態を切り替える。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._toggle(device_id) def bulb_set_brightness(self: SwitchBotClientProtocol | Self, device_id: str, brightness: int): + """ + Set the brightness of a SwitchBot Color Bulb. + SwitchBotカラー電球の明るさを設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + brightness (int): Brightness level (1-100). + brightness (int): 明るさレベル（1-100）。 + """ return self._set_brightness(device_id, brightness) def bulb_set_color_temperature(self: SwitchBotClientProtocol | Self, device_id: str, color_temperature: int): + """ + Set the color temperature of a SwitchBot Color Bulb. + SwitchBotカラー電球の色温度を設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + color_temperature (int): Color temperature in Kelvin (2700-6500). + color_temperature (int): 色温度（ケルビン、2700-6500）。 + """ return self._set_color_temperature(device_id, color_temperature) def bulb_set_color(self: SwitchBotClientProtocol | Self, device_id: str, color: str): + """ + Set the RGB color of a SwitchBot Color Bulb. + SwitchBotカラー電球のRGB色を設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + color (str): RGB color in format "R:G:B" (0-255 each). + color (str): RGB色、"R:G:B"形式（各0-255）。 + """ return self._set_color(device_id, color) # Strip Light def strip_turn_on(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn on a SwitchBot Strip Light. + SwitchBotストリップライトの電源をオンにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_on(device_id) def strip_turn_off(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn off a SwitchBot Strip Light. + SwitchBotストリップライトの電源をオフにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_off(device_id) def strip_toggle(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Toggle the power state of a SwitchBot Strip Light. + SwitchBotストリップライトの電源状態を切り替える。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._toggle(device_id) def strip_set_brightness(self: SwitchBotClientProtocol | Self, device_id: str, brightness: int): + """ + Set the brightness of a SwitchBot Strip Light. + SwitchBotストリップライトの明るさを設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + brightness (int): Brightness level (1-100). + brightness (int): 明るさレベル（1-100）。 + """ return self._set_brightness(device_id, brightness) def strip_set_color_temperature(self: SwitchBotClientProtocol | Self, device_id: str, color_temperature: int): + """ + Set the color temperature of a SwitchBot Strip Light. + SwitchBotストリップライトの色温度を設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + color_temperature (int): Color temperature in Kelvin (2700-6500). + color_temperature (int): 色温度（ケルビン、2700-6500）。 + """ return self._set_color_temperature(device_id, color_temperature) def strip_set_color(self: SwitchBotClientProtocol | Self, device_id: str, color: str): + """ + Set the RGB color of a SwitchBot Strip Light. + SwitchBotストリップライトのRGB色を設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + color (str): RGB color in format "R:G:B" (0-255 each). + color (str): RGB色、"R:G:B"形式（各0-255）。 + """ return self._set_color(device_id, color) # Smart Plug def plug_turn_on(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn on a SwitchBot Smart Plug. + SwitchBotスマートプラグの電源をオンにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_on(device_id) def plug_turn_off(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn off a SwitchBot Smart Plug. + SwitchBotスマートプラグの電源をオフにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_off(device_id) def plug_toggle(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Toggle the power state of a SwitchBot Smart Plug. + SwitchBotスマートプラグの電源状態を切り替える。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._toggle(device_id) # SwitchBot Bot def bot_turn_on(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn on a device using SwitchBot Bot. + SwitchBotボットを使用してデバイスの電源をオンにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_on(device_id) def bot_turn_off(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn off a device using SwitchBot Bot. + SwitchBotボットを使用してデバイスの電源をオフにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_off(device_id) def bot_press(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Trigger a press action on SwitchBot Bot. + SwitchBotボットのプレスアクションを実行する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self.commands(device_id, "press") # Circulator Fan def circulator_fan_turn_on(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn on a SwitchBot Circulator Fan. + SwitchBotサーキュレーターの電源をオンにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_on(device_id) def circulator_fan_turn_off(self: SwitchBotClientProtocol | Self, device_id: str): + """ + Turn off a SwitchBot Circulator Fan. + SwitchBotサーキュレーターの電源をオフにする。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + """ return self._turn_off(device_id) def circulator_fan_set_night_light_mode(self: SwitchBotClientProtocol | Self, device_id: str, mode: str | int): + """ + Set the night light mode of a SwitchBot Circulator Fan. + SwitchBotサーキュレーターのナイトライトモードを設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + mode (str | int): Night light mode ('off', 1 for bright, 2 for dim). + mode (str | int): ナイトライトモード（'off'、1は明るい、2は暗い）。 + """ assert mode in ("off", 1, 2), "Invalid mode, should be 'off' (off), 1 (bright), or 2 (dim)" return self.commands(device_id, "setNightLightMode", parameter=mode) def circulator_fan_set_wind_mode(self: SwitchBotClientProtocol | Self, device_id: str, mode: str): + """ + Set the wind mode of a SwitchBot Circulator Fan. + SwitchBotサーキュレーターの風モードを設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + mode (str): Wind mode ('direct', 'natural', 'sleep', or 'baby'). + mode (str): 風モード（'direct'、'natural'、'sleep'、'baby'）。 + """ assert mode in ("direct", "natural", "sleep", "baby"), \ "Invalid mode, should be 'direct', 'natural', 'sleep', or 'baby'" return self.commands(device_id, "setWindMode", parameter=mode) def circulator_fan_set_wind_speed(self: SwitchBotClientProtocol | Self, device_id: str, speed: int): + """ + Set the wind speed of a SwitchBot Circulator Fan. + SwitchBotサーキュレーターの風速を設定する。 + + Args: + device_id (str): Device ID to control. + device_id (str): 制御するデバイスのID。 + speed (int): Wind speed (1-100). + speed (int): 風速（1-100）。 + """ assert 1 <= speed <= 100, "Invalid speed, should be between 1 and 100" return self.commands(device_id, "setWindSpeed", parameter=speed) # get device status def bot_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[BotStatusBody]: + """ + Get the status of a SwitchBot Bot. + SwitchBotボットのステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[BotStatusBody]: Device status response. + SBDeviceStatusResponse[BotStatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[BotStatusBody]) def meter_pro_co2_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[MeterProCO2StatusBody]: + """ + Get the status of a SwitchBot Meter Pro CO2. + SwitchBotメータープロCO2のステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[MeterProCO2StatusBody]: Device status response. + SBDeviceStatusResponse[MeterProCO2StatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[MeterProCO2StatusBody]) def motion_sensor_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[MotionSensorStatusBody]: + """ + Get the status of a SwitchBot Motion Sensor. + SwitchBotモーションセンサーのステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[MotionSensorStatusBody]: Device status response. + SBDeviceStatusResponse[MotionSensorStatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[MotionSensorStatusBody]) def plug_mini_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[PlugMiniJPStatusBody]: + """ + Get the status of a SwitchBot Plug Mini. + SwitchBotプラグミニのステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[PlugMiniJPStatusBody]: Device status response. + SBDeviceStatusResponse[PlugMiniJPStatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[PlugMiniJPStatusBody]) + def strip_light_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[StripLightStatusBody]: + """ + Get the status of a SwitchBot Strip Light. + SwitchBotストリップライトのステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[StripLightStatusBody]: Device status response. + SBDeviceStatusResponse[StripLightStatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[StripLightStatusBody]) def color_bulb_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[ColorBulbStatusBody]: + """ + Get the status of a SwitchBot Color Bulb. + SwitchBotカラー電球のステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[ColorBulbStatusBody]: Device status response. + SBDeviceStatusResponse[ColorBulbStatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[ColorBulbStatusBody]) def humidifier_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[HumidifierStatusBody]: + """ + Get the status of a SwitchBot Humidifier. + SwitchBot加湿器のステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[HumidifierStatusBody]: Device status response. + SBDeviceStatusResponse[HumidifierStatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[HumidifierStatusBody]) def hub2_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[Hub2StatusBody]: + """ + Get the status of a SwitchBot Hub 2. + SwitchBotハブ2のステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[Hub2StatusBody]: Device status response. + SBDeviceStatusResponse[Hub2StatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[Hub2StatusBody]) def circulator_fan_get_device_status(self: SwitchBotClientProtocol | Self, device_id: str) -> SBDeviceStatusResponse[CirculatorFanStatusBody]: + """ + Get the status of a SwitchBot Circulator Fan. + SwitchBotサーキュレーターのステータスを取得する。 + + Args: + device_id (str): Device ID to query. + device_id (str): クエリするデバイスのID。 + + Returns: + SBDeviceStatusResponse[CirculatorFanStatusBody]: Device status response. + SBDeviceStatusResponse[CirculatorFanStatusBody]: デバイスステータスのレスポンス。 + """ return self._get_device_status_typed(device_id, SBDeviceStatusResponse[CirculatorFanStatusBody]) diff --git a/examples/switchbot/switchbot_client/switchbot_models.py b/examples/switchbot/switchbot_client/switchbot_models.py index 2f2819a..dd9ea48 100644 --- a/examples/switchbot/switchbot_client/switchbot_models.py +++ b/examples/switchbot/switchbot_client/switchbot_models.py @@ -6,122 +6,174 @@ class ListDeviceBody(BaseModel): - deviceId: str # Device ID - deviceName: str # Device name - deviceType: str # Device type, e.g., MeterPro(CO2) - hubDeviceId: str # Device's parent hub ID - # enabledCloudService: bool # Cloud service status + """ + Model representing a SwitchBot device in the device list. + デバイスリストに表示されるSwitchBotデバイスを表すモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceName: str # Device name / デバイス名 + deviceType: str # Device type, e.g., MeterPro(CO2) / デバイスタイプ（例：MeterPro(CO2)） + hubDeviceId: str # Device's parent hub ID / 親ハブのデバイスID + # enabledCloudService: bool # Cloud service status / クラウドサービスの状態 class ListDeviceBodyRoot(BaseModel): - deviceList: list[ListDeviceBody] - # infraredRemoteList: list[ListDeviceBody] + """ + Root model containing the list of SwitchBot devices. + SwitchBotデバイスのリストを含むルートモデル。 + """ + deviceList: list[ListDeviceBody] # List of devices / デバイスのリスト + # infraredRemoteList: list[ListDeviceBody] # List of infrared devices / 赤外線デバイスのリスト class SBListDeviceResponse(BaseModel): - statusCode: int # HTTP status code of the response - message: str # Response message or error description - body: ListDeviceBodyRoot + """ + Response model for the list devices API endpoint. + デバイス一覧取得APIエンドポイントのレスポンスモデル。 + """ + statusCode: int # HTTP status code of the response / レスポンスのHTTPステータスコード + message: str # Response message or error description / レスポンスメッセージまたはエラー説明 + body: ListDeviceBodyRoot # Response body containing device list / デバイスリストを含むレスポンスボディ class SBDeviceStatusResponse[T](BaseModel): - statusCode: int # HTTP status code of the response - message: str # Response message or error description - body: T # Body of the response containing device-specific information + """ + Generic response model for device status API endpoints. + デバイスステータスAPIエンドポイントの汎用レスポンスモデル。 + """ + statusCode: int # HTTP status code of the response / レスポンスのHTTPステータスコード + message: str # Response message or error description / レスポンスメッセージまたはエラー説明 + body: T # Body of the response containing device-specific information / デバイス固有の情報を含むレスポンスボディ class MeterProCO2StatusBody(BaseModel): - deviceId: str # Device ID - deviceType: str # Device type, e.g., MeterPro(CO2) - hubDeviceId: str # Device's parent hub ID - battery: int # Current battery level, from 0 to 100 - version: str # Current firmware version, e.g., V4.2 - temperature: float # Temperature in Celsius - humidity: int # Humidity percentage - CO2: int # CO2 concentration in parts per million (ppm), from 0 to 9999 + """ + Status model for SwitchBot Meter Pro CO2 device. + SwitchBotメータープロCO2デバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceType: str # Device type, e.g., MeterPro(CO2) / デバイスタイプ（例：MeterPro(CO2)） + hubDeviceId: str # Device's parent hub ID / 親ハブのデバイスID + battery: int # Current battery level, from 0 to 100 / バッテリー残量（0-100） + version: str # Current firmware version, e.g., V4.2 / 現在のファームウェアバージョン（例：V4.2） + temperature: float # Temperature in Celsius / 温度（摂氏） + humidity: int # Humidity percentage / 湿度（%） + CO2: int # CO2 concentration in parts per million (ppm), from 0 to 9999 / CO2濃度（ppm、0-9999） class BotStatusBody(BaseModel): - deviceId: str # Device ID - deviceType: str # Device type, e.g., Bot - power: str # ON/OFF state - battery: int # Current battery level, from 0 to 100 - version: str # Current firmware version, e.g., V6.3 - deviceMode: str # Mode: pressMode, switchMode, or customizeMode - hubDeviceId: str # Device's parent Hub ID + """ + Status model for SwitchBot Bot device. + SwitchBotボットデバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceType: str # Device type, e.g., Bot / デバイスタイプ（例：Bot） + power: str # ON/OFF state / 電源状態（ON/OFF） + battery: int # Current battery level, from 0 to 100 / バッテリー残量（0-100） + version: str # Current firmware version, e.g., V6.3 / 現在のファームウェアバージョン（例：V6.3） + deviceMode: str # Mode: pressMode, switchMode, or customizeMode / モード：pressMode、switchMode、またはcustomizeMode + hubDeviceId: str # Device's parent Hub ID / 親ハブのデバイスID class MotionSensorStatusBody(BaseModel): - deviceId: str # Device ID - deviceType: str # Device type, e.g., Motion Sensor - hubDeviceId: str # Device's parent Hub ID - battery: int # The current battery level, from 0 to 100 - version: str # The current firmware version, e.g., V4.2 - moveDetected: bool # Determines if motion is detected - brightness: str # The ambient brightness, bright or dim + """ + Status model for SwitchBot Motion Sensor device. + SwitchBotモーションセンサーデバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceType: str # Device type, e.g., Motion Sensor / デバイスタイプ（例：Motion Sensor） + hubDeviceId: str # Device's parent Hub ID / 親ハブのデバイスID + battery: int # The current battery level, from 0 to 100 / バッテリー残量（0-100） + version: str # The current firmware version, e.g., V4.2 / 現在のファームウェアバージョン（例：V4.2） + moveDetected: bool # Determines if motion is detected / モーション検知状態 + brightness: str # The ambient brightness, bright or dim / 周囲の明るさ（brightまたはdim） class PlugMiniJPStatusBody(BaseModel): - deviceId: str # Device ID - deviceType: str # Device type, e.g., Plug Mini (JP) - hubDeviceId: str # Device's parent Hub ID - voltage: float # The voltage of the device, measured in Volts - version: str # The current BLE and Wi-Fi firmware version, e.g., V3.1-6.3 - weight: float # The power consumed in a day, measured in Watts - electricityOfDay: int # The duration used in a day, measured in minutes - electricCurrent: float # The current of the device, measured in Amps + """ + Status model for SwitchBot Plug Mini (JP) device. + SwitchBotプラグミニ（JP）デバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceType: str # Device type, e.g., Plug Mini (JP) / デバイスタイプ（例：Plug Mini (JP)） + hubDeviceId: str # Device's parent Hub ID / 親ハブのデバイスID + voltage: float # The voltage of the device, measured in Volts / デバイスの電圧（V） + version: str # The current BLE and Wi-Fi firmware version, e.g., V3.1-6.3 / 現在のBLEとWi-Fiファームウェアバージョン（例：V3.1-6.3） + weight: float # The power consumed in a day, measured in Watts / 1日の消費電力（W） + electricityOfDay: int # The duration used in a day, measured in minutes / 1日の使用時間（分） + electricCurrent: float # The current of the device, measured in Amps / デバイスの電流（A） class StripLightStatusBody(BaseModel): - deviceId: str # Device ID - deviceType: str # Device type, e.g., Strip Light - hubDeviceId: str # Device's parent Hub ID - power: str # ON/OFF state - version: str # The current BLE and Wi-Fi firmware version, e.g., V3.1-6.3 - brightness: int # The brightness, range from 1 to 100 - color: str # The color value, RGB "255:255:255" + """ + Status model for SwitchBot Strip Light device. + SwitchBotストリップライトデバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceType: str # Device type, e.g., Strip Light / デバイスタイプ（例：Strip Light） + hubDeviceId: str # Device's parent Hub ID / 親ハブのデバイスID + power: str # ON/OFF state / 電源状態（ON/OFF） + version: str # The current BLE and Wi-Fi firmware version, e.g., V3.1-6.3 / 現在のBLEとWi-Fiファームウェアバージョン（例：V3.1-6.3） + brightness: int # The brightness, range from 1 to 100 / 明るさ（1-100） + color: str # The color value, RGB "255:255:255" / RGB色値（"255:255:255"） class ColorBulbStatusBody(BaseModel): - deviceId: str # Device ID - deviceType: str # Device type, e.g., Color Bulb - hubDeviceId: str # Device's parent Hub ID - power: str # ON/OFF state - brightness: int # Brightness value, range from 1 to 100 - version: str # Current BLE and Wi-Fi firmware version, e.g., V3.1-6.3 - color: str # RGB color value, e.g., "255:255:255" - colorTemperature: int # Color temperature, range from 2700 to 6500 + """ + Status model for SwitchBot Color Bulb device. + SwitchBotカラー電球デバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceType: str # Device type, e.g., Color Bulb / デバイスタイプ（例：Color Bulb） + hubDeviceId: str # Device's parent Hub ID / 親ハブのデバイスID + power: str # ON/OFF state / 電源状態（ON/OFF） + brightness: int # Brightness value, range from 1 to 100 / 明るさ（1-100） + version: str # Current BLE and Wi-Fi firmware version, e.g., V3.1-6.3 / 現在のBLEとWi-Fiファームウェアバージョン（例：V3.1-6.3） + color: str # RGB color value, e.g., "255:255:255" / RGB色値（例："255:255:255"） + colorTemperature: int # Color temperature, range from 2700 to 6500 / 色温度（2700-6500） class HumidifierStatusBody(BaseModel): - deviceId: str # Device ID - deviceType: str # Device type, e.g., Humidifier - power: str # ON/OFF state - humidity: int # Humidity percentage - temperature: float # Temperature in Celsius - nebulizationEfficiency: int # Atomization efficiency percentage - auto: bool # Auto Mode status - childLock: bool # Child lock status - sound: bool # Mute status - lackWater: bool # Empty water tank status + """ + Status model for SwitchBot Humidifier device. + SwitchBot加湿器デバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceType: str # Device type, e.g., Humidifier / デバイスタイプ（例：Humidifier） + power: str # ON/OFF state / 電源状態（ON/OFF） + humidity: int # Humidity percentage / 湿度（%） + temperature: float # Temperature in Celsius / 温度（摂氏） + nebulizationEfficiency: int # Atomization efficiency percentage / 霧化効率（%） + auto: bool # Auto Mode status / 自動モード状態 + childLock: bool # Child lock status / チャイルドロック状態 + sound: bool # Mute status / 消音状態 + lackWater: bool # Empty water tank status / 水切れ状態 class Hub2StatusBody(BaseModel): - deviceId: str # Device ID - deviceType: str # Device type, e.g., Hub 2 - hubDeviceId: str # Equivalent to device ID - temperature: float # Temperature in Celsius - lightLevel: int # Level of ambient light, range from 1 to 20 - version: str # Current firmware version, e.g., V4.2 - humidity: int # Humidity percentage + """ + Status model for SwitchBot Hub 2 device. + SwitchBotハブ2デバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceType: str # Device type, e.g., Hub 2 / デバイスタイプ（例：Hub 2） + hubDeviceId: str # Equivalent to device ID / デバイスIDと同じ + temperature: float # Temperature in Celsius / 温度（摂氏） + lightLevel: int # Level of ambient light, range from 1 to 20 / 周囲の明るさレベル（1-20） + version: str # Current firmware version, e.g., V4.2 / 現在のファームウェアバージョン（例：V4.2） + humidity: int # Humidity percentage / 湿度（%） class CirculatorFanStatusBody(BaseModel): - deviceId: str # Device ID - deviceName: str # Device name - deviceType: str # Device type, e.g., Circulator Fan - mode: str # Fan mode: direct, natural, sleep, or baby - version: str # Current firmware version, e.g., V4.2 - power: str # ON/OFF state - nightStatus: int # Nightlight status, off or mode 1/2 - oscillation: str # Horizontal oscillation state - verticalOscillation: str # Vertical oscillation state - fanSpeed: int # Fan speed, range from 1 to 100 + """ + Status model for SwitchBot Circulator Fan device. + SwitchBotサーキュレーターデバイスのステータスモデル。 + """ + deviceId: str # Device ID / デバイスID + deviceName: str # Device name / デバイス名 + deviceType: str # Device type, e.g., Circulator Fan / デバイスタイプ（例：Circulator Fan） + mode: str # Fan mode: direct, natural, sleep, or baby / ファンモード：direct、natural、sleep、またはbaby + version: str # Current firmware version, e.g., V4.2 / 現在のファームウェアバージョン（例：V4.2） + power: str # ON/OFF state / 電源状態（ON/OFF） + nightStatus: int # Nightlight status, off or mode 1/2 / ナイトライト状態（オフまたはモード1/2） + oscillation: str # Horizontal oscillation state / 水平首振り状態 + verticalOscillation: str # Vertical oscillation state / 垂直首振り状態 + fanSpeed: int # Fan speed, range from 1 to 100 / ファン速度（1-100）